A routine checkup for your agent's toolbox, run at the point of usage.
Every skill you add can be individually well-written and highly vetted and still hurt you in aggregate: it's the combination of everything the agent can reach for that decides how well it routes, and that's a failure the model can't self-diagnose, because each skill looks fine on its own. As the toolbox grows you have no signal for when the mix has started to degrade. This is that signal — a checkup you re-run as you add things.
It focuses on one question about your Claude Code Agent Skills (SKILL.md
files): routing entropy — do any of them overlap enough that the model's
choice of which to trigger becomes a coin flip? The mechanical CLI discovers
and inventories your skills; the judgment about which ones actually compete
for the same request happens in the agent (see the plugin section), which
reads the descriptions and bodies and reasons about intent directly.
It deliberately does not lint individual skills (description wording, body size, trigger phrasing) or cap how many you can have — a well-differentiated set of many skills routes fine, and single-skill quality is already covered by other tools. This one is only about the collection-level overlap that no individual skill can reveal.
The generic name is deliberate — an agent toolbox checkup implies auditing the whole toolbox an agent reaches for (skills, tools, MCP servers). Today it only audits Claude Code Skills; treat the broader name as room to grow into, not a claim about what's implemented right now.
go build -o bin/agent-toolbox-checkup ./cmd/agent-toolbox-checkup
./bin/agent-toolbox-checkupBy default it looks under <cwd>/.claude/skills and ~/.claude/skills.
Add more directories as positional arguments or with --path (repeatable)
— including a specific installed plugin's skills/ directory, if you want
to inventory one standalone.
./bin/agent-toolbox-checkup ./some/other/skills --jsonFlags:
| Flag | Default | Description |
|---|---|---|
--json |
false |
Emit machine-readable JSON instead of a table |
--path |
— | Extra directory to scan (repeatable) |
--project-dir |
cwd | Override the project directory |
--home-dir |
$HOME |
Override the user home directory |
--session-skills |
false |
Also fetch the live session's full skill set (built-ins included) via a headless claude probe |
Exit codes: 0 success, 2 a usage or I/O error. The CLI only reports an
inventory, so it never exits non-zero on the contents of your skills.
The CLI only does the parts that are genuinely mechanical: discovery, frontmatter/YAML parsing, and inventorying what it finds. It does not attempt overlap detection — an earlier version tried a lexical (TF-IDF) prefilter for that, but testing showed it missed genuinely duplicate skills described in different words while flagging unrelated skills that merely shared boilerplate phrasing. Judging whether two skills actually compete for the same request needs to read full skill bodies and reason about intent, which the plugin layer below does directly instead.
The file scan only sees skills that exist as SKILL.md files. It can't see
Claude Code's built-in skills (compiled into the binary, no file on disk)
or other loaded plugins — yet those still compete for routing. With
--session-skills, the CLI briefly runs claude in headless mode and reads
the skill list from its startup event, adding a session_skills block to the
output: a deterministic list of every skill loaded in a live session,
built-ins included.
It's a grounding signal, not a full picture. It's names only — built-in
bodies aren't on disk, so it tells you which skills compete, and the judging
agent supplies what each does from its own knowledge. It requires the
claude CLI on PATH and authenticated; if the probe fails, session_skills
reports available: false and the scan still succeeds. The list reflects a
fresh headless session in the current directory, which can differ from a
session started with custom plugins or settings.
This repo is also a plugin: it bundles the CLI with an agent-toolbox-checkup
skill, invoked as /agent-toolbox-checkup (a manual, user-invoked skill — it
never auto-triggers, so it stays out of the routing pool it audits). Inside a
live agent session, it runs agent-toolbox-checkup --json --session-skills to
inventory the skills, then reads every scanned skill's description in a single
pass and identifies which ones plausibly compete for the same kind of request
— using the agent's own reasoning directly, no lexical prefilter, no embeddings
API or extra API key required. It reports only actionable routing risks (each
with a one-line fix), and cross-checks the scanned skills against everything
else live in the session — built-ins and other plugins that have no file for
the CLI to find but still compete for routing.
To try it locally, point Claude Code at this repo as a plugin directory — during development, the pattern documented for testing Claude Code plugin skills is:
claude --plugin-dir /path/to/agent-toolbox-checkup(Verify this flag against your current Claude Code version's docs — plugin
loading flags can change between releases.) Once loaded, run
/agent-toolbox-checkup in a session.
First run builds the CLI via scripts/build.sh (requires a Go toolchain on
PATH) and caches the binary at bin/agent-toolbox-checkup.
go build ./...
go vet ./...
go test ./...