jovermier 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
Read SKILL.md
- Parse YAML frontmatter
- Check structure and organization
- Evaluate content quality
Check File Structure
- List all files in skill directory
- Verify organization
- Check file naming
Assess PDA Compliance
- Estimate SKILL.md size
- Check for reference/ directory
- Evaluate progressive disclosure
Identify Issues
- Categorize by severity (P1/P2/P3)
- Provide specific recommendations
- Suggest concrete fixes
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