julien-dev-skill-reviewer
Review and improve skill quality. Use when: user asks to review skill, check skill quality, improve skill, or after creating a skill with skill-creator-pro.
When & Why to Use This Skill
This Claude skill provides a systematic framework for auditing, scoring, and optimizing the quality of AI agent skills. By evaluating nine critical dimensions—such as context efficiency, actionability, and error handling—it ensures that SKILL.md files are concise, production-ready, and perform at peak efficiency within Claude's context window.
Use Cases
- Quality Auditing: Automatically evaluate a newly developed skill against a standardized 9-dimension rubric to ensure it meets professional deployment standards.
- Context Optimization: Identify and refactor bloated SKILL.md files that exceed the 500-line limit to improve model responsiveness and reduce token costs.
- Iterative Improvement: Generate prioritized refactoring plans to fix DRY (Don't Repeat Yourself) violations and improve the logical flow of complex agent instructions.
- Pre-Distribution Validation: Run a comprehensive checklist to verify naming conventions, path formatting, and skill-chaining documentation before sharing skills with a team.
| name | julien-dev-skill-reviewer |
|---|---|
| description | "Review and improve skill quality. Use when: user asks to review skill, check skill quality, improve skill, or after creating a skill with skill-creator-pro." |
| license | Apache-2.0 |
| author | "Julien" |
| version | "2.0.0" |
| category | "development" |
Skill Reviewer
Systematically evaluate and improve skill quality through scoring, refactoring, and iteration.
When to Use
- After creating a skill with skill-creator-pro
- When SKILL.md exceeds 500 lines
- Before packaging for distribution
- When quality score is unknown or low
- When skill feels bloated or has duplication
Review Process
Step 1: Read and Parse
# Read main file
Read skills/skill-name/SKILL.md
# Discover all resources
Glob skills/skill-name/**/*
# Check line count
wc -l skills/skill-name/SKILL.md
Parse YAML frontmatter: name, description, license, allowed-tools.
Step 2: Score Against Rubric
Evaluate 9 dimensions (1-5 scale). See references/quality-rubric.md for detailed criteria.
| Dimension | Check |
|---|---|
| Clarity | Clear steps, no ambiguity |
| Completeness | All scenarios covered |
| Discoverability | Good name + description |
| Context Efficiency | < 500 lines, refs used |
| Actionability | Concrete, copy-paste ready |
| Resource Organization | Proper scripts/refs/assets |
| Examples | Concrete, realistic |
| Skill Chaining | I/O/Dependencies documented |
| Error Handling | Troubleshooting provided |
Step 3: Calculate Score
Average = Sum of 9 scores / 9
| Score | Status |
|---|---|
| 1.0-2.4 | Needs major rework |
| 2.5-3.4 | Functional, needs improvement |
| 3.5-4.4 | Good, minor refinements |
| 4.5-5.0 | Excellent, production ready |
Minimum for production: 3.5/5, no dimension < 3/5
Step 4: Identify Issues
For each dimension < 4/5, document with line references. See references/refactoring-templates.md for issue format.
Step 5: Suggest Refactoring
Create prioritized plan:
- Priority 1: Critical (must fix)
- Priority 2: High impact
- Priority 3: Polish
See references/dry-patterns.md for common patterns.
Step 6: Execute (with approval)
Ask user before changes:
A) Show detailed plan
B) Execute Priority 1 automatically
C) Walk through one-by-one
D) Focus on specific dimension
Step 7: Re-evaluate
After refactoring:
- Re-read modified files
- Re-score all 9 dimensions
- Compare before/after
- Report improvement
Step 8: Iterate if Needed
If score < 3.5/5, continue iterations. Safety limit: Max 5 iterations.
Key Validation Checks
See references/validation-checks.md for complete list.
| Check | Requirement |
|---|---|
| Line count | SKILL.md < 500 lines |
| Name | ≤ 64 chars, lowercase + hyphens |
| Description | Third person, ≤ 1024 chars |
| Paths | Forward slashes only |
| References | One level deep |
| Long files | TOC if > 100 lines |
| No duplicates | Content in one place only |
Reference Files
| File | Content |
|---|---|
| references/quality-rubric.md | 9-dimension scoring details |
| references/dry-patterns.md | DRY violations and fixes |
| references/refactoring-templates.md | Report and plan templates |
| references/validation-checks.md | Automated and manual checks |
Quality Assurance Checklist
Before marking production-ready:
- Average score ≥ 3.5/5
- No dimension < 3/5
- SKILL.md ≤ 500 lines
- Proper progressive disclosure
- No DRY violations
- Skill Chaining documented
- Examples are concrete
- Error handling documented
- YAML frontmatter valid
- All references linked from SKILL.md
Skill Chaining
Skills Required Before
- julien-dev-tools-skill-creator-pro (optionnel): If reviewing newly created skill
Input Expected
- Path to skill directory with SKILL.md
- Skill must have valid YAML frontmatter
Output Produced
- Format: Review report in markdown
- Side effects:
- May create
references/directory - May create new .md files
- May modify SKILL.md (with approval)
- Creates backup:
SKILL.md.backup-YYYYMMDD-HHMMSS
- May create
- Duration: 5-10 minutes (3-5 iterations)
Compatible Skills After
Recommandés (if score ≥ 3.5/5):
- Package script from skill-creator-pro
- julien-workflow-sync-personal-skills: Deploy to ~/.claude/skills/
Called By
- julien-dev-tools-skill-creator-pro: After Step 4, before packaging
- Direct invocation: "Review my skill X"
Tools Used
Read(usage: read SKILL.md, references/)Glob(usage: discover skill files)Grep(usage: search patterns, word count)Edit(usage: refactor SKILL.md)Write(usage: create references/*.md)Bash(usage: wc -l, backup files)
Visual Workflow
User: "Review skills/my-skill"
↓
[THIS SKILL]
├─► Read SKILL.md + refs
├─► Score 9 dimensions
├─► Identify issues
└─► Generate report
↓
Score < 3.5/5?
YES → Refactor → Re-evaluate → Iterate
NO → Production ready ✅
↓
[Next steps]
├─► package_skill.py
└─► sync-personal-skills
Usage Example
Scenario: Review deployment skill
Command: "Review the skill at skills/deployment-manager/"
Result:
- Initial score: 2.8/5
- Issues: DRY violation, bloated SKILL.md (6000 words), missing chaining
- After 3 iterations: 4.3/5
- SKILL.md: 6000 → 2500 words
- Created: references/api-reference.md, references/examples.md
- Status: Production ready