The skill collision tester. npx skillfire ./my-skill — will your SKILL.md win the routing race, or get cannibalized by the skills people already have installed?
A skill is routed by its description alone. In a saturated category (the many "commit message" skills, the many "code reviewers"), your new skill's description is a near-duplicate of a pile of existing ones — so when a user types a normal request, the agent's router sees a crowd of near-identical descriptions and may pick someone else's skill, or coin-flip. skillfire measures that collision, offline and deterministically, before you ship.
npx skillfire ./path/to/your-skillCOLLISION REPORT — My Commit Wizard
tested against Commit message generators · 7 skills · population 2026.06-public-v1
Distinctiveness 47/100 contested
Routing race — who the router would plausibly consider:
▸ "write a commit message for my staged changes"
1 ████████████████ 1.00 caveman-commit
2 ████████████████ 1.00 My Commit Wizard ← your skill
3 ████████████░░░░ 0.77 conventional-commit
4 ████████████░░░░ 0.73 git-commit-message
contention 5 (cover ≥0.5) · dead heat 2 · margin 0.00
▸ "commit my changes with a good message"
... 6 skills tie at 0.50 ...
contention 6 (cover ≥0.5) · dead heat 6 · margin 0.00
Near-duplicate incumbents (overlap · shared trigger terms):
0.50 conventional-commit shared: write, git, changes, conventional
0.40 commit shared: staged, following, changes, conventional
Placement: nearest twin conventional-commit (0.50) · worst tied-with 4 · cannibalized on 4/5 prompts
» Collision — your skill is cannibalized by the incumbents above. Run with --doctor to sharpen the description and win its triggers.
Collisions are real in the wild: run skillfire audit ~/.claude/skills on a populated skills folder and you'll find genuine near-duplicates (e.g. grill-me ⇄ grill-with-docs at 1.00, diagnose ⇄ diagnosing-bugs at 0.93).
npx skillfire ./my-skill --doctorDescription-Doctor
before 47/100 "Write a polished git commit message from my staged changes following Conventional Commits, with an optional emoji and the related issue key."
after 100/100 "with an optional emoji and the related issue key."
drop generic: commit, message, changes, conventional, git
» Leading with your distinctive wording — and dropping generic phrasing many skills share — raised distinctiveness from 47 to 100.
The suggestion is measured: every candidate is re-scored through the same engine, so the "after" number is real, not a guess. When nothing helps, it says so rather than inventing a fix.
| Command | What it does |
|---|---|
skillfire <skill> |
Collision report for a single skill against the pinned reference population |
skillfire <skill> --doctor |
Suggest a sharper description with a measured before/after |
skillfire <skill> --badge |
Emit a reproducible README badge (markdown + shields endpoint) |
skillfire <skill> --verify |
Confirm collisions against a real Claude Code agent (stub skills) |
skillfire audit <dir> |
Rank the worst near-duplicate pairs across a directory of skills |
skillfire fix-pr <skill> [--apply] |
Preview (or open) a description-only fix-PR with the measured improvement |
| Flag | Effect |
|---|---|
--against <dir> |
Test against your own installed skills instead of the pinned population |
--category <key> |
Force a category (commit-message, code-review, pr-description) instead of auto-detect |
--json |
Machine-readable report (stable schema, no ANSI) |
--fail-under <n> |
Exit non-zero when distinctiveness is below n (CI gate; default 50) |
npx skillfire ./my-skill --badge
Drop the markdown into your skill's README — the score is reproducible because it's pinned to a population version.
- Offline overlap (default, always on). Routing contention is modeled as coverage — how much of a prompt's weighted intent a description claims — and near-duplication as a weighted overlap coefficient. It's deterministic, needs no API key, and powers the score and badge.
- Verified mode (opt-in,
--verify). Installs the field as stub skills (realdescription, empty body), asks a real Claude Code agent each prompt, and reads the trace to see which skill actually triggered — the same report shape, confirmed against a live router. - Pinned reference population. A versioned set of real, sourced community skill descriptions grouped into saturated categories (sources tracked internally).
- The offline metric is a lexical proxy — overlap is not the same as real routing.
--verifyexists to confirm against a real agent (at the cost of real agent calls). - The pinned population is a curated public seed (v1) sourced from real skills; growing it is ongoing. For your real environment, prefer
--against <your skills dir>. - Verified mode is validated against Claude Code 2.1.x (it reads the
Skilltool_use from the stream-json trace); the trace shape may differ on other versions/agents.
npm install
npm test # vitest
npm run typecheck # tsc --noEmit
npm run build # bundle to dist/ (tsup)
npm run skillfire -- ./examples/sample-commit-skillRequires Node 18+ for the published CLI; the dev workflow (running TypeScript directly) needs Node 22.6+.