Skill Improver
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 a SKILL.md file.
- Optional: the skill's intended purpose, if stated — used to judge whether name and scope match intent.
Steps
- Gather mechanical facts deterministically:
bash "${CLAUDE_SKILL_DIR}/scripts/skill-lint.sh" <skill-dir-or-SKILL.md>
Reports frontmatter validity, name format, description shape, SKILL.md size, preferred sections, and referenced vs orphaned files. Treat [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 or SKILL.md path.
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.
1---2name: skill-improver3description: Use when reviewing, grading, critiquing, or improving an existing Claude Code skill or SKILL.md — checks name/scope, invocation description, structure, leanness, and surfaces concrete opportunities to add references, scripts, and determinism.4---56# Skill Improver78## Overview910Make 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.1112**Core principle:** Every observation comes with a suggested fix.1314## Inputs1516- **Required:** path to a skill directory (with `SKILL.md`) or to a `SKILL.md` file.17- **Optional:** the skill's intended purpose, if stated — used to judge whether name and scope match intent.1819## Steps20211. **Gather mechanical facts deterministically:**22 ```bash23 bash "${CLAUDE_SKILL_DIR}/scripts/skill-lint.sh" <skill-dir-or-SKILL.md>24 ```25 Reports frontmatter validity, name format, description shape, SKILL.md size, preferred sections, and referenced vs orphaned files. Treat `[FLAG]`s as leads, not verdicts.262. **Read the SKILL.md and bundled files yourself** — the linter can't judge clarity, scope, or correctness.273. **Review the five dimensions** (Guidelines), turning each finding into a concrete fix.284. **Prioritize** high -> low impact. Lead with anything that breaks discovery (weak description) or correctness.295. **Write the report** (Output). Offer to apply changes; if asked, hand authoring to `superpowers:writing-skills`.3031## Guidelines3233| Dimension | What good looks like |34| :-------- | :------------------- |35| **Name & scope** | Verb-first, active, single clear purpose. Flag vague or multi-purpose skills (suggest a split). |36| **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. |37| **Structure** | Prefer **overview, inputs, steps, guidelines, output format**. Note missing sections; suggest where content should move. |38| **Lean SKILL.md** | Body holds workflow + judgment; heavy detail (APIs, long tables, big examples) belongs in `references/`. Flag bloat and name what to extract. |39| **References / scripts / assets** | Mechanical actions -> a deterministic **script**. Reusable context -> a **reference**. Templates -> **assets**. Flag orphaned files and non-deterministic scripts. |4041Look 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).4243## Output format4445```46## Skill review: <name>4748Strengths: <1-2 lines>4950### Suggested improvements (highest impact first)511. [<dimension>] <observation> -> <concrete fix>522. ...5354### Extraction & determinism opportunities55- <inline content -> references/file.md>, <prose step -> scripts/x.sh>5657Overall: <1-2 sentences, specific and encouraging. No score.>58```5960## Common mistakes6162- **Grading instead of helping** — no scores; every point needs an actionable fix.63- **Parroting the linter** — its flags are inputs; add the judgment it can't.64- **Extraction with nowhere to go** — name the target file and what moves into it.6566## Scripts6768- `scripts/skill-lint.sh` — deterministic mechanical checks (frontmatter, name, description, size, sections, orphaned/non-deterministic files). Read-only; pass a skill dir or `SKILL.md` path.6970**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.
devclarityai