skillfire

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.

Quickstart

npx skillfire ./path/to/your-skill

COLLISION 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).

Fix it — the Description-Doctor

npx skillfire ./my-skill --doctor

Description-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.

Commands

| 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 |

Flags

| 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) |

Score badge

npx skillfire ./my-skill --badge

![skillfire](https://img.shields.io/badge/skillfire-47%2F100-yellow)

Drop the markdown into your skill's README — the score is reproducible because it's pinned to a population version.

How it works

• 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 (real description, 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).

Limitations (honest)

• The offline metric is a lexical proxy — overlap is not the same as real routing. --verify exists 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 Skill tool_use from the stream-json trace); the trace shape may differ on other versions/agents.

Development

npm install
npm test          # vitest
npm run typecheck # tsc --noEmit
npm run build     # bundle to dist/ (tsup)
npm run skillfire -- ./examples/sample-commit-skill

Requires Node 18+ for the published CLI; the dev workflow (running TypeScript directly) needs Node 22.6+.

License

MIT