Skill Review

Purpose

Systematically audit Claude Code skills against official best practices to ensure quality, discoverability, and maintainability before release or merge.

Review Workflow

Step 1: Structure Validation

Check the basic structural requirements:

# Navigate to skill directory
cd ~/.claude/skills/skill-name

# Verify file structure
ls -la
# Expected:
# - Skill.md (capital S)
# - REFERENCE.md (optional, all caps)
# - TEMPLATE.md (optional, all caps)
# - scripts/ (optional, lowercase)

Validation checklist:

• Directory name matches skill name
• Directory name uses gerund form (verb + -ing)
• Directory name lowercase-with-hyphens
• Skill.md exists (capital S, not skill.md)
• Supporting files use ALL CAPS (REFERENCE.md, not reference.md)
• No deeply nested directories
• No files with underscores or wrong extensions

Step 2: Frontmatter Audit

Validate YAML frontmatter quality:

# Extract frontmatter
head -n 10 Skill.md

Validation checklist:

• Has valid YAML frontmatter (between — markers)
• name field present and matches directory name
• name uses gerund form (verb + -ing)
• name max 64 characters
• name lowercase-with-hyphens only
• description field present
• description in third person (not first/second)
• description includes specific capabilities
• description includes WHEN to use triggers
• description includes key terms for discovery
• description max 1024 characters
• description avoids vague language
• version field present in SemVer format (X.Y.Z)
• dependencies field if external packages needed

Common frontmatter issues:

# ❌ BLOCKER: First person
description: I can help you process PDFs...

# ❌ BLOCKER: Second person
description: You can use this to extract text...

# ❌ CRITICAL: Too vague
description: Helps with documents.

# ❌ CRITICAL: No triggers
description: Processes PDF files efficiently.

# ✅ GOOD: Third person, specific, with triggers
description: Extract text, tables, and forms from PDF files including scanned documents. Use when working with PDFs or document extraction tasks.

Step 3: Content Quality Check

Review the main skill content:

# Check file length
wc -l Skill.md
# Should be under 500 lines for optimal performance

Core content validation:

• Main file under 500 lines
• Has clear “Purpose” section
• Has “When to Use” section with specific scenarios
• Has structured workflow or quick start
• Provides 2-3 concrete examples minimum
• Uses consistent terminology throughout
• Avoids general knowledge Claude already has
• Provides ONE default approach (not too many options)
• Includes validation/verification steps
• Has troubleshooting section for common issues
• Uses progressive disclosure (details in reference files)
• Reference files are one level deep only
• No time-sensitive information
• No marketing language or vague confidence claims

Progressive disclosure validation:

• SKILL.md under 500 lines (target: under 300 for complex skills)
• Uses references/ directory for detailed content
• Detailed workflows extracted to references/WORKFLOW-STEPS.md
• Troubleshooting content in references/TROUBLESHOOTING.md
• Templates/examples in references/TEMPLATE-EXAMPLES.md
• Domain-specific checks in references/[DOMAIN]-CHECKS.md
• No nested references (SKILL.md → references/A.md only)
• Clear loading guidance format:

  **For detailed [topic]:**
  \`\`\`
  Read `~/.claude/skills/[skill]/references/FILE.md`
  \`\`\`
  Use when: [specific scenario]
  

• Each reference has “Use when:” context
• Reference files are standalone (no cross-references)

Example quality validation:

• At least 2-3 concrete examples provided
• Examples show input AND expected output
• Code examples are complete (not pseudocode)
• Examples cover common use cases
• Examples include validation steps

Step 4: Instruction Clarity Audit

Verify instructions are clear and actionable:

Sequential workflows:

• Steps numbered clearly (Step 1, Step 2, etc.)
• Each step has concrete action
• Code blocks show exact commands
• Expected outputs documented
• Validation checkpoints provided

Example pattern:

### Step 1: Validate Input

\`\`\`bash

# Check file exists

test -f document.pdf || echo "File not found"
\`\`\`

### Step 2: Extract Text

\`\`\`python
import pdfplumber
with pdfplumber.open('document.pdf') as pdf:
text = pdf.pages[0].extract_text()
\`\`\`

### Step 3: Verify Output

Expected format:
\`\`\`json
{
"pages": 5,
"text": "extracted content..."
}
\`\`\`

Terminology consistency:

• Same concept uses same term throughout
• No switching between synonyms
• Terms defined before use
• Technical terms used correctly

Step 5: Testing Verification

Validate testing and evaluation quality:

Testing checklist:

• Has evaluations or test cases
• At least 3 test scenarios created
• Tests cover common use cases
• Tests cover edge cases
• Tested with fresh Claude instances
• Tested across multiple models (Haiku, Sonnet, Opus)
• Real-world validation completed
• Team feedback incorporated

Code quality (if applicable):

• Scripts have explicit error handling
• Configuration values commented (WHY, not WHAT)
• Required packages available and version-specified
• Forward slashes in all paths (not backslashes)
• Validation for critical operations
• No hardcoded credentials or secrets

Severity Levels

Use these severity levels to prioritize issues:

BLOCKER (Must fix before release)

• First/second person in description
• Skill.md over 750 lines
• No description or completely vague
• No examples provided
• Missing critical frontmatter fields
• Broken/invalid YAML
• Skill name doesn’t match directory
• Major structural issues

CRITICAL (Should fix before release)

• Description missing key triggers
• Skill.md 500-750 lines (over recommended)
• Fewer than 2 examples
• Deeply nested references (>1 level)
• Inconsistent terminology
• Too many options without default
• Missing validation steps
• No testing performed

MAJOR (Should fix soon)

• Description could be more specific
• Missing troubleshooting section
• Examples lack expected outputs
• No progressive disclosure
• Includes general knowledge Claude has
• Missing error handling in scripts
• No version number in dependencies
• Inconsistent file naming

MINOR (Nice to have)

• Could add more examples
• Could improve comments
• Could add table of contents
• Could extract more to reference files
• Could add more test scenarios

Review Report Template

# Skill Review: [skill-name]

**Reviewer:** [name]
**Date:** [YYYY-MM-DD]
**Version Reviewed:** [X.Y.Z]

## Summary

[1-2 sentences on overall quality]

**Recommendation:** [PASS | NEEDS WORK | FAIL]

## Findings by Category

### Structure [PASS/FAIL]

- [ ] Directory structure correct
- [ ] File naming conventions followed
- [ ] Under 500 lines

**Issues:**

- [SEVERITY] Issue description
- [SEVERITY] Issue description

### Frontmatter [PASS/FAIL]

- [ ] Valid YAML
- [ ] All required fields present
- [ ] Description quality

**Issues:**

- [SEVERITY] Issue description

### Content Quality [PASS/FAIL]

- [ ] Clear purpose and workflows
- [ ] Concrete examples provided
- [ ] Progressive disclosure used
- [ ] Consistent terminology

**Issues:**

- [SEVERITY] Issue description

### Instruction Clarity [PASS/FAIL]

- [ ] Clear sequential steps
- [ ] Code examples complete
- [ ] Validation steps included

**Issues:**

- [SEVERITY] Issue description

### Testing [PASS/FAIL]

- [ ] Test scenarios created
- [ ] Fresh instance testing done
- [ ] Multi-model testing done

**Issues:**

- [SEVERITY] Issue description

## Blockers (must fix)

1. [Issue]
2. [Issue]

## Critical Issues (should fix)

1. [Issue]
2. [Issue]

## Major Issues (fix soon)

1. [Issue]
2. [Issue]

## Minor Issues (nice to have)

1. [Issue]
2. [Issue]

## Positive Highlights

- [What the skill does well]
- [What the skill does well]

## Recommendations

1. [Specific actionable recommendation]
2. [Specific actionable recommendation]

## Next Steps

- [ ] Address blockers
- [ ] Address critical issues
- [ ] Re-review after fixes
- [ ] Approve for merge

Anti-Pattern Detection

Watch for these common anti-patterns:

Anti-Pattern: Too Many Options

Problem:

You can use pypdf, pdfplumber, PyMuPDF, pdf2image, camelot, tabula,
or pytesseract depending on your needs. Each has pros and cons...
[200 lines comparing libraries]

Solution:

Use pdfplumber for text and tables. For scanned PDFs, use pytesseract with pdf2image.
See REFERENCE.md for alternative libraries.

Anti-Pattern: General Knowledge

Problem:

## Python Basics

Python is a programming language. To install Python, visit python.org...
[100 lines of Python installation]

Solution:

# Remove entirely - Claude already knows this

Anti-Pattern: Vague Instructions

Problem:

1. Do the thing
2. Check if it worked
3. Fix any issues

Solution:

### Step 1: Extract Text

\`\`\`python
import pdfplumber
with pdfplumber.open('document.pdf') as pdf:
text = pdf.pages[0].extract_text()
\`\`\`

### Step 2: Validate Extraction

\`\`\`python
assert text is not None, "Extraction failed"
assert len(text) > 0, "Empty result"
\`\`\`

Anti-Pattern: Nested References

Problem:

Skill.md → REFERENCE.md → ADVANCED.md → EXPERT.md

Solution:

Skill.md → REFERENCE.md
Skill.md → ADVANCED.md
Skill.md → EXPERT.md

Anti-Pattern: Bloated Main File

Problem:

Skill.md: 1,247 lines

Solution:

Skill.md: 342 lines
REFERENCE.md: 400 lines (detailed API)
EXAMPLES.md: 300 lines (additional examples)
TEMPLATE.md: 205 lines (output templates)

Quality Gates

Skills should pass these gates before release:

Gate 1: Structure ✅

• Directory/file naming correct
• Frontmatter valid and complete
• Under 500 lines

Gate 2: Description ✅

• Third person
• Specific capabilities
• Clear triggers
• Key terms included

Gate 3: Content ✅

• Clear purpose and workflows
• 2-3 concrete examples
• One default approach
• Validation steps

Gate 4: Clarity ✅

• Sequential steps
• Complete code examples
• Expected outputs
• Troubleshooting section

Gate 5: Testing ✅

• Test scenarios created
• Fresh instance testing
• Multi-model validation

Quick Reference

# Run full review
1. Check structure (file naming, organization)
2. Validate frontmatter (YAML, description quality)
3. Audit content (length, examples, clarity)
4. Verify instructions (workflows, code, validation)
5. Check testing (scenarios, coverage, feedback)
6. Generate report with severity levels
7. Provide actionable recommendations

# Pass criteria
- All BLOCKERS resolved
- All CRITICAL issues resolved
- At least 80% of MAJOR issues resolved
- Clear path to resolve remaining issues

Resources

• Skill Best Practices
• Review Checklist
• Example Reviews
• Official Documentation