Overview
Make an existing skill better. The goal is helpful improvement, not a grade — produce concrete, prioritized changes the author can apply, not a score. You review five dimensions, lean on the bundled linter for mechanical facts, and apply judgment to the rest.
Core principle: Every observation comes with a suggested fix.
Inputs
- Required: path to a skill directory (with
SKILL.md) or to aSKILL.mdfile. - Optional: the skill's intended purpose, if stated — used to judge whether name and scope match intent.
Steps
- Gather mechanical facts deterministically:
Reports frontmatter validity, name format, description shape, SKILL.md size, preferred sections, and referenced vs orphaned files. Treatbash "${CLAUDE_SKILL_DIR}/scripts/skill-lint.sh" <skill-dir-or-SKILL.md>[FLAG]s as leads, not verdicts. - Read the SKILL.md and bundled files yourself — the linter can't judge clarity, scope, or correctness.
- Review the five dimensions (Guidelines), turning each finding into a concrete fix.
- Prioritize high -> low impact. Lead with anything that breaks discovery (weak description) or correctness.
- Write the report (Output). Offer to apply changes; if asked, hand authoring to
superpowers:writing-skills.
Guidelines
| Dimension | What good looks like |
|---|---|
| Name & scope | Verb-first, active, single clear purpose. Flag vague or multi-purpose skills (suggest a split). |
| Description | Says when to invoke (triggers/symptoms/situations), not just what it does — "Use when the user asks about slow queries or indexes", not "Analyze and optimize queries". Third person; lead with "Use when". A summary of the steps makes agents skip the body — flag it. |
| Structure | Prefer overview, inputs, steps, guidelines, output format. Note missing sections; suggest where content should move. |
| Lean SKILL.md | Body holds workflow + judgment; heavy detail (APIs, long tables, big examples) belongs in references/. Flag bloat and name what to extract. |
| References / scripts / assets | Mechanical actions -> a deterministic script. Reusable context -> a reference. Templates -> assets. Flag orphaned files and non-deterministic scripts. |
Look explicitly for the two highest-value opportunities: extraction (inline content that belongs in a references/ file, leaning out the always-loaded body) and determinism (prose steps an agent does inconsistently that a small script would make reproducible).
Output format
## Skill review: <name>
Strengths: <1-2 lines>
### Suggested improvements (highest impact first)
1. [<dimension>] <observation> -> <concrete fix>
2. ...
### Extraction & determinism opportunities
- <inline content -> references/file.md>, <prose step -> scripts/x.sh>
Overall: <1-2 sentences, specific and encouraging. No score.>
Common mistakes
- Grading instead of helping — no scores; every point needs an actionable fix.
- Parroting the linter — its flags are inputs; add the judgment it can't.
- Extraction with nowhere to go — name the target file and what moves into it.
Scripts
scripts/skill-lint.sh— deterministic mechanical checks (frontmatter, name, description, size, sections, orphaned/non-deterministic files). Read-only; pass a skill dir orSKILL.mdpath.
If a script can't run here (missing bash/a tool, or a different OS): don't abandon the task — the scripts only automate ordinary git/text commands, so reproduce the same steps directly with whatever tools this environment has.