Skill Reviewer

Ensure skills maintain high quality standards through systematic review.

When to Use

Use this skill when:

• •Creating a new skill (before finalization)
• •Updating an existing skill (after making changes)
• •Auditing skill quality across your marketplace
• •Reviewing team members' skill contributions

Quick Review Process

1. Load the Skill

Read the skill's SKILL.md and check the directory structure:

ls -la path/to/skill/
cat path/to/skill/SKILL.md

2. Apply the 10-Point Checklist

Review against these core quality criteria:

1. •Progressive Disclosure - Metadata/instructions/resources properly separated
2. •Mental Model Shift - Describes skill as canonical approach, not "new feature"
3. •Degree of Freedom - Matches instructions to declared autonomy level
4. •SKILL.md Conciseness - Lean, actionable, purpose-driven
5. •Safety & Failure Handling - Guardrails and recovery steps present
6. •Resource Hygiene - References current, minimal, discoverable
7. •Consistency - Terminology and flow clear and unambiguous
8. •Testing Guidance - Verification steps or examples included
9. •Ownership (Optional) - Known limitations documented; version/maintainer optional
10. •Tight Scope - Focused purpose, no feature creep

3. Document Findings

Create a review report with:

• •✅ Criteria that pass
• •⚠️ Areas needing improvement
• •🔴 Critical issues requiring fixes
• •💡 Suggestions for enhancement

Detailed Guidance

For in-depth review criteria and examples:

• •Quality Checklist - Comprehensive criteria with examples
• •Progressive Disclosure - Proper structure and information layering
• •Mental Model Shift - Language and positioning guidance
• •Common Pitfalls - What to avoid and how to fix
• •Review Examples - Sample reviews demonstrating the process

Review Workflow

For New Skills

1. •

   Structure Check

   • •Verify SKILL.md exists with proper frontmatter
   • •Check references/ directory organization
   • •Confirm scripts/ are executable if present
2. •

   Content Review

   • •Frontmatter: name (lowercase, hyphens), description (clear, comprehensive)
   • •Body: Concise instructions with examples
   • •Progressive disclosure: Core in SKILL.md, details in references/
3. •

   Quality Assessment

   • •Apply 10-point checklist
   • •Verify mental model language
   • •Check for appropriate scope and freedom level

For Updated Skills

1. •

   Change Assessment

   • •Identify what changed (use git diff if available)
   • •Verify changes align with skill's purpose
   • •Check for scope creep or complexity additions
2. •

   Documentation Update

   • •Ensure SKILL.md reflects new capabilities
   • •Update references/ if needed
   • •Maintain progressive disclosure pattern
3. •

   Regression Check

   • •Verify existing examples still work
   • •Check that changes didn't break mental model
   • •Confirm scope remains focused

Review Report Template

# Skill Review: [skill-name]

**Date**: YYYY-MM-DD
**Reviewer**: [name]
**Type**: [New|Update|Audit]

## Summary
Brief overview of the skill and review findings.

## Checklist Results

✅ Progressive Disclosure
✅ Mental Model Shift
⚠️  Degree of Freedom - Instructions too prescriptive for declared high freedom
✅ SKILL.md Conciseness
🔴 Safety & Failure Handling - Missing error recovery steps
✅ Resource Hygiene
✅ Consistency
⚠️  Testing Guidance - Examples present but no verification steps
✅ Ownership
✅ Tight Scope

## Critical Issues

1. **Missing Failure Handling**: Add error recovery steps for [specific scenario]

## Improvements Needed

1. **Degree of Freedom Mismatch**: Reduce prescriptiveness in steps 3-5 to match high freedom declaration
2. **Testing**: Add quick verification example showing expected output

## Suggestions

- Consider moving detailed API reference to references/api-docs.md
- Example in section 4 could be more concise

## Conclusion

[Overall assessment and recommendation: Approve|Needs Revision|Reject]

Best Practices

Keep SKILL.md Lean

Move detailed content to references/:

• •API documentation → references/api-docs.md
• •Complex workflows → references/workflows.md
• •Extensive examples → references/examples.md
• •Configuration details → references/configuration.md

Verify Progressive Disclosure

Check that information loads in stages:

1. •Metadata (always): name + description only
2. •Instructions (when triggered): SKILL.md body
3. •Resources (as needed): references/ files

Assess Mental Model

Language should reflect "this is the way":

• •❌ "New recommended approach"
• •❌ "Optional feature"
• •✅ "Use [tool] for [task]"
• •✅ "Standard workflow"

Match Freedom to Instructions

• •High freedom: Provide principles, let Claude decide specifics
• •Medium freedom: Offer preferred patterns with parameters
• •Low freedom: Specify exact steps for fragile operations

Examples

For complete review examples with before/after comparisons:

• •Review Examples - Sample reviews of simple and complex skills

For detailed examples of each quality criterion:

• •Quality Checklist - Examples for each of the 10 criteria

Quick Verification

After completing a review, verify the process worked correctly:

Checklist:

• • All reference links in SKILL.md resolve correctly
• • Review report follows the template format
• • Critical issues (🔴) are clearly identified
• • At least one improvement or suggestion provided
• • Checklist results show ✅⚠️🔴 indicators

Smoke test: Review a simple skill (e.g., a single-file skill with <500 words) and verify you can:

1. •Load the skill and identify its structure
2. •Apply all 10 checklist criteria
3. •Generate a complete review report
4. •Identify at least one area for improvement

Expected outcome: A review report that provides actionable feedback and follows the template structure.

Version

Version: 1.1.0 Last Updated: 2025-11-23 Maintainer: Alberto Leal (mail4alberto@gmail.com) Changelog: See changelogs/skill-reviewer.md