| name | review-skill |
| description | Reviews a SKILL.md file or skill directory for quality, correctness, and alignment with Claude Code skill conventions. Use when you've written a new skill and want to check it before committing, or when evaluating an existing skill for improvements.
|
| allowed-tools | Read, Glob, Grep, Edit, Write |
| argument-hint | <skill-dir>... |
This skill reviews and fixes other skills — identifying issues and applying corrections with developer approval at each stage.
Stop after each stage and have changes reviewed with the user.
Note: The agent checks skills against conventions and best practices, then proposes fixes. The developer approves before changes are applied. When uncertain about intent, ask — don't assume.
See responsibilities.md for the full agent vs developer ownership matrix.
Each stage produces a checklist of findings (pass / issue / suggestion) and proposes fixes for any issues found. Stage 5 delivers an overall quality assessment and publish/revise/rethink recommendation.
-
Read and understand the skill (agent proposes, developer confirms)
- Read the target
SKILL.md at $ARGUMENTS (and any supporting files in the directory). If no argument was provided, ask the user which skill to review.
- Summarize: what does this skill do, when is it invoked, and what workflow does it follow?
- Confirm understanding before proceeding to review
-
Frontmatter review (agent reviews, then fixes with developer approval)
Check that frontmatter is well-formed and follows conventions:
- Is
name kebab-case and does it match the directory name?
- Is
description present, specific enough to trigger correctly, and does it include when-to-use context?
- Are invocation control fields appropriate for the skill's purpose?
- Side-effect workflows should use
disable-model-invocation: true
- Background knowledge should use
user-invocable: false
- Is
allowed-tools set if the skill should restrict tool access?
- Is
argument-hint present if the skill uses $ARGUMENTS?
- Is the
description written in third person? (descriptions are injected into the system prompt — third person reads naturally there)
- Are
context/agent set appropriately if the skill runs in isolation?
- Are there unknown or misspelled frontmatter fields?
Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.
-
Prompt structure review (agent reviews, then fixes with developer approval)
Check the prompt body for structural quality:
- Does it have a stop-after-each-stage instruction if it's a multi-stage workflow?
- Is there a Stage 0 for understanding/confirmation before doing work?
- Are agent vs developer responsibilities clear at each stage?
- Does it use questions to guide analysis, not just imperatives?
- Is the skill under 500 lines? Does it reference supporting files for detail rather than inlining everything?
- Does the skill specify what artifacts or outputs it produces and in what format? (reports, checklists, files, modified documents)
- Are file references at most one level deep from SKILL.md? (no file→file→file chains — Claude may partially read nested references)
- Is the stage numbering consistent and logical?
Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.
-
Effectiveness review (agent reviews, then fixes with developer approval)
Check that the skill will work well in practice:
- Are instructions unambiguous — will Claude interpret them correctly?
- Is the scope right-sized? (Not trying to do too much in one skill)
- Are
$ARGUMENTS, $0, $1 used correctly if present?
- Is dynamic context (exclamation-mark backtick syntax) used correctly if present?
- If the skill uses
$ARGUMENTS, does it handle missing or invalid arguments gracefully? (prompt the user, show usage, or fail with a clear message)
- Does the skill address what happens when it encounters an error or unexpected state? (validation, recovery, or clear reporting — not every skill needs elaborate handling, but it shouldn't leave the developer guessing)
- Do reference files over 100 lines include a table of contents so Claude can see their full scope?
- Are supporting files referenced from
SKILL.md?
- Check for anti-patterns:
- Overly broad or narrow description
- No review pauses in a multi-stage workflow
- Unreferenced supporting files in the directory
- Task instructions in a skill with no
context: fork and no clear action
- Deeply nested file references (file→file→file chains that Claude may not follow)
- Agent escape hatches: Soft language ("where appropriate", "if you have a clear fix", "as needed") that lets the agent skip required work. Completion gates must use hard prerequisites, not discretionary phrasing. Look for: conditional qualifiers on mandatory steps, missing definitions of done, and loops without explicit exit criteria.
Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.
-
Alignment review (agent reviews, then fixes with developer approval)
If the skill is intended for this repo's skill library, check alignment with existing skills:
- Consistent formatting with other skills in the repo?
- Blockquotes for philosophy notes
- Bold for stage titles
- Tables for comparisons
- Includes "When to use this vs other skills" if it overlaps with existing skills?
- Follows the composition model (flesh-out -> review-steps -> strong-edit -> agent-optimize)?
- Has a
responsibilities.md if it's a multi-stage workflow with mixed agent/developer ownership?
If the skill is standalone (not for this repo), skip repo-specific alignment checks and note this.
Report findings as a checklist: pass / issue / suggestion. Then apply fixes for any issues, with developer approval.
-
Summary and recommendations (agent leads)
Provide a final summary:
- Overall quality assessment (ready to use / needs minor fixes / needs rework)
- Top 3 issues to address (if any)
- Top 3 strengths (what the skill does well)
- Recommendation: publish / revise / rethink
- If the skill will be used across model tiers (Haiku, Sonnet, Opus), flag whether instructions are explicit enough for smaller models — what works for Opus may need more detail for Haiku
When to Use This vs Other Skills
| Goal | Use |
|---|
| Review a document for polish | review-steps |
| Review a document for substantive critique | strong-edit |
| Review a SKILL.md for quality and conventions | review-skill |
| Create a new skill from scratch | Start with _template, then review-skill the result |
