Skill Reviewer

Purpose

Comprehensive review of Claude Code skills to ensure they follow best practices, use Progressive Disclosure Architecture (PDA) appropriately, and provide optimal user experience.

When to Use

• User asks to "review this skill" or "check this skill"
• Evaluating skill quality before publishing
• Identifying improvement opportunities
• Checking for PDA compliance
• Validating skill structure and conventions

Review Dimensions

1. Structure & Organization

Check:

• SKILL.md exists in correct location
• YAML frontmatter is valid and properly formatted
• Name follows conventions (lowercase, hyphens, <64 chars)
• Description is specific and includes trigger terms
• Description is under 1024 characters
• Description is in third person

Common Issues:

• Invalid YAML (missing ---, wrong indentation)
• Reserved words in name (anthropic, claude)
• Vague description ("helps with documents")
• Description too long (>1024 chars)

2. Content Quality

Check:

• Clear purpose statement
• Numbered step-by-step instructions
• Concrete examples with inputs/outputs
• Appropriate level of detail
• Consistent terminology

Common Issues:

• Missing examples
• Abstract guidance without concrete steps
• Inconsistent terminology
• Too much or too little detail

3. Progressive Disclosure (PDA) Compliance

Check:

• SKILL.md is under 500 lines
• SKILL.md is under 10KB (ideally 3-5KB)
• Large content split into reference/ files
• References are one level deep from SKILL.md
• Links to detailed docs are clear

PDA Assessment:

If SKILL.md < 5KB: ✅ Basic structure is fine
If SKILL.md 5-10KB: ⚠️ Consider progressive disclosure
If SKILL.md > 10KB: ❌ Should use PDA
If SKILL.md > 20KB: ❌❌ Strongly recommend PDA refactor

Common Issues:

• Monolithic SKILL.md with all content inline
• Deeply nested references (SKILL.md → advanced.md → details.md)
• Missing progressive disclosure for large content

4. File Organization

Check:

• Forward slashes in all paths (cross-platform)
• Descriptive file names (not doc1.md, doc2.md)
• Scripts in scripts/ directory
• Reference docs in reference/ directory
• No Windows-style backslashes

Common Issues:

• Mixed path separators
• Generic file names
• Scripts and docs in wrong locations

5. Best Practices

Check:

• Single responsibility (one clear purpose)
• Error handling guidance
• Security considerations (if applicable)
• Dependencies documented
• Troubleshooting section

Common Issues:

• Too broad scope ("does everything")
• Missing error handling
• Undocumented dependencies

6. Token Efficiency

Check:

• Progressive disclosure used appropriately
• Reference files loaded on-demand
• Scripts for mechanical work
• No redundant information

Efficiency Assessment:

Excellent: 80-95% token savings (PDA well applied)
Good: 50-79% token savings (PDA partially applied)
Fair: 20-49% token savings (some optimization)
Poor: 0-19% token savings (encyclopedia approach)

Review Process

1. Read SKILL.md

   • Parse YAML frontmatter
   • Check structure and organization
   • Evaluate content quality

2. Check File Structure

   • List all files in skill directory
   • Verify organization
   • Check file naming

3. Assess PDA Compliance

   • Estimate SKILL.md size
   • Check for reference/ directory
   • Evaluate progressive disclosure

4. Identify Issues

   • Categorize by severity (P1/P2/P3)
   • Provide specific recommendations
   • Suggest concrete fixes

5. Generate Report

   • Overall quality score
   • Detailed findings by dimension
   • Prioritized recommendations
   • Estimated token savings from improvements

Output Format

# Skill Review Report

## Overall Assessment
**Score:** [X/10]
**PDA Compliance:** [Yes/No/Partial]
**Recommendation:** [Approve/Improve/Refactor]

## Findings by Dimension

### Structure & Organization
[Issues found, if any]

### Content Quality
[Issues found, if any]

### PDA Compliance
[Current state, recommendations]

### File Organization
[Issues found, if any]

### Best Practices
[Issues found, if any]

### Token Efficiency
[Current efficiency, potential savings]

## Prioritized Recommendations

### P1 (Critical - Must Fix)
[Blocking issues]

### P2 (Important - Should Fix)
[Significant improvements]

### P3 (Nice-to-Have)
[Minor optimizations]

## Token Savings Estimate
[Current vs optimized comparison]

Quality Scoring

Excellent (9-10):

• All best practices followed
• PDA optimally applied
• Clear, concise, actionable
• Token savings >80%

Good (7-8):

• Most best practices followed
• PDA appropriately used
• Minor improvements possible
• Token savings 50-80%

Fair (5-6):

• Some best practices missing
• PDA partially applied or not needed
• Several improvements recommended
• Token savings 20-50%

Poor (1-4):

• Many best practices violated
• PDA not applied when needed
• Significant refactoring needed
• Token savings <20%

Common Recommendations

For Structure Issues

• "Fix YAML frontmatter formatting"
• "Rename skill to follow conventions"
• "Rewrite description to be more specific"
• "Add missing examples"

For PDA Issues

• "Split large SKILL.md using progressive disclosure"
• "Move detailed docs to reference/ files"
• "Create on-demand loading structure"
• "Reduce SKILL.md to <5KB"

For Organization Issues

• "Reorganize files into standard structure"
• "Rename files to be more descriptive"
• "Convert paths to forward slashes"
• "Move scripts to scripts/ directory"

For Content Issues

• "Add concrete examples with inputs/outputs"
• "Include error handling guidance"
• "Add troubleshooting section"
• "Document dependencies"

Severity Classification

P1 (Critical):

• Blocks usage or understanding
• Fundamental flaws in structure
• Missing essential information
• Security vulnerabilities

P2 (Important):

• Should be addressed
• Significant gaps
• Risky approaches
• Performance issues

P3 (Nice-to-Have):

• Consider for polish
• Minor improvements
• Optimizations
• Style consistency

Integration with Other Skills

After review, recommend:

• skill-generator - If major restructuring needed
• skill-optimizer - If PDA refactor recommended
• manual review - For nuanced decisions

Examples

Example 1: Excellent Skill

Input: Well-structured skill with PDA

Review:

# Skill Review Report

## Overall Assessment
**Score:** 9/10
**PDA Compliance:** Yes
**Recommendation:** Approve

### Findings
All dimensions met or exceeded standards.
Minor suggestion: Add troubleshooting section.

### Token Efficiency
Current: 3KB + on-demand loading
Savings: 92%

Example 2: Needs PDA Refactor

Input: 50KB monolithic SKILL.md

Review:

# Skill Review Report

## Overall Assessment
**Score:** 4/10
**PDA Compliance:** No
**Recommendation:** Refactor with PDA

### PDA Compliance
**Current:** 50KB monolithic file
**Recommended:** Split using progressive disclosure

### Token Savings Estimate
**Current:** 50KB per request
**Optimized:** 3KB + 8KB average = 11KB
**Savings:** 78% (39KB per request)

### P1 Recommendations
- Split SKILL.md into orchestrator + reference files
- Create reference/ directory for detailed docs
- Implement on-demand loading pattern

Quality Checklist Template

## Review Checklist

### YAML Frontmatter
- [ ] Valid format (starts/ends with `---`)
- [ ] Name: lowercase, hyphens, <64 chars
- [ ] No reserved words (anthropic, claude)
- [ ] Description: specific, includes triggers
- [ ] Description: <1024 characters
- [ ] Description: third person
- [ ] Allowed tools: appropriate for skill

### Content Structure
- [ ] Clear purpose statement
- [ ] Numbered process steps
- [ ] Concrete examples
- [ ] Error handling guidance
- [ ] Troubleshooting section

### PDA Compliance
- [ ] SKILL.md <500 lines
- [ ] SKILL.md <10KB
- [ ] Progressive disclosure used if >10KB
- [ ] References one level deep
- [ ] On-demand loading implemented

### File Organization
- [ ] Standard directory structure
- [ ] Forward slash paths
- [ ] Descriptive file names
- [ ] Scripts in scripts/
- [ ] References in reference/

### Best Practices
- [ ] Single responsibility
- [ ] Consistent terminology
- [ ] Dependencies documented
- [ ] Security considered
- [ ] Token efficient

See Also

• SKILL_GENERATOR.md - Create new skills
• SKILL_OPTIMIZER.md - Optimize existing skills
• SKILL_ARCHITECT.md - Complete workflow
• CLAUDE_SKILLS_ARCHITECTURE.md - Reference documentation

Sources

Based on:

• CLAUDE_SKILLS_ARCHITECTURE.md
• Official Anthropic skill authoring best practices