Workflow
- Inventory —
for d in <root>/*/*/; do grep -E '^(name|description):' "$d/SKILL.md"; done - Cluster — group by topic; flag pairs whose descriptions overlap or triggers could both fire.
- Read suspects — never classify from description or regex alone.
- Classify against taxonomy below.
- Surface findings + recommended fix — get direction before multi-file refactor; small isolated fixes can proceed.
- Fix and verify. Don't commit unless asked.
Taxonomy
- Forked script — same script copied across skills. Diff for drift. One owner; the other points to it.
- Contradiction — conflicting instructions for the same artifact. Pick owner; other defers.
- Restatement — one skill re-derives another's content. Replace with a one-line pointer.
- Bloat — frequently-loaded file carrying rare detail. Externalize to
references/; keep quick-fixes inline. - Unused or over budget — a skill no session log has read, or descriptions that together exceed the harness's list budget (Codex: 2% of context, then equal truncation). steipete/agent-scripts skill-cleaner measures both for Codex; elsewhere, sum description bytes by hand.
- Internal defect — duplicate headers/numbering, dead path refs, dead code.
- Smell — a single skill that fails on its own. From a 238-skill survey (arXiv 2607.01456), the ones worth flagging: stepless workflow; option buffet (choices with no decision rule); rationalization loophole ("usually", "if needed"); buried gotchas (traps mid-paragraph instead of in Notes); confusing description (what, when, and keywords blurred into one sentence); time-sensitive claims; non-third-person description; XML or backslash paths in frontmatter.
Rules
- Read every claimed defect before asserting it — heuristics misfire on code blocks and intentional parallel structures.
- One owner per capability; the other references it by explicit path.
- Progressive disclosure: description → SKILL.md (terse) →
references/REFERENCE.md(deep). Terseness scales with load frequency. - Fix the defect only — no adjacent refactoring, no extra cross-links.
See also
write-skill— author one new skill.