Agent skill

The gap

Tools without judgement

Registering an MCP server answers “what can I call”. It does not answer “should I call anything at all”. An agent that knows 29 tools exist will still reach for grep when searching would do, and will crawl a monorepo to answer a question about one file it already has open.

A skill is progressive-disclosure documentation the agent loads on demand. It costs nothing until it is relevant, and it carries the one thing a tool schema cannot: the decision rule.

Graph questions

Who calls this? What breaks if I change it? Where does a request enter? Is this reachable at all? These have no cheap text answer — the answer is spread across files that never mention each other.

Search questions

Where is ThingFactory defined? Show me this function's body. Reading the file is faster and more accurate than crawling, and the skill says so explicitly.

Contents

Three files, no build step

The skill is plain Markdown and ships inside the npm package, so installing it is a copy. It does not depend on dist/.

SKILL.md

Discovery frontmatter, the MCP client config that registers the server, then the crawl-first workflow: index_status before trusting any index, crawl_project once and incrementally, and force after a history rewrite.

reference/tools.md

All 29 tools grouped by the question they answer, with the one argument that matters for each and notes on when not to use them.

reference/edge-semantics.md

confidence, external, and phantom nodes — the three things agents misread most, plus the ways a “missing” edge is legitimate.

The decision rule, verbatim

| Question                                   | Use                        |
| Who calls this method?                     | get_callers                |
| What breaks if I change this?              | impact_analysis            |
| Where is ThingFactory defined?             | plain search - do not crawl|
| Show me the body of this function          | plain file read - do not crawl |

Install

One command

Via the skills CLI

npx skills add nithin554/code-crawler

skills.sh finds skills/code-crawler/ by convention — no registry entry needed — and installs the whole directory, reference/ included. It writes a skills-lock.json you can commit so the rest of the team reproduces the setup. npx skills update refreshes it later.

Non-interactive, or from the npm package

npx skills add nithin554/code-crawler -g -a claude-code -y

npm install @nithin554/code-crawler
# skill lives at:
#   node_modules/@nithin554/code-crawler/skills/code-crawler/

Or copy skills/code-crawler/ wherever your client loads skills from:

Layout	Destination
Personal skills folder	`~/.claude/skills/code-crawler/`
Project-scoped skills	`.claude/skills/code-crawler/`
Plugin or marketplace	`skills/code-crawler/` inside the plugin root

The MCP server still needs registering separately — the skill is judgement, the server is capability, and they are independent. The shortest route is add-mcp:

Register the server, not the skill

npx add-mcp @nithin554/code-crawler --args serve -a cursor

Run it from inside the repository you want indexed: without -g the entry lands in the checkout (.mcp.json, .cursor/mcp.json, .vscode/mcp.json), so each repository carries its own registration and its own index. -a accepts claude-code, cursor, vscode, claude-desktop, codex, opencode, zed and more — npx add-mcp list-agents lists them. -g writes user-level config instead; prefer it only when the client launches the server from your checkout, because a global entry started elsewhere resolves ~/.code-crawler/index.db and every repository then shares that one file. --env CODECRAWLER_DB is optional: the server indexes into <project>/.code-crawler/index.db by default, so pin it — --env CODECRAWLER_DB=/absolute/path/index.db — only to move the file, or when the client's working directory is not the project. Full details in Usage.

Or install the plugin: server + skill together

# Claude Code
/plugin marketplace add nithin554/code-crawler
/plugin install code-crawler@code-crawler

# Copilot CLI
copilot plugin marketplace add nithin554/code-crawler
copilot plugin install code-crawler@code-crawler

The plugin launches npx -y @nithin554/code-crawler serve. Its stdio server runs from the plugin directory, but resolves a project per call — from crawl_project, the client's workspace roots, or the project this session already selected — and writes <project>/.code-crawler/index.db, exactly like the CLI: one database per repository, all from one plugin install. Set CODECRAWLER_DB to pin a single file. The skill is also published to ClawHub as code-crawler (clawhub install code-crawler), where ClawHub bumps the patch digit of the version it already holds, so the skill advances one publish at a time. It is published as a plugin bundle too, versioned by the release tag: v0.1.67 publishes the bundle at 0.1.67. Both publishes are limited to main by the clawhub-publish deployment environment.

Maintenance

It cannot rot

Documentation that is not asserted against code drifts. tests/skill.test.ts parses the skill and fails when it disagrees with the live registry:

Registry parity

The tool table in reference/tools.md must list exactly the tools the server registers — no missing tool, no stale one.

Vocabulary parity

Every edge kind in schema.ts, every confidence band the resolver emits, and every phantom prefix must be documented.