@erclx/aitk 3.16.0 → 3.17.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/bash-script/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bash-script
-description: Generates production Bash scripts with a visual timeline UI, state-based interactive prompts, and strict error handling. Use when asked to write an interactive or human-facing bash or shell script, or a DevOps tool with framed terminal output. Do NOT use for a non-interactive automation, CI, or pipeline script, that is `cli-script`.
+description: Generates production Bash scripts with a visual timeline UI, state-based interactive prompts, and strict error handling. Use when asked for "a human-facing shell tool", an interactive bash script, or a DevOps tool with framed terminal output. Do NOT use for a non-interactive automation, CI, or pipeline script, that is `cli-script`.
 ---
 
 # Bash script

package/claude/skills/ci-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ci-workflow
-description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to write a CI workflow, add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
+description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to "write a CI workflow", add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
 ---
 
 # CI workflow

package/claude/skills/cli-script/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cli-script
-description: Generates non-interactive Bash scripts for automation, CI, and agent-run tasks. Lean functional style with structured logging, strict error handling, and a clean stdout, no interactive UI. Use when asked for an automation script, a CI or cron script, a pipeline helper, or a non-interactive shell script. Do NOT use for a human-facing interactive tool with prompts or a visual timeline UI, that is `bash-script`.
+description: Generates non-interactive Bash scripts for automation, CI, and agent-run tasks. Lean functional style with structured logging, strict error handling, and a clean stdout, no interactive UI. Use when asked for "a non-interactive shell script", an automation script, a CI or cron script, or a pipeline helper. Do NOT use for a human-facing interactive tool with prompts or a visual timeline UI, that is `bash-script`.
 ---
 
 # CLI script

package/claude/skills/create-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-skill
-description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to create a skill, add a skill, or make a new skill.
+description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to "create a skill", add a skill, or make a new skill.
 disable-model-invocation: true
 ---
 

package/claude/skills/create-snippet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-snippet
-description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to create a snippet, add a snippet, write a reusable prompt, or make a new snippet. Do NOT use to edit an existing snippet.
+description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to "create a snippet", add a snippet, write a reusable prompt, or make a new snippet. Do NOT use to edit an existing snippet.
 ---
 
 # Create snippet

package/claude/skills/create-standard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-standard
-description: Creates a new standard file in `standards/`. Use when asked to create a standard, add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
+description: Creates a new standard file in `standards/`. Use when asked to "create a standard", add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
 ---
 
 # Create standard

package/claude/skills/decision-escalate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: decision-escalate
-description: Collects every open decision whose answer turns on the operator's preference, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
+description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
 disable-model-invocation: true
 ---
 

package/claude/skills/git-branch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-branch
-description: Generates and validates conventional branch names. Use for any branch naming or renaming.
+description: Generates and validates conventional branch names. Use for any branch naming or renaming, such as when asked to "name this branch".
 ---
 
 # Git branch

package/claude/skills/git-pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-pr
-description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update.
+description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update, such as when asked to "open a pull request".
 ---
 
 # Git PR

package/claude/skills/git-stage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-stage
-description: Groups staged files by concern and generates one conventional commit per group. Use when staged changes span multiple concerns and need to ship as separate commits. Do NOT use on a single-concern staged set. That is `git-commit`, which also preserves a hunk-level selection this skill's unstage and restage over whole files would widen.
+description: Groups staged files by concern and generates one conventional commit per group. Use when asked to "group these changes into commits", or when staged changes span multiple concerns and need to ship as separate commits. Do NOT use on a single-concern staged set. That is `git-commit`, which also preserves a hunk-level selection this skill's unstage and restage over whole files would widen.
 ---
 
 # Git stage

package/claude/skills/youtube-transcripts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: youtube-transcripts
-description: Fetches a YouTube video transcript with metadata frontmatter into the current repo via `aitk transcripts`. Use when the user pastes a YouTube URL and asks to grab the transcript, pull captions, or save a transcript for context. Do NOT use for downloading the video file, summarizing a transcript that already exists, or non-YouTube links.
+description: Fetches a YouTube video transcript with metadata frontmatter into the current repo via `aitk transcripts`. Use when the user pastes a YouTube URL and asks to "grab the transcript", pull captions, or save a transcript for context. Do NOT use for downloading the video file, summarizing a transcript that already exists, or non-YouTube links.
 ---
 
 # YouTube transcripts

package/docs/agents/audits.md

@@ -22,11 +22,11 @@ aitk audits list --json
 
 ## What it runs
 
-Eighteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
+Nineteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
 
 The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `aitk deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's.
 
-Fifteen of the eighteen read a tree on this disk, the one added by `restated.md` and the one added by `census.md` among them, since the first reads three such trees against each other and the second counts every file in one. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
+Sixteen of the nineteen read a tree on this disk, the one added by `restated.md` and the one added by `census.md` among them, since the first reads three such trees against each other and the second counts every file in one. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
 
 Each is invoked as the CLI the caller is running rather than as a global `aitk`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
 
@@ -57,7 +57,7 @@ The verdict is published as a field as well as an exit code. A reader branching
 
 A per-machine folder that is not on this disk reports as `absent` and moves neither the verdict nor the exit code. Every one of those folders is gitignored, so a fresh clone and every CI run carry none of them, and counting six expected absences as failures pins the verdict at `incomplete` forever. A signal that never changes is one nobody reads after the second time they see it.
 
-Which refusals count as an absence is declared per audit rather than inferred from the corpus alone. A per-machine corpus counts a missing folder. An upstream corpus counts every reason the advisory verb publishes, since each of the three means there is nothing resolved to measure. Several tracked audits override that default too, wherever the corpus not being there is the ordinary state of a target rather than a broken checkout: the secret scan for a project that publishes nothing, the skill corpora and the citation reach check for a project holding no skills tree, and the context audit for a project that adopted none of the folders it measures.
+Which refusals count as an absence is declared per audit rather than inferred from the corpus alone. A per-machine corpus counts a missing folder. An upstream corpus counts every reason the advisory verb publishes, since each of the three means there is nothing resolved to measure. Several tracked audits override that default too, wherever the corpus not being there is the ordinary state of a target rather than a broken checkout: the secret scan for a project that publishes nothing, the skill corpora, the citation reach check, and the routing measure for a project holding no skills tree, and the context audit for a project that adopted none of the folders it measures.
 
 Everything else stays `unmeasured`. That covers a tree git cannot list, which is a broken checkout, and a package declaring no `files` field, where a publish would pack the whole tree and the scan read none of it. Both are a corpus that exists and went unread, so softening either would report a pass over a shipped tree nobody measured.
 

package/docs/agents/commands.md

@@ -48,6 +48,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                 |
 | `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)      |
 | `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one                                    |
+| `aitk claude skills rank`  | Score the shipped catalog's descriptions against a hand-authored case corpus by TF-IDF cosine similarity, reporting rank-one and top-three     |
 | `aitk claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                 |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                             |
@@ -67,27 +68,27 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
 
-| Domain      | Subcommands                                                                                                            |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                 |
-| `snippets`  | `list`, `install`, `sync`, `create`                                                                                    |
-| `standards` | `list`, `<name>`                                                                                                       |
-| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                |
-| `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
-| `demo`      | `compile`, `run`                                                                                                       |
-| `wiki`      | `init`                                                                                                                 |
-| `design`    | `render`                                                                                                               |
-| `slides`    | `render`, `list`                                                                                                       |
-| `tasks`     | `archive`, `validate`                                                                                                  |
-| `intake`    | `list`, `answer`                                                                                                       |
-| `teach`     | `list`, `open`, `resource`, `glossary`                                                                                 |
-| `comments`  | `scan`                                                                                                                 |
-| `context`   | `audit`                                                                                                                |
-| `markdown`  | `audit`                                                                                                                |
-| `secrets`   | `scan`                                                                                                                 |
-| `deps`      | `audit`                                                                                                                |
-| `labels`    | `audit`                                                                                                                |
-| `audits`    | `run`, `list`                                                                                                          |
+| Domain      | Subcommands                                                                                                                           |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                                |
+| `snippets`  | `list`, `install`, `sync`, `create`                                                                                                   |
+| `standards` | `list`, `<name>`                                                                                                                      |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                               |
+| `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |
+| `demo`      | `compile`, `run`                                                                                                                      |
+| `wiki`      | `init`                                                                                                                                |
+| `design`    | `render`                                                                                                                              |
+| `slides`    | `render`, `list`                                                                                                                      |
+| `tasks`     | `archive`, `validate`                                                                                                                 |
+| `intake`    | `list`, `answer`                                                                                                                      |
+| `teach`     | `list`, `open`, `resource`, `glossary`                                                                                                |
+| `comments`  | `scan`                                                                                                                                |
+| `context`   | `audit`                                                                                                                               |
+| `markdown`  | `audit`                                                                                                                               |
+| `secrets`   | `scan`                                                                                                                                |
+| `deps`      | `audit`                                                                                                                               |
+| `labels`    | `audit`                                                                                                                               |
+| `audits`    | `run`, `list`                                                                                                                         |
 
 Common patterns:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/audits/catalog.ts

@@ -1,4 +1,5 @@
 import type { SkillsAuditRefusal } from '@/claude/skills-audit'
+import type { RankRefusal } from '@/claude/skills-rank'
 import type { ReachRefusal } from '@/claude/skills-reach'
 import type { ContextAuditRefusal } from '@/context/audit'
 import type { AuditRefusal } from '@/deps/audit'
@@ -306,6 +307,24 @@ function reachCounts(record: unknown): Record<string, number> | undefined {
   return allOf({ unqualifiedCitations: lengthOf(root.unqualified) })
 }
 
+/**
+ * Reads the routing measure's miss and unmeasurable counts, leaving `rank1`
+ * and `top3` out. Both move in lockstep with `misses` over a fixed-size
+ * corpus, so carrying them would report one movement three times, the same
+ * reasoning `restatedCounts` already takes over its own pair of derived
+ * totals. `unmeasurable` is retained separately, since it counts a defect in
+ * the instrument rather than a collision the catalog itself carries.
+ */
+function rankCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  return allOf({
+    misses: lengthOf(root.misses),
+    unmeasurable: lengthOf(root.unmeasurable),
+  })
+}
+
 function boardCounts(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -518,6 +537,22 @@ export const AUDITS: readonly AuditSpec[] = [
     absentReasons: ['no-skills'] satisfies ReachRefusal[],
     counts: reachCounts,
   },
+  {
+    id: 'skills-rank',
+    label: 'Skill routing measure',
+    argv: ['claude', 'skills', 'rank', '--json'],
+    // Reports rather than gates. The corpus is a first run with no baseline to
+    // fail a push against, and a lexical ranker bounds a necessary condition
+    // rather than reporting real routing behavior, so a push failing on a
+    // moved rank would teach a contributor to route around the stage.
+    gatingExits: [],
+    corpus: 'tracked',
+    // The one reason this verb refuses for, and it is an absence for the same
+    // reason the reach check's is: a project carrying no `claude/skills/` has
+    // adopted no skill convention this audit reads.
+    absentReasons: ['no-skills'] satisfies RankRefusal[],
+    counts: rankCounts,
+  },
   {
     id: 'tasks',
     label: 'Task board',

package/src/claude/cases/all.ts

@@ -0,0 +1,24 @@
+import type { SkillCase } from '@/claude/skills-rank'
+import { AUTHORING_CASES } from '@/claude/cases/authoring'
+import { CLAUDE_WORKFLOW_CASES } from '@/claude/cases/claude-workflow'
+import { GIT_CASES } from '@/claude/cases/git'
+import { MISC_CASES } from '@/claude/cases/misc'
+import { SETUP_CASES } from '@/claude/cases/setup'
+
+/**
+ * The full routing case corpus, one file per domain so a description change
+ * in one family touches only the file beside it.
+ *
+ * Bootstrapped from each skill's own quoted trigger phrases and then
+ * rephrased and supplemented rather than shipped verbatim, since a positive
+ * lifted unchanged from a trigger passes by construction and never tests a
+ * person's own words. See `.claude/groundwork/42-ai-blueprint/08-spikes.md`
+ * for the extraction arm this corpus replaces as the shipped measure.
+ */
+export const SKILL_CASES: readonly SkillCase[] = [
+  ...CLAUDE_WORKFLOW_CASES,
+  ...GIT_CASES,
+  ...SETUP_CASES,
+  ...AUTHORING_CASES,
+  ...MISC_CASES,
+]

package/src/claude/cases/authoring.ts

@@ -0,0 +1,53 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * Script, skill, snippet, standard, and doc authoring, plus the two prose
+ * skills that revise rather than generate.
+ */
+export const AUTHORING_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'I need a shell tool with prompts and a nice terminal UI for people to run by hand.',
+    expect: 'bash-script',
+  },
+  {
+    prompt:
+      'Wire up a GitHub Actions pipeline with parallel jobs for this repo.',
+    expect: 'ci-workflow',
+  },
+  {
+    prompt:
+      'Write me a headless automation script with no interactive prompts.',
+    expect: 'cli-script',
+  },
+  {
+    prompt: 'Scaffold a brand-new SKILL.md for this capability.',
+    expect: 'create-skill',
+  },
+  {
+    prompt: 'I need a new reusable prompt snippet added to the corpus.',
+    expect: 'create-snippet',
+  },
+  {
+    prompt: 'Write a fresh authoring convention as a new standard file.',
+    expect: 'create-standard',
+  },
+  {
+    prompt:
+      "The docs folder and README are stale against what's on main, refresh them.",
+    expect: 'docs-sync',
+  },
+  {
+    prompt: 'Say what that dense answer actually means in plain terms.',
+    expect: 'restate',
+  },
+  {
+    prompt: 'This passage reads flat and robotic, give it some real cadence.',
+    expect: 'write-human',
+  },
+  {
+    prompt:
+      'Pull the captions off this YouTube link and save them with metadata.',
+    expect: 'youtube-transcripts',
+  },
+]

package/src/claude/cases/claude-workflow.ts

@@ -0,0 +1,153 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * The `claude-*` skill family: feature planning, review, and the session
+ * artifacts that coordinate work across sessions.
+ *
+ * Every positive is phrased away from its skill's own quoted trigger, since a
+ * verbatim trigger passes by construction and proves nothing about a prompt in
+ * someone's own words. Negatives target the pairs whose bodies already state
+ * an explicit `Do NOT` boundary against each other, since a boundary in a
+ * body does not reach the field a router reads.
+ */
+export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
+  {
+    prompt: 'Go fix everything the reviewer flagged on my open PR.',
+    expect: 'claude-address-review',
+  },
+  {
+    prompt:
+      'Run the whole implement, verify, review, and ship pipeline for the approved plan.',
+    expect: 'claude-autoship',
+  },
+  {
+    prompt: "Pull together a design system from what's already in the app.",
+    expect: 'claude-design-extract',
+  },
+  {
+    prompt: 'Draw me a diagram of how the pieces of this system connect.',
+    expect: 'claude-diagram',
+  },
+  {
+    prompt:
+      'Bring the internal planning docs under .claude up to date with what we decided this session.',
+    expect: 'claude-docs',
+  },
+  {
+    prompt:
+      'Sketch out a plan for adding this new capability before we touch any code.',
+    expect: 'claude-feature',
+  },
+  {
+    prompt:
+      'We need to measure this properly before committing to an approach.',
+    expect: 'claude-groundwork',
+  },
+  {
+    prompt: 'Take this pile of raw notes and turn it into filed items.',
+    expect: 'claude-intake',
+  },
+  {
+    prompt: 'Walk me through the open intake items so I can decide on each.',
+    expect: 'claude-intake-answer',
+  },
+  {
+    prompt:
+      "Draft a diff-based proposal for tightening this passage in the standard, don't just edit it.",
+    expect: 'claude-markdown-propose',
+  },
+  {
+    prompt: 'Pull the durable lessons out of this session before it ends.',
+    expect: 'claude-memory-capture',
+  },
+  {
+    prompt:
+      'Go through the memory folder and propose what to do with each entry.',
+    expect: 'claude-memory-review',
+  },
+  {
+    prompt:
+      'Take on the orchestrator role and coordinate the parallel feature builds.',
+    expect: 'claude-orchestrate',
+  },
+  {
+    prompt: 'Post a formal review with findings on that open pull request.',
+    expect: 'claude-pr-review',
+  },
+  {
+    prompt:
+      'Look over everything that changed on this branch for bugs and edge cases.',
+    expect: 'claude-review',
+  },
+  {
+    prompt: 'Draft me a script with beats for a screencast recording.',
+    expect: 'claude-screencast',
+  },
+  {
+    prompt:
+      "Check whether my installed Claude seed docs have drifted from the toolkit's.",
+    expect: 'claude-seed-sync',
+  },
+  {
+    prompt: 'Turn this topic into a slide deck I can render.',
+    expect: 'claude-slides-draft',
+  },
+  {
+    prompt:
+      'Check whether the markdown I changed violates any authoring standards.',
+    expect: 'claude-standards-audit',
+  },
+  {
+    prompt: 'Open a new entry on the task board for this piece of work.',
+    expect: 'claude-tasks',
+  },
+  {
+    prompt: 'Open a learning workspace so I can study this topic properly.',
+    expect: 'claude-teach',
+  },
+  {
+    prompt: 'Generate the Playwright tests I need after this UI change.',
+    expect: 'claude-ui-test',
+  },
+  {
+    prompt:
+      'Look over the interface and tell me what feels unfinished or confusing.',
+    expect: 'claude-ux-audit',
+  },
+  {
+    prompt: 'Tell me the paint and layout cost of this page right now.',
+    expect: 'claude-ux-measure',
+  },
+  {
+    prompt: 'Get me set up in a fresh Claude Code worktree for this branch.',
+    expect: 'claude-worktree',
+  },
+
+  // Negatives: pairs whose bodies already carry an explicit Do NOT boundary.
+  {
+    prompt:
+      'Refresh the stale sections of README and the docs folder based on what changed.',
+    expect: 'docs-sync',
+  },
+  {
+    prompt: 'Sort through this brain dump and write it up as findings.',
+    expect: 'claude-intake',
+  },
+  {
+    prompt:
+      "Go through what's still unanswered in the intake folder and decide.",
+    expect: 'claude-intake-answer',
+  },
+  {
+    prompt: 'Check this markdown against the house style rules.',
+    expect: 'claude-standards-audit',
+  },
+  {
+    prompt: 'Find the rough, unfinished-feeling spots in this interface.',
+    expect: 'claude-ux-audit',
+  },
+  {
+    prompt: 'Tell me the render cost of this page in the browser.',
+    expect: 'claude-ux-measure',
+  },
+]

package/src/claude/cases/git.ts

@@ -0,0 +1,44 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/** The `git-*` skill family: branch, commit, and pull-request mechanics. */
+export const GIT_CASES: readonly SkillCase[] = [
+  {
+    prompt: 'Come up with a conventional name for this branch.',
+    expect: 'git-branch',
+  },
+  {
+    prompt: "Turn what's staged into one commit message.",
+    expect: 'git-commit',
+  },
+  {
+    prompt: "Push a quick follow-up fix onto the PR that's already open.",
+    expect: 'git-followup',
+  },
+  {
+    prompt: 'Turn this bug into a GitHub issue and file it.',
+    expect: 'git-issue',
+  },
+  {
+    prompt: 'Write the title and body for this pull request.',
+    expect: 'git-pr',
+  },
+  {
+    prompt: 'Take this finished feature all the way through to an opened PR.',
+    expect: 'git-ship',
+  },
+  {
+    prompt:
+      'This branch has unrelated commits mixed together, break it into separate branches.',
+    expect: 'git-split',
+  },
+  {
+    prompt:
+      'These staged changes cover more than one concern, commit them separately.',
+    expect: 'git-stage',
+  },
+  {
+    prompt:
+      'Show me the linked worktrees and clear out the ones already merged.',
+    expect: 'git-worktree',
+  },
+]

package/src/claude/cases/misc.ts

@@ -0,0 +1,27 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/** Skills that share no prefix with any other domain file here. */
+export const MISC_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'Bundle up every open call that only I can make and ask me all at once.',
+    expect: 'decision-escalate',
+  },
+  {
+    prompt: 'Fire up the dev server the way this project documents it.',
+    expect: 'project-commands',
+  },
+  {
+    prompt:
+      "We're about to hit the context limit, write the handoff before we lose state.",
+    expect: 'session-map',
+  },
+  {
+    prompt: 'Catch me up on what was in progress before this session started.',
+    expect: 'session-resume',
+  },
+  {
+    prompt: "This test just started failing and I don't know why yet.",
+    expect: 'systematic-debugging',
+  },
+]

package/src/claude/cases/setup.ts

@@ -0,0 +1,78 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * `setup-*`, `migration-*`, `toolkit-*`, and `create-rule`: scaffolding,
+ * proposal-only migrations, and the toolkit's own reference and feedback
+ * surfaces.
+ */
+export const SETUP_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'This project has no rules installed yet, get the right governance in place.',
+    expect: 'setup-gov',
+  },
+  {
+    prompt:
+      "Get the index.md system bootstrapped across this project's folders.",
+    expect: 'setup-indexes',
+  },
+  {
+    prompt:
+      'This is a brand-new project, get the toolkit bootstrapped in one shot.',
+    expect: 'setup-init',
+  },
+  {
+    prompt: 'Get the usual Claude Code plugins provisioned on this machine.',
+    expect: 'setup-plugins',
+  },
+  {
+    prompt:
+      "Run through the generated scaffold's scripts and confirm each one passes.",
+    expect: 'setup-verify',
+  },
+  {
+    prompt:
+      'This CLAUDE.md file has grown huge, break it apart into the tiered context model.',
+    expect: 'migration-claude-md',
+  },
+  {
+    prompt:
+      'Move the agent-flavored docs out of the docs folder and into context.',
+    expect: 'migration-context',
+  },
+  {
+    prompt:
+      'The snippets folder needs to move under .claude to match the current layout.',
+    expect: 'migration-standards',
+  },
+  {
+    prompt:
+      'This file was replaced by a folder, help me split its content into it.',
+    expect: 'migration-superseded',
+  },
+  {
+    prompt:
+      "Before I run this sync, tell me exactly what it's going to overwrite.",
+    expect: 'toolkit-cli',
+  },
+  {
+    prompt:
+      'Something about the toolkit itself is broken, write it up and send it back to the maintainers.',
+    expect: 'toolkit-feedback',
+  },
+  {
+    prompt:
+      "I don't know which specific toolkit skill I need, just handle it for me.",
+    expect: 'toolkit-operator',
+  },
+  {
+    prompt:
+      'Work through the open feedback issues on the toolkit repo one by one.',
+    expect: 'toolkit-triage',
+  },
+  {
+    prompt:
+      "This project needs its own coding rule that the toolkit doesn't ship.",
+    expect: 'create-rule',
+  },
+]

package/src/claude/skills-rank.ts

@@ -0,0 +1,240 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { listSkills } from '@/claude/skills-list'
+
+/**
+ * Whether a prompt reaches the right skill, measured by TF-IDF cosine
+ * similarity over the shipped catalog's own frontmatter descriptions. This is
+ * a necessary condition rather than a report of real routing behavior: it
+ * asks whether the descriptions are separable by the words they use, and
+ * Claude Code does not route this way.
+ *
+ * Ported from `.claude/groundwork/42-ai-blueprint/evidence/rank.ts`, which
+ * ran once against this catalog and named the collisions this measure now
+ * tracks on a cadence.
+ */
+
+const SKILLS_DIR = join('claude', 'skills')
+
+const STOP = new Set(
+  'a about after again all also and any are as at be before but by can do does for from has have help how in into is it its just make not of on or our so that the then there these this to use used uses using want was what when where which who why with you your run'.split(
+    ' ',
+  ),
+)
+
+export interface RankedSkill {
+  readonly name: string
+  readonly description: string
+}
+
+/** One prompt and the skill it should reach. */
+export interface SkillCase {
+  readonly prompt: string
+  readonly expect: string
+}
+
+/** A case whose prompt did not rank its expected skill first. */
+export interface Miss {
+  readonly prompt: string
+  readonly expect: string
+  /** The skill the ranker placed first instead. */
+  readonly won: string
+  /** Where `expect` placed, or 0 when it never appears in the catalog. */
+  readonly rank: number
+}
+
+/** Why a measure produced no reading, which is never the same as a clean one. */
+export type RankRefusal = 'no-skills'
+
+export type RankReport =
+  | {
+      readonly kind: 'measured'
+      readonly skills: number
+      readonly cases: number
+      readonly rank1: number
+      readonly top3: number
+      readonly misses: readonly Miss[]
+      /** Cases whose prompt carried no vocabulary to score. */
+      readonly unmeasurable: readonly SkillCase[]
+    }
+  | { readonly kind: 'refused'; readonly reason: RankRefusal }
+
+/**
+ * Every shipped skill's frontmatter description, read the way a prompt is
+ * matched against it: whole, including the quoted trigger phrases it states.
+ * A skill whose frontmatter carries no description contributes no vocabulary
+ * and never wins a rank, so it is dropped rather than scored on nothing.
+ */
+export function loadCatalog(root: string): RankedSkill[] {
+  return listSkills(root)
+    .filter((skill) => skill.description !== '')
+    .map((skill) => ({ name: skill.name, description: skill.description }))
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length > 2 && !STOP.has(token))
+}
+
+function termCounts(tokens: readonly string[]): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1)
+  return counts
+}
+
+function buildIdf(
+  docs: readonly Map<string, number>[],
+): (term: string) => number {
+  const total = docs.length
+  const documentFrequency = new Map<string, number>()
+  for (const doc of docs) {
+    for (const term of doc.keys()) {
+      documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1)
+    }
+  }
+  return (term) =>
+    Math.log((total + 1) / ((documentFrequency.get(term) ?? 0) + 1)) + 1
+}
+
+function tfIdfVector(
+  terms: Map<string, number>,
+  idf: (term: string) => number,
+): Map<string, number> {
+  const vec = new Map<string, number>()
+  for (const [term, frequency] of terms) vec.set(term, frequency * idf(term))
+  return vec
+}
+
+function cosineSimilarity(
+  a: Map<string, number>,
+  b: Map<string, number>,
+): number {
+  let dot = 0
+  for (const [term, weight] of a) dot += weight * (b.get(term) ?? 0)
+  if (dot === 0) return 0
+
+  const norm = (vec: Map<string, number>) =>
+    Math.sqrt(
+      [...vec.values()].reduce((sum, weight) => sum + weight * weight, 0),
+    )
+  const denominator = norm(a) * norm(b)
+  return denominator === 0 ? 0 : dot / denominator
+}
+
+export interface RankedResult {
+  readonly name: string
+  readonly score: number
+}
+
+/**
+ * Every skill's TF-IDF vector over the catalog it was loaded with, and the
+ * IDF weighting that both the catalog and a scored prompt read from. A model
+ * is built once per catalog and reused across every case, since the IDF
+ * weights are the same question asked of the same corpus each time.
+ */
+export interface RankModel {
+  readonly rank: (prompt: string) => readonly RankedResult[]
+}
+
+export function buildModel(catalog: readonly RankedSkill[]): RankModel {
+  const docs = catalog.map((skill) => termCounts(tokenize(skill.description)))
+  const idf = buildIdf(docs)
+  const vectors = new Map(
+    catalog.map((skill, index) => [skill.name, tfIdfVector(docs[index], idf)]),
+  )
+
+  return {
+    rank: (prompt: string): readonly RankedResult[] => {
+      const promptVector = tfIdfVector(termCounts(tokenize(prompt)), idf)
+      // A prompt built entirely from stopwords and short words tokenizes to
+      // nothing, so every skill would score 0 and the sort would fall through
+      // to `localeCompare`, handing the alphabetically first skill a win no
+      // description earned. Reporting no ranking at all is what keeps that
+      // tie-break from reading as a measurement.
+      if (promptVector.size === 0) return []
+
+      return [...vectors]
+        .map(([name, vector]) => ({
+          name,
+          score: cosineSimilarity(promptVector, vector),
+        }))
+        .sort(
+          (left, right) =>
+            right.score - left.score || left.name.localeCompare(right.name),
+        )
+    },
+  }
+}
+
+/**
+ * Scores every case against the catalog's own descriptions, which is the
+ * production mechanism: Claude Code matches a prompt against the whole
+ * description a skill ships, triggers included.
+ */
+export function measureCases(
+  catalog: readonly RankedSkill[],
+  cases: readonly SkillCase[],
+): {
+  readonly rank1: number
+  readonly top3: number
+  readonly misses: readonly Miss[]
+  readonly unmeasurable: readonly SkillCase[]
+} {
+  const model = buildModel(catalog)
+  let rank1 = 0
+  let top3 = 0
+  const misses: Miss[] = []
+  const unmeasurable: SkillCase[] = []
+
+  for (const skillCase of cases) {
+    const ranked = model.rank(skillCase.prompt)
+    if (ranked.length === 0) {
+      unmeasurable.push(skillCase)
+      continue
+    }
+
+    const at = ranked.findIndex((entry) => entry.name === skillCase.expect) + 1
+
+    if (at === 1) rank1 += 1
+    if (at > 0 && at <= 3) top3 += 1
+    if (at !== 1) {
+      misses.push({
+        prompt: skillCase.prompt,
+        expect: skillCase.expect,
+        won: ranked[0]?.name ?? '',
+        rank: at,
+      })
+    }
+  }
+
+  return { rank1, top3, misses, unmeasurable }
+}
+
+/**
+ * Reads the shipped catalog off disk and scores it against the given case
+ * corpus. Measures the cwd's catalog rather than the toolkit root, matching
+ * the reach and audit verbs, so a linked worktree reads its own branch.
+ */
+export function scanRank(
+  root: string,
+  cases: readonly SkillCase[],
+): RankReport {
+  const skillsRoot = join(root, SKILLS_DIR)
+  if (!existsSync(skillsRoot)) return { kind: 'refused', reason: 'no-skills' }
+
+  const catalog = loadCatalog(root)
+  const { rank1, top3, misses, unmeasurable } = measureCases(catalog, cases)
+
+  return {
+    kind: 'measured',
+    skills: catalog.length,
+    cases: cases.length,
+    rank1,
+    top3,
+    misses,
+    unmeasurable,
+  }
+}

package/src/commands/claude.ts

@@ -34,6 +34,12 @@ import {
   type ReachReport,
   scanReach,
 } from '@/claude/skills-reach'
+import { SKILL_CASES } from '@/claude/cases/all'
+import {
+  type RankRefusal,
+  type RankReport,
+  scanRank,
+} from '@/claude/skills-rank'
 import {
   planSettings,
   readSettings,
@@ -85,6 +91,10 @@ interface SkillsReachOptions {
   readonly json?: boolean
 }
 
+interface SkillsRankOptions {
+  readonly json?: boolean
+}
+
 interface RoutingOptions {
   readonly json?: boolean
 }
@@ -215,15 +225,18 @@ export function register(program: Command): void {
 
   const skills = claude
     .command('skills')
-    .description('Plugin skill catalog (list, audit, drift, reach)')
-    .argument('[subcommand]', "One of 'list', 'audit', 'drift', or 'reach'")
+    .description('Plugin skill catalog (list, audit, drift, reach, rank)')
+    .argument(
+      '[subcommand]',
+      "One of 'list', 'audit', 'drift', 'reach', or 'rank'",
+    )
     .helpOption('-h, --help', 'Show this help message')
     .action((subcommand: string | undefined) => {
       intro('aitk claude')
       logError(
         subcommand === undefined
-          ? "Missing subcommand. Use 'list', 'audit', 'drift', or 'reach'."
-          : `Unknown subcommand: ${subcommand}. Use 'list', 'audit', 'drift', or 'reach'.`,
+          ? "Missing subcommand. Use 'list', 'audit', 'drift', 'reach', or 'rank'."
+          : `Unknown subcommand: ${subcommand}. Use 'list', 'audit', 'drift', 'reach', or 'rank'.`,
       )
       outro()
       process.exitCode = 1
@@ -351,6 +364,42 @@ export function register(program: Command): void {
     .action((path: string | undefined, opts: SkillsReachOptions) => {
       process.exitCode = runSkillsReach(path, opts)
     })
+
+  skills
+    .command('rank')
+    .description('Score the shipped catalog against the routing case corpus')
+    .argument('[path]', 'Repository root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        '  TF-IDF cosine similarity over every claude/skills/*/SKILL.md',
+        '  frontmatter description, scored against the hand-authored corpus',
+        '  at src/claude/cases/. A necessary condition rather than a report of',
+        '  real routing behavior: it asks whether the descriptions are',
+        '  separable by the words they use, and Claude Code does not route',
+        '  this way.',
+        '',
+        'Exit codes:',
+        '  0  the catalog was read, whether or not a case missed rank one',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Reports rather than gates. The corpus is a first run with no',
+        'baseline to fail a push against, so `aitk audits run` registers',
+        'this with no gating exit and joins the ratchet instead.',
+        '',
+        'Examples:',
+        '  aitk claude skills rank',
+        '  aitk claude skills rank --json',
+        '',
+      ].join('\n'),
+    )
+    .action((path: string | undefined, opts: SkillsRankOptions) => {
+      process.exitCode = runSkillsRank(path, opts)
+    })
 }
 
 function succeed(message: string): number {
@@ -816,6 +865,101 @@ function reportReach(report: Extract<ReachReport, { kind: 'measured' }>): void {
   )
 }
 
+/** What a reader does about the one way the measure fails to build. */
+const RANK_REFUSALS: Record<RankRefusal, string> = {
+  'no-skills':
+    'No claude/skills/ here, so this tree ships no plugin body to measure.',
+}
+
+/**
+ * Measures the cwd rather than the toolkit root, matching the reach and audit
+ * verbs, so a linked worktree reads its own branch instead of `main`. The
+ * case corpus is the toolkit's own, since a target project ships no cases of
+ * its own for a catalog it did not author.
+ */
+function runSkillsRank(
+  path: string | undefined,
+  opts: SkillsRankOptions,
+): number {
+  const root = resolve(path ?? process.cwd())
+  const report = scanRank(root, SKILL_CASES)
+
+  if (report.kind === 'refused') {
+    frameError(RANK_REFUSALS[report.reason])
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: RANK_REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  intro('aitk claude skills rank')
+  reportRank(report)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        skills: report.skills,
+        cases: report.cases,
+        rank1: report.rank1,
+        top3: report.top3,
+        misses: report.misses,
+        unmeasurable: report.unmeasurable,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+/**
+ * States the corpus and both counts on every run, including a clean one. A
+ * miss list alone reads as a verdict on the catalog unless the run also says
+ * how many skills and cases it measured against.
+ */
+function reportRank(report: Extract<RankReport, { kind: 'measured' }>): void {
+  logStep('Corpus')
+  logInfo(
+    `${plural(report.skills, 'skill')} scored against ${plural(report.cases, 'case')}`,
+  )
+
+  logStep('Score')
+  logInfo(
+    `rank one: ${report.rank1}/${report.cases}, top three: ${report.top3}/${report.cases}`,
+  )
+
+  if (report.unmeasurable.length > 0) {
+    logWarn(plural(report.unmeasurable.length, 'unmeasurable case'))
+    pipeOutput(
+      report.unmeasurable
+        .map((skillCase) => `${skillCase.expect}  ${skillCase.prompt}`)
+        .join('\n'),
+    )
+  }
+
+  if (report.misses.length === 0) {
+    logInfo('Every measurable case ranked its expected skill first.')
+    return
+  }
+
+  logWarn(plural(report.misses.length, 'collision'))
+  pipeOutput(
+    report.misses
+      .map(
+        (miss) =>
+          `${miss.expect} lost to ${miss.won} (rank ${miss.rank})  ${miss.prompt}`,
+      )
+      .join('\n'),
+  )
+}
+
 /**
  * States the bound on every run, including the run that names nothing. A report
  * listing only what moved reads as a verdict on what a session holds, and the