solo-skill-audit

/skill-audit

Audit a skill against the quality checklist based on Anthropic's internal best practices for Claude Code skills. Reads the skill's SKILL.md, references/, scripts/, and evaluates across 12 dimensions.

Source: https://x.com/trq212/status/2033949937936085378

Checklist Reference

• Scoring rubric, 12 dimensions: references/checklist.md
• The levers the scores measure — invocation, information hierarchy, leading words, failure modes: references/writing-skills.md
• Term definitions used in findings: references/skills-glossary.md

Steps

1. Locate skill from $ARGUMENTS:

   • If name: search skills/{name}/SKILL.md in current project, then ~/.claude/plugins/**/skills/{name}/SKILL.md
   • If path: read directly
   • If empty: list available skills via Glob **/skills/*/SKILL.md, ask via AskUserQuestion

2. Read skill contents (parallel):

   • SKILL.md — main skill file
   • references/* — all reference files (if dir exists)
   • scripts/* — all scripts (if dir exists)
   • assets/* — all assets (if dir exists)
   • Count total lines of SKILL.md

3. Read checklist from references/checklist.md

4. Evaluate each dimension — for every checklist item, assess based on what you read:

   For each of the 12 dimensions:

   • State what you found (evidence)
   • Score 0, 1, or 2 (use rubric from checklist)
   • If score < 2: give one specific fix

5. Determine category — classify skill into one of 9 types from checklist. Flag if it straddles multiple.

6. Failure-mode pass — read references/writing-skills.md, then check the skill for each named failure mode. Quote the offending line for every hit; a hit with no quote is a guess:

   • No-op — a line the model already obeys by default. Test each sentence in isolation: does it change behaviour versus the default?
   • Duplication — one meaning stated in more than one place.
   • Sediment — stale lines describing behaviour, paths, or tools that no longer exist.
   • Sprawl — long even after no-ops and duplication are removed; cure is disclosure into references/, not deletion.
   • Negation — steering by prohibition where a positive target would work. Don't use X names X; use Y doesn't.
   • Premature completion — a step whose completion criterion can't distinguish done from not-done.
   • Weak leading word — a description or body leaning on generic words instead of a compact pretrained concept the user actually types.