review-skill

name	review-skill
description	Reviews and audits Claude Code skills for structure, effectiveness, and strategic design. Use when user says 'review skill', 'audit skill', 'check my skill', 'is this skill good', or provides a SKILL.md path to evaluate.

Evaluate a Claude Code skill against structural and strategic best practices. Produce a severity-based report with actionable findings covering both correctness (is it well-formed?) and effectiveness (will it actually work well?).

<quick_start>

1. If no skill path provided: list available skills from ~/.claude/skills/ and ~/.claude/commands/, ask user to pick
2. Read the target SKILL.md and scan its directory (references/, scripts/, workflows/)
3. Evaluate against all 8 areas below
4. Present findings in the report format
5. Offer to fix issues </quick_start>

YAML front matter is Level 1 of the 3-level loading system -- always loaded in every session. It MUST answer: 1. What does the skill do? 2. When should it be invoked?

Check:

• name: kebab-case, 1-4 words, max 64 chars, matches directory name
• description: Max 1024 chars, third person, follows the formula: [What it does] + [When to use it] + [Trigger words/phrases]
• Trigger words present: Explicit keywords or phrases that activate the skill
  • Text triggers: keywords user might say ("sprint", "clean CSV", "deploy")
  • Event triggers: actions like uploading a file, pasting a URL
• No over-triggering: Description specific enough to NOT fire for unrelated tasks
• No under-triggering: Enough trigger words to reliably invoke when needed

See references/description-examples.md for bad vs good examples.

Check: - **SKILL.md under 500 lines** (overview only, details in references) - **Pure XML tags** in body -- no markdown headings (##, ###) - **All XML tags properly closed** - **No hybrid XML/markdown** (mixing `` with `## Workflow`) - **Required tags present**: at minimum `` and `` - **Conditional tags match complexity**: - Simple skill (single task): required tags only is fine - Complex skill (multi-step, APIs, security): MUST have error handling, validation - MCP skill: MUST specify which tools to use and in what order - **References one level deep** from SKILL.md - **Folder structure**: has `references/` and/or `scripts/` if non-trivial - **Token efficiency**: SKILL.md MUST be a lean router. Workflow details, step-by-step instructions, and verbose content MUST be in `references/` files loaded on demand. SKILL.md is loaded on EVERY invocation - every line costs tokens. Flag any SKILL.md over 200 lines that could be split into a router + reference files. Identify which pattern the skill uses and whether it fits:

1. Sequential: Linear steps, each depends on prior output. MUST have rollback/failure handling.
2. Multi-MCP Coordination: Spans multiple MCPs in phases. Each phase MUST complete before next.
3. Iterative Refinement: Generate -> Vary -> Audit -> Refine -> Select. MUST have quality criteria.
4. Conditional Routing: Same input, different paths based on conditions. MUST cover all input types.
5. Domain-Specific Intelligence: Embeds org rules, SOPs, decision logic.

Flag if pattern is unclear or workflow is vague prose with no structure.

Only evaluate for skills that invoke MCP servers.

Check:

• Tool scoping: specifies WHICH tools to use, not just "use the X MCP"
• Tool ordering: sequence of calls is explicit
• Domain expertise: adds knowledge on TOP of raw MCP access (why these tools, in this order)
• Context preservation: avoids loading unnecessary MCP tools

Check: - **Step-based structure**: numbered steps with expected outputs per step - **Specificity**: each step says WHAT to do, not "handle appropriately" - **Balance**: explicit enough for consistency, flexible enough for dynamic tasks - **No vague prose**: no "make sure everything looks good" - **Constraint strength**: MUST/NEVER/ALWAYS for critical rules, not "should" or "try to" - **Conciseness**: every line earns its place (test: "does removing this reduce effectiveness?") Evaluate whether the skill is testable: - **Measurable success criteria**: not "user is satisfied" but "output contains valid JSON with X fields" - **Deterministic outputs**: would it produce consistent results across 5 runs? - **Triggering clarity**: could you write 3 prompts that SHOULD trigger it and 3 that SHOULDN'T? - **Edge cases**: what happens with empty input, malformed data, missing files? Is this skill worth the complexity? - Could a simple script, cron job, or alias do the same thing? - Does the skill add more value than error it might introduce? - How often will it realistically be used? (daily = high value, monthly = question it) - Is the maintenance burden justified? (external API dependencies = higher burden) - Would removing the skill make the workflow worse, or would no one notice? - Should this be a slash command, CLAUDE.md instruction, or MCP server instead?

Flag if: skill reimplements something trivial, has excessive complexity for simple output, or depends on volatile APIs without clear justification.

Flag: - `markdown_headings_in_body`: using ## instead of XML tags - `hybrid_xml_markdown`: mixing XML tags with markdown headings - `unclosed_xml_tags`: missing closing tags - `vague_description`: "helps with", "processes data", "works with" - `no_trigger_words`: description has no invocation hints - `overt_triggering`: description so broad it fires for unrelated tasks - `consultant_word_salad`: technical-sounding but says nothing actionable - `bloat`: obvious explanations, redundant content, motivational prose - `deeply_nested_references`: references more than one level deep - `monolithic_skill`: over 500 lines with no references - `broken_references`: references files that don't exist - `wrong_tool`: this should be a script, command, app, or CLAUDE.md instruction instead

<contextual_judgment> Apply the right lens based on skill category:

Document & Asset Creation (PDFs, Excel, presentations):

• Focus on output consistency and format specs
• Templates and examples are critical

Meta/Process Skills (skill creators, workflow crystallizers):

• Focus on flexibility and generalization
• MUST handle diverse inputs gracefully

MCP Orchestration Skills (recipe layer on MCP tools):

• Focus on tool scoping, ordering, domain expertise
• MUST preserve context window
• MUST add value beyond raw MCP access

Always explain WHY a finding matters for THIS specific skill, not just that it violates a rule. </contextual_judgment>

<output_format>

## Review: [skill-name]

### Assessment

[1-2 sentences: fit for purpose? Main takeaway.]

### Critical Issues

1. **[Category]** (file:line)
   - Current: [what exists]
   - Should be: [what it should be]
   - Why: [impact on this skill]

### Recommendations

1. **[Category]** (file:line)
   - Current: [what exists]
   - Recommendation: [what to change]
   - Benefit: [how this helps]

### Strengths

- [what's working well]

### Quick Fixes

1. [issue] at file:line -> [one-line fix]

### Context

- Category: [document-creation / meta-process / mcp-orchestration / workflow / other]
- Design pattern: [sequential / multi-mcp / iterative / conditional / domain-specific / unclear]
- Line count: [number]
- Value assessment: [high / medium / low / questionable / wrong-tool]
- Effort to fix: [low / medium / high]

</output_format>

<success_criteria>

• All 8 evaluation areas assessed
• Findings have file:line locations
• Contextual judgment applied (not arbitrary rules)
• Severity categories used (Critical / Recommendations / Quick Fixes)
• Strengths identified
• Category, design pattern, and value assessment identified
• If wrong tool: clearly states what should be used instead </success_criteria>

<final_step> After presenting findings, offer:

1. Fix all issues automatically
2. Fix critical issues only
3. Show examples for specific issues
4. Just the report </final_step>