Skill Audit

Skill Audit

A periodic health sweep of the whole skills/ tree - run it on a cadence, not per change. Validating one skill you just wrote is /skill-creator's job; this walks the collection and judges it as a set. The output is a findings list, not silent edits: audit, report, then route each finding to the skill that fixes it.

The tree is the single source of truth; the generated README, agents/AGENTS.md, dashboard, and skills.sh.json are downstream of it.

Before you start

Two mechanical gates come first - they are cheap and catch drift a read-through would miss:

1. devenv --no-tui shell -- skills --action lint - frontmatter, naming, placement. Record every error; these are findings.
2. devenv --no-tui shell -- skills --action sync, then check git status. A diff means the generated artifacts had drifted from the tree - the drift is itself a finding.

The audit

Walk the whole collection. Each pass carries an exhaustive bound - every skill, every reference, no sampling.

1. Inventory. List every promoted skill - one per skills/<category>/<name>/, excluding the in-progress/ lifecycle bucket (archived skills live outside skills/, under skills-archive/, and are out of scope) - grouped by category. This inventory is what the rest of the audit checks against.

2. Per-skill review. Apply the checklist below to every skill in the inventory.

3. Cross-reference integrity. Collect every /skill-name mentioned in any SKILL.md and confirm each resolves to a promoted skill of that name. A reference to an archived or nonexistent skill is a dangling reference - record it. Then confirm the /skill-router index names every promoted skill exactly once, and names nothing archived or gone.

   # promoted skill names (the inventory)
   ls -d skills/*/*/ | grep -v '/in-progress/' | xargs -n1 basename
   # every /skill-name reference to reconcile against it
   grep -rhoE '/[a-z][a-z0-9]+(-[a-z0-9]+)*' skills --include=SKILL.md | sort -u
   

4. Collection-level review. Across the whole set, look for:

   • Duplication or conflict - two skills covering the same branch, or giving contradictory guidance. Recommend a merge or a sharper boundary between them.
   • Retirement candidates - a skill superseded, stale, or that no realistic task would reach. Route to /archive-skill.
   • Gaps - a recurring task with no skill to serve it. Route to /skill-creator.

5. Report. Emit one findings list. Each finding names the skill(s) it touches, the problem, and a recommended action - edit or create via /skill-creator, retire via /archive-skill, fix a reference in place.

Per-skill checklist (reference)

For each skill in the inventory:

• Frontmatter valid - name equals the directory, kebab-case, prefix-free, ≤64 chars, no "claude"/"anthropic"; description is one line, ≤1024 chars, stating what it does and when to use it. Canonical keys only - no legacy custom:, triggers:, category:, or type:.
• Categorised right - sits in the topic bucket matching what it does, and is not stranded in in-progress/ while still live, nor sitting in skills-archive/ while something still routes to it.
• Description earns its load - one trigger per branch, leading word front-loaded, no identity already stated in the body.
• Body is lean - no sediment (stale lines), no sprawl (simply too long), no duplication (one meaning, one place), no no-op (default behaviour restated), no negation (steer by the positive target).
• References resolve - its /skill-name mentions and sibling-file pointers all hit live targets.

Done when

Every skill in the inventory has been through the checklist, every /skill-name reference has been resolved to a live skill or recorded as dangling, the router has been checked against the inventory, and the findings list names each problem with a recommended action and the skill it belongs to.