{"id":"cb94c3f6-01bb-47f3-8f03-d896dc5d513a","slug":"iosrxwy-skillint","kind":"skill","name":"skillint","summary":"Static analysis for AI agent skills. Audit SKILL.md and AGENTS.md used by Codex, Cursor, and Claude Code.","owner":"iosrxwy","repoUrl":"https://github.com/iosrxwy/skillint","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-08-16T09:59:29.000Z","addedAt":"2026-10-14T11:42:55.553Z","logoUrl":"https://avatars.githubusercontent.com/u/184130225?u=a7c54f67c7ed968216c830dc1cf612f09e4292fa&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["ai-agents","anthropic","claude","claude-code","cli","codex","cursor","developer-tools"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T21:50:49.307Z","sample":false,"url":"https://conduits.dev/tools/iosrxwy-skillint","language":"TypeScript","transports":["stdio"],"install":{"npm":"skillint"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"

\n English ·\n 简体中文 ·\n 繁體中文 ·\n 日本語 ·\n 한국어 ·\n Español ·\n Français ·\n Deutsch ·\n Português ·\n Русский\n

\n\n

\n \"skillint\"\n

\n\n

skillint

\n\n

eslint for SKILL.md

\n\n

\n Audit SKILL.md, AGENTS.md, and editor rules used by\n Codex, Cursor, Claude Code, Grok, Gemini, Copilot, and other agents.\n Separate copied installs from real conflicts, diagnose broken metadata, and estimate catalog size before it becomes agent context.\n

\n\n

\n \"CI\"\n \"npm\n \"MIT\"\n \"issues\"\n \"stars\"\n

\n\n

\n \"skillint\n

\n\n```bash\nnpx skillint\n```\n\nIn a terminal this runs a guided checkup: it scans every agent's skills, explains the problems in plain language (localized, including Chinese), and offers numbered fixes — recycle-bin cleanup, security findings, symlink sharing, or the interactive UI. Every write is undoable with `skillint restore`. Without a TTY (CI, pipes) the same command prints the classic scan inventory.\n\n

\n \"skillint\n

\n\nThe audit path is static and read-only: scanned skills are parsed as text and never executed. `scan`, `map`, `doctor`, `audit`, and `tokens` do not modify the catalog. `prune --apply`, `trash`, `link --apply`, and `update --apply` are explicit, undoable writes.\n\n## What it solves\n\n- **Catalog sprawl** — inventory global and project skills and rules across Codex, Cursor, Claude Code, Grok, Gemini, Copilot, OpenCode, Windsurf, Kiro, Cline, and more\n- **Agent-specific resolution** — map Cursor, Claude Code, or Codex resources as effective, coexisting, shadowed, conditional, or unknown using each agent's documented discovery semantics\n- **Duplicate noise** — report cross-agent installs as `synced-copy` info while keeping same-agent-family name collisions as errors\n- **Broken skill specs** — diagnose missing, unclosed, or invalid YAML frontmatter; required fields; naming issues; oversized bodies; and long instruction files\n- **Skill supply chain** — audit installed skills for `curl | bash`, leaked tokens, prompt-injection wording, permission bypass flags, and destructive commands, with file:line output\n- **Unknown context size** — compare metadata and body size using explicit estimates (`characters / 4`), not exact tokenizer cost or a claim about what any model loaded\n- **CI drift** — emit GitHub Action annotations and summaries, write Markdown/JSON reports, and enforce `--fail-on`, `--fail-under`, or shared config thresholds\n- **Fast local scan** — use concurrent, bounded reads, follow symlinked skill roots without loops, and scaffold a valid starter with `skillint init`\n\n---\n\n## Why this exists\n\nCoding agents can discover instructions from many global and project directories. Once those directories accumulate copies, the catalog becomes hard to reason about:\n\n- the same skill copied across several agents makes inventory noisy\n- duplicate names inside one agent family create real ambiguity\n- malformed or missing metadata makes skill discovery unreliable\n- oversized bodies and always-on rules hide potential context cost\n\n

\n \"Cursor,\n

\n\n`skillint` turns those directories into an actionable audit: inventory, diagnostics, a 0–100 health score, estimated size, and an undoable cleanup plan. It never deletes files — cleanup means quarantine plus `skillint restore`.\n\n## Install\n\nRequires Node.js 22.12 or later.\n\n```bash\nnpx skillint scan\n```\n\nNo global install is required. To keep the command on your PATH:\n\n```bash\nnpm install --global skillint\nskillint scan\n```\n\n## Quick start\n\n```bash\nnpx skillint scan # inventory + estimated size + health bar\nnpx skillint map --agent cursor # Cursor's catalog for this directory\nnpx skillint doctor # diagnostics\nnpx skillint audit # security scan: curl|bash, leaked keys, injection\nnpx skillint ui # interactive terminal UI over everything\nnpx skillint init code-review # scaffold a SKILL.md that passes doctor\nnpx skillint tokens # compact estimates\nnpx skillint prune # cleanup plan (safe items -> undoable trash)\nnpx skillint prune --apply # move all safe items to ~/.skillint/trash\nnpx skillint restore # undo the last trash batch\nnpx skillint fix --apply # resurrect skills with broken frontmatter\nnpx skillint adopt # match orphan skills to known repos\nnpx skillint update --apply # batch-update git + adopted skills\nnpx skillint report --html # self-contained HTML dashboard\nnpx skillint badge # SVG health badge for your README\nnpx skillint link # share identical copies across agents\nnpx skillint update # check git-backed skills for upstream updates\nnpx skillint report --out out.md # Markdown audit\n```\n\nScope control:\n\n```bash\nnpx skillint scan -g # user-level dirs only\nnpx skillint scan -p # current project only\nnpx skillint doctor ./skills # one directory\nnpx skillint doctor --json --fail-on error\nnpx skillint doctor --fail-under 80 # fail CI when health drops below 80\n```\n\nAudit commands never mutate or delete scanned skill files. `report` creates only the requested report, and `init` never overwrites an existing `SKILL.md`. `prune --apply`, `trash`, `restore`, `link --apply`, and `update --apply` are explicit write operations.\n\n## Cleanup — no `rm`, ever\n\nskillint never deletes anything. Cleanup moves items into a quarantine at `~/.skillint/trash//` with a manifest, and `skillint restore` moves the last batch back:\n\n```bash\nnpx skillint prune -g # plan: what to trash and why\nnpx skillint prune -g --apply # move all safe items to the trash\nnpx skillint restore # changed your mind? undo the batch\nnpx skillint trash # trash specific items by hand\n```\n\n| Bucket | Meaning |\n| --- | --- |\n| **safe** | Backups, nested copies, same-catalog duplicates. Trashed by `--apply`. |\n| **review** | Oversized or broken metadata. Trim or fix; never touched by `--apply`. |\n\n`prune` only targets junk inside one catalog. It does **not** touch the same skill installed across Cursor, Claude, Codex, and Grok — each agent reads its own directory; share those with `skillint link` instead.\n\n## Interactive UI\n\n`skillint ui` puts the whole engine behind a lazygit-style terminal UI — no flags to remember:\n\n```bash\nnpx skillint ui -g\n```\n\nFive tabs with live counts: **issues** (doctor findings), **audit** (security scan), **cleanup** (prune plan), **links** (cross-agent sharing), **largest** (token hogs). Navigate with `1-5` and `j`/`k`, press `c` to copy the suggested command for the selected row, `r` to rescan, `q` to quit. The UI is read-only and needs no extra dependencies — commands are copied to your clipboard, never executed.\n\n## Scan a repo before you install it\n\nSkills are instructions your agent will follow. Check a repository *before* `npx skills add`:\n\n```bash\nnpx skillint scan-remote owner/repo\n```\n\nShallow-clones to a cache, pattern-scans every `SKILL.md` (plus shell scripts and instruction files), and returns a verdict — `clean`, `caution`, or `risky` — with file:line receipts. Exit code 1 on risky, so it drops straight into CI. Nothing from the repo is ever executed.\n\n[`OBSERVATORY.md`](./OBSERVATORY.md) tracks popular public skill repos with this scanner and refreshes weekly via GitHub Actions.\n\n## Use it from your agent (MCP)\n\n`skillint mcp` runs a zero-dependency MCP server over stdio, so Claude Code, Cursor, or any MCP client can call skillint natively — ask \"audit my skills\" and the agent gets structured results instead of improvising grep:\n\n```json\n{\n \"mcpServers\": {\n \"skillint\": { \"command\": \"npx\", \"args\": [\"-y\", \"skillint\", \"mcp\"] }\n }\n}\n```\n\nTools exposed: `skill_checkup`, `skill_audit`, `skill_cleanup_plan`, and `scan_skill_repo` (pre-install repo vetting). All read-only; cleanup returns commands for the human to run.\n\n## Security audit\n\nSkills are markdown you installed from the internet, and agents follow them. `audit` scans every installed skill for dangerous patterns — before an agent acts on one:\n\n```bash\nnpx skillint audit -g\nnpx skillint audit --fail-on error # gate CI\n```\n\n| Rule | Flags |\n| --- | --- |\n| `remote-exec` | `curl \\| bash`, `irm \\| iex` install pipes |\n| `credential` | AWS/GitHub/Stripe/Slack/OpenAI token formats, private key blocks |\n| `prompt-injection` | \"ignore previous instructions\", \"hide this from the user\" |\n| `exfiltration` | instructions to send secrets or env data to a URL |\n| `permission-bypass` | `--dangerously-skip-permissions`, `--yolo`, `--no-sandbox` |\n| `sensitive-file` | `~/.ssh`, `.aws/credentials`, keychain reads |\n| `destructive` | `rm -rf ~`, fork bombs |\n\nDocumentation placeholders (`sk-xxxx…`, `AKIA…EXAMPLE`) are filtered out. Findings include `path:line` and the matching excerpt; in GitHub Actions they surface as line-level annotations. The scan is static and read-only — nothing is executed.\n\n## Skill manager\n\nIdentical copies across agents should be **shared**, not deleted:\n\n```bash\nnpx skillint link -g # dry run\nnpx skillint link -g --apply # replace identical copies with symlinks\nnpx skillint adopt -g # fingerprint-match orphans to known repos\nnpx skillint update -g # check git checkouts + adopted skills\nnpx skillint update -g --apply # batch-update everything that is behind\n```\n\n`link` keeps one canonical copy (preferring `~/.agents/skills`) and points the other agent directories at it. `adopt` solves the orphan problem: marketplace copies have no recorded upstream, so `adopt` hashes every installed skill, matches it against known public repos (Anthropic skills, Vercel agent-skills, superpowers; add more with `--repo`), and records the provenance. From then on `skillint update` batch-checks them and `--apply` batch-updates them — with the old version quarantined, so `skillint restore` still undoes it. Name-only matches are listed for human review, never auto-updated.\n\n## Fix broken skills\n\nSome installed skills are invisible to agents because their metadata is broken — often just a trailing space after `---`:\n\n```bash\nnpx skillint fix # dry run: shows recovered names/descriptions\nnpx skillint fix --apply # rewrite; originals go to the trash first\n```\n\n`fix` recovers frontmatter written without `---` markers, normalizes sloppy delimiters, and drafts missing names (from the folder) and descriptions (from the first paragraph). The whole engine also *tolerates* sloppy delimiters when scanning, so scores reflect reality: on the machine this was built against, that tolerance alone revived 8 \"dead\" skills and raised the health score from 10 to 42.\n\n## Roast mode\n\n```bash\nnpx skillint roast --card\n```\n\n> You installed 1,658 skills. Your agent doesn't lack skills — it lacks attention.\n> Loading everything would take ~27 full context windows. That's not a library, that's a mortgage for your agent.\n> 67 skills contain download-and-run commands or worse. Giving random markdown shell access — bold strategy.\n\nRead-only, localized (English and Chinese), and `--card` writes a shareable SVG scorecard. Post yours.\n\n## HTML dashboard and badge\n\n```bash\nnpx skillint report --html # skillint-report.html, single file, no dependencies\nnpx skillint badge # skills-health.svg + a ready-to-paste embed line\n```\n\nThe dashboard has a health gauge, per-source bars, and filterable findings/security/cleanup tables — send it to a teammate or attach it to a PR. The badge is shields-style and score-colored for READMEs and dotfiles repos.\n\n## Agent-aware map\n\n`scan` is a broad physical inventory across many tools. Its token totals describe files found on disk; they are not an effective catalog and do not claim that an agent or model loaded every file.\n\n`map` applies one agent adapter to a working directory:\n\n```bash\nnpx skillint map [cwd] --agent cursor\nnpx skillint map [cwd] --agent claude\nnpx skillint map [cwd] --agent codex\nnpx skillint map . --agent codex --json\n```\n\n

\n \"Light\n

\n\nJSON output has `schemaVersion: 1` and includes logical and real paths, scope, resource role, source kind, official documentation URL, visibility, and resolution.\n\n- `effective` — statically part of the current instruction chain or unconditionally loaded\n- `coexisting` — official semantics keep same-name resources available as distinct entries\n- `shadowed` — an official precedence rule selects another observed resource\n- `conditional` — availability depends on file/directory context, globs, manual invocation, or the agent's relevance decision\n- `unknown` — behavior is undocumented, managed outside observable roots, or depends on trust/configuration that `skillint` did not parse\n\nThe map deliberately does not predict whether a model will trigger a skill. Cursor same-name skill precedence is reported as unknown rather than guessed. Claude's personal/project precedence and directory-qualified skills are modeled. Codex same-name skills coexist, and `AGENTS.override.md` shadows `AGENTS.md` only at the same directory level. Managed and bundled sources are listed as limitations instead of fabricated files.\n\nAdapter semantics follow the current official docs for [Cursor skills](https://cursor.com/docs/skills) and [rules](https://cursor.com/docs/rules), [Claude Code skills](https://code.claude.com/docs/en/skills) and [memory](https://code.claude.com/docs/en/memory), and [Codex skills](https://developers.openai.com/codex/skills) and [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md).\n\n## Example\n\nFrom a developer machine with a large local skill library:\n\n

\n \"Light\n

\n\n`skillint doctor` on the same machine: **271 findings**, including 157 oversized bodies, 13 same-family duplicate names, and 54 cross-agent synced copies reported as informational rather than errors.\n\nThe ~3.43M-token figure is a sizing estimate for the discovered files, not a claim that any agent loads the entire catalog.\n\n## What `scan` inventories\n\nThese are physical inventory roots retained for cross-agent auditing, including compatibility and legacy locations. Use `map` when you need one agent's current effective catalog semantics.\n\n| Agent | Global | Project |\n| --- | --- | --- |\n| Cursor | `~/.cursor/skills`, `~/.cursor/rules` | `.cursor/skills`, `.cursor/rules` |\n| Claude Code | `~/.claude/skills`, `~/.claude/rules` | `.claude/skills`, `.claude/rules` |\n| Codex | `~/.codex/skills`, `~/.codex/rules`, `~/.codex/prompts` | `.codex/skills`, `.codex/rules`, `.codex/prompts` |\n| Grok | `~/.grok/skills`, `~/.grok/plugins` | `.grok/skills`, `.grok/plugins` |\n| Gemini / Antigravity | `~/.gemini/skills`, `~/.antigravity/skills` | `.gemini/skills`, `.antigravity/skills` |\n| GitHub Copilot | `~/.copilot/skills` | `.github/skills`, `.github/agents`, `.github/instructions` |\n| OpenCode | `~/.config/opencode/skills` | `.opencode/skills` |\n| Windsurf | `~/.codeium/windsurf/skills`, `~/.windsurf/skills` | `.windsurf/skills` |\n| Kiro | `~/.kiro/skills`, `~/.kiro/steering` | `.kiro/skills`, `.kiro/steering` |\n| Cline / Continue | `~/.cline/skills`, `~/.continue/skills` | `.cline/skills`, `.continue/skills` |\n| Shared agents | `~/.agents/skills` | `.agents/skills`, `skills/` |\n| Others | Factory, OpenClaw, Hermes, Qoder, CodeBuddy, Goose, Amp, Roo, Trae, Crush, Pi, cc-switch | matching `.tool/skills` folders |\n\nAlso reads project instruction files: `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `GEMINI.md`, `GROK.md`, `CODEX.md`, `COPILOT.md`, `WINDSURF.md`, `OPENCODE.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.github/copilot-instructions.md`.\n\nToken counts are **physical inventory estimates**, not a vendor tokenizer or a prediction of model context. Use them to compare size, not to bill APIs.\n\n## GitHub Action\n\n```yaml\nname: skillint\non: [push, pull_request]\njobs:\n audit:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: iosrxwy/skillint@main\n with:\n fail-on: error\n```\n\nFindings show up as pull request annotations. Copies of the same skill across Cursor, Claude, Grok, and other agents are reported as info (`synced-copy`), not as CI-failing duplicates.\n\n## Ignore patterns\n\nCreate `.skillintignore` in the working directory, or pass `--ignore`:\n\n```bash\nskillint doctor --ignore vendor --ignore \"*.bak\"\n```\n\n## Configuration\n\nPut a `skillint.config.json` next to where you run skillint to share ignore patterns and tune the doctor limits:\n\n```json\n{\n \"$schema\": \"https://unpkg.com/skillint@latest/skillint.schema.json\",\n \"ignore\": [\"vendor\", \"*.bak\"],\n \"limits\": {\n \"skillBodyTokens\": 3000,\n \"descriptionMin\": 60\n }\n}\n```\n\nThe schema provides editor completion and catches misspelled settings. Available limits: `skillBodyTokens` (4000), `ruleAlwaysOnTokens` (800), `descriptionMax` (1024), `descriptionMin` (40), `agentsDocLines` (100), `nameMax` (64).\n\n## How it works\n\n```mermaid\nflowchart LR\n A[Physical roots] --> B[discover]\n B --> C[doctor]\n C --> D[health score]\n C --> E[report / JSON / CI]\n B --> F[token budget]\n G[Agent + cwd] --> H[map adapter]\n H --> I[effective / conditional / unknown catalog]\n```\n\nAudit commands never execute scanned skills or modify the catalog. `init` creates a new skill, and `report` writes only the report path you request.\n\n## CI\n\n```yaml\n- run: node dist/cli.js doctor ./skills --fail-on error\n- run: node dist/cli.js report --out skillint-report.md -p\n```\n\nThis repository dogfoods `doctor` on `./skills` in GitHub Actions.\n\n## Use it as an agent skill\n\nThe repo ships a full skill package at `skills/skillint/`:\n\n```bash\nnpx skills add iosrxwy/skillint\n```\n\nThe core `SKILL.md` stays small enough to load on every trigger; the package also bundles a command reference, a security-rule catalog, an MCP setup guide, and worked workflows under `references/` and `examples/` that agents load on demand.\n\n## Development\n\n```bash\nnpm test\nnpm run build\nnode dist/cli.js --help\n```\n\n## Star history\n\nIf skillint told you something about your machine you didn't know, [a star](https://github.com/iosrxwy/skillint) is the best way to say thanks — it keeps the project going.\n\n\n \"Star\n\n\n## License\n\n[MIT](./LICENSE) © 2026 [iosrxwy](https://github.com/iosrxwy)\n"}