Review Skill

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?).

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

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

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.

## 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]

• 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

After presenting findings, offer:

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alexadark
• Source: alexadark/review-skill-skill
• License: MIT

Install and usage instructions live in the source repository linked above.