/skill-audit

name: skill-audit
description: "Audit the shipped skill catalogue for overlap, staleness, and drift against the install record, and propose keep, improve, merge, or retire per skill."
category: skill-ops
mutates: documents

Skill Audit

The catalogue is a product surface: every extra entrypoint spends a reader's attention whether or not it fires. Audit it on evidence the repository and the host already hold, and propose verdicts. Deleting or merging a skill is the caller's decision, taken after the proposal, never inside the audit.

The assessment half is a saved workflow, not a procedure this skill performs inline. Its single source of truth is `.claude/workflows/skill-audit-sweep.js` in the genie repository's canonical workflow catalog (see `.claude/workflows/README.md` there); this skill is its front door. On a runtime that runs saved workflows, run the script at `<repository root>/.claude/workflows/skill-audit-sweep.js` when that file exists, otherwise `~/.claude/workflows/skill-audit-sweep.js` (delivered by `genie install` / `genie update`); give the runtime that explicit script path, never a bare name — both scopes now carry these names and the order a name resolves in is undocumented. Pass `{focus?, skills?, searchPass?, skillsDir?, shardCount?, quorum?, model?, timestamp?}` — every key optional, and with no `skills` list the sweep audits whatever the inventory check reports on disk. Freeze the interview below into `searchPass` before the call; the workflow asks nothing, writes nothing, and moves no file. Relay the returned `report` unchanged, and list `notConvened` (agents that returned nothing) and `unjudged` (roster skills that carry no verdict) beside it rather than filling either gap yourself.

Before authoring

A new skill is the last option, not the first. This interview stays here, with you, and reaches the workflow only as a frozen `searchPass` record. Search before you write:

1. **Name the intent.** The task the skill performs, the trigger conditions, and three to five keywords with their synonyms. 2. **Search the shipped catalogue first.** Grep the skill directories for the keywords in both the frontmatter description and the body. A hit in an existing description usually means the workflow already has a home. 3. **Search the host's installed homes.** The install record written at the end of a successful update lists the inventory and every agent skills home it wrote, and the skills lines of `genie doctor` report what is present per home. A name already installed from elsewhere is user-owned and is not yours to overwrite. 4. **Vet anything external** before adopting it: read its instructions end to end, look for shell commands, file writes, network calls, and credential handling, and prefer copying into a branch you can diff over editing an installed original. 5. **Decide out loud.** Use the existing skill, extend it, or create a fresh one because the search found no close match. Say which, and why.

The consolidation table in the catalogue README is the precedent: audit lenses collapsed into one review entrypoint, investigation collapsed into one report entrypoint. Prefer the same move.

Verdicts

The sweep judges each skill holistically against actionability, scope fit, uniqueness, and currency, and returns one verdict per skill:

| Verdict | Meaning | |---------|---------| | Keep | Distinct, current, and carrying its own workflow | | Improve | Worth keeping once a named, specific change lands | | Update | The behaviour it describes has moved; the text has not | | Merge into X | Substantial overlap; X is the surviving entrypoint | | Retire | No unique content remains, or the cost outweighs the use |

Every verdict carries a self-contained reason a reader can act on without re-reading the skill: the defect, the line range, and what covers the same need instead. "Superseded" and "too long" are not reasons. A `Merge into X` row names the surviving target and the content to carry across; an `Improve` row names the section and the target size.

Without a workflow surface

On a runtime with no workflow surface, dispatch the same four stages by hand and carry no roster the script does not. **Signals**: one read-only agent runs whatever skill lint and inventory parity check the repository itself ships — in the genie repository, `scripts/skills-lint.ts` and `scripts/skills-inventory-parity.ts` with `--repo .`, fed the `skills@1.5.23 add "$PWD" --list` listing on its stdin, because that script alone reads an empty list and exits 1 — reads the `genie doctor` skills lines, and returns a compact summary plus the on-disk inventory — that inventory is the one roster, never a second reading unioned into it. **Characterize**: three or four shards, each reading several whole skill files against the closed category enum, the four mutates values and the forty-to-ninety house range, and naming any file it could not read rather than inferring a record. **Verdicts**: one consolidating judge sees every responding shard at once and assigns exactly one verdict per skill it received, with a single bounded re-state round for any reason that names no defect. **Render**: draw the verdict table, the signals block and the unjudged list yourself. A shard that returns nothing is reported, never inferred.

Batch intake

Intake answers one question for a batch of candidate skills that are NOT in the shipped catalogue: what the product should do with each one. It is the batch form of the vet-anything-external and decide-out-loud steps above, and its assessment half is a saved workflow rather than a procedure this skill performs inline — the single source of truth is `.claude/workflows/skill-intake.js` in the same catalog. On a runtime that runs saved workflows, run the script at `<repository root>/.claude/workflows/skill-intake.js` when that file exists, otherwise `~/.claude/workflows/skill-intake.js` (delivered by `genie install` / `genie update`), as the explicit script path eith