Skill Quality Reviewer

Review Modes

Use one of three review modes depending on the task:

1. score-only
   • fast first-pass grading for one skill.
2. remediation-backlog
   • convert findings into P0 / P1 / P2 fix queues with concrete evidence.
3. batch-portfolio
   • review multiple skills together, cluster repeated issues, and produce a prioritized shortlist.

Prefer remediation-backlog when the user asks what to fix next. Prefer batch-portfolio when auditing many skills at once.

Analysis Workflow

Step 1: Load the Skill

Accept skill path as input. Verify the path exists and contains SKILL.md. Read the complete skill directory structure.

# Example invocation
ls -la ~/.claude/skills/target-skill/

Validate:

• SKILL.md exists
• Directory is readable
• Path points to a valid skill

Step 2: Parse YAML Frontmatter

Extract and validate the YAML frontmatter from SKILL.md.

Required fields:

• name - Skill identifier
• description - Trigger description with phrases

Check for:

• Valid YAML syntax
• No prohibited fields
• Proper formatting

Step 3: Evaluate Description Quality (25%)

Assess the quality and effectiveness of the frontmatter description.

Scoring breakdown:

Red flags:

• Vague triggers like "helps with tasks"
• Second-person descriptions ("Use this when you...")
• Missing or generic descriptions
• No actionable trigger phrases

Reference: references/examples-good.md for exemplary descriptions

Step 4: Evaluate Content Organization (30%)

Assess adherence to progressive disclosure principles.

Scoring breakdown:

Check:

• SKILL.md body is concise and focused
• Detailed content moved to references/
• Examples and templates in appropriate directories
• No information duplication across files

Reference: references/scoring-criteria.md for detailed rubrics

Step 5: Evaluate Writing Style (20%)

Verify adherence to skill writing conventions.

Scoring breakdown:

Check for:

• Imperative verbs: "Create the file", "Validate input", "Check structure"
• Absence of: "You should", "You can", "You need to"
• Objective, instructional language
• Consistent style throughout

Good examples:

Create the skill directory structure.
Validate the YAML frontmatter.
Check for required fields.

Bad examples:

You should create the directory.
You need to validate the frontmatter.
Check if the fields are there.

Step 6: Evaluate Structural Integrity (25%)

Verify the skill's physical structure and completeness.

Scoring breakdown:

Validate:

• YAML frontmatter contains name and description
• Directory structure follows conventions:

  skill-name/
  ├── SKILL.md
  ├── references/ (optional)
  ├── examples/ (optional)
  └── scripts/ (optional)
  

• All files referenced in SKILL.md actually exist
• Examples are complete and working
• Scripts are executable

Step 7: Calculate Weighted Score

Compute the overall quality score using weighted dimensions.

Formula:

Overall Score = (Description × 0.25) + (Organization × 0.30) +
                (Style × 0.20) + (Structure × 0.25)

Letter grade mapping:

Step 8: Generate Reports

Create two output documents in the current working directory.

1. Quality Report (quality-report-{skill-name}.md)

• Executive summary with overall score and grade
• Dimension-by-dimension breakdown
• Strengths and weaknesses for each dimension
• Grade breakdown table
• Link to improvement plan

2. Improvement Plan (improvement-plan-{skill-name}.md)

• Prioritized improvement list (High/Medium/Low)
• Specific file locations and line numbers for issues
• Current vs. suggested content comparisons
• Estimated impact on scores
• Time estimates for fixes
• Expected score improvement

Output Templates

Quality Report Template

# Skill Quality Report: {skill-name}

## Executive Summary
- **Overall Score**: X/100 ({Grade})
- **Evaluated**: {Date}
- **Skill Path**: {path}

## Dimension Scores

### 1. Description Quality (25%)
**Score**: X/100

**Strengths**:
- ✅ {specific strength}

**Weaknesses**:
- ❌ {specific weakness}

**Recommendations**:
1. {actionable recommendation}

[Repeat for other dimensions...]

## Grade Breakdown
| Dimension | Score | Weight | Contribution |
|-----------|-------|--------|--------------|
| Description | X/100 | 25% | X.X |
| Organization | X/100 | 30% | X.X |
| Style | X/100 | 20% | X.X |
| Structure | X/100 | 25% | X.X |
| **Overall** | **X/100** | **100%** | **X.X ({Grade})** |

## Next Steps
See `improvement-plan-{skill-name}.md` for detailed improvement suggestions.

Improvement Plan Template

# Skill Improvement Plan: {skill-name}

## Priority Summary
- **High Priority**: {count} items
- **Medium Priority**: {count} items
- **Low Priority**: {count} items

## High Priority Improvements

### 1. [Issue Title]
**File**: SKILL.md:line:line
**Dimension**: Description Quality
**Impact**: +X points

**Current**:
```yaml
{current content}

Suggested:

{suggested content}

Reason: {why this improves quality}

[Continue with all issues...]

Quick Wins (Easy Fixes)

1. {quick fix}
2. {quick fix}

Estimated Time to Complete

• High Priority: X hours
• Medium Priority: X hours
• Low Priority: X hours
• Total: X hours

Expected Score Improvement

• Current: X/100 ({Grade})
• After High Priority: X/100 ({Grade})
• After All: X/100 ({Grade})

## Additional Resources

### Reference Files

For detailed evaluation criteria and examples, consult:

- **`references/scoring-criteria.md`** - Comprehensive scoring rubrics for each dimension
- **`references/examples-good.md`** - Exemplary skills demonstrating best practices
- **`references/examples-bad.md`** - Common anti-patterns to avoid

### Scripts

- **`scripts/extract-yaml.sh`** - Utility for extracting YAML frontmatter from SKILL.md
- **`scripts/skill-audit.py`** - Lightweight integrity audit for missing references, word count, and sibling-path checks

### Related Skills

- **`skill-development`** - Comprehensive guide for creating skills
- **`code-review-excellence`** - Best practices for code review

## Best Practices

### When Analyzing Skills

1. **Be objective and specific** - Base scores on observable criteria, not opinions
2. **Provide actionable feedback** - Each recommendation should be concrete and implementable
3. **Include examples** - Show current vs. suggested content for clarity
4. **Estimate impact** - Help users understand which changes matter most
5. **Be constructive** - Frame feedback as opportunities for improvement

### Common Quality Issues

**Description Quality:**
- Vague or generic trigger phrases
- Second-person descriptions
- Missing concrete use cases

**Content Organization:**
- SKILL.md too long (>5,000 words)
- Detailed content not moved to references/
- Poor information hierarchy

**Writing Style:**
- Second-person language ("you", "your")
- Mixed imperative and descriptive styles
- Subjective or conversational tone

**Structural Integrity:**
- Missing required YAML fields
- Referenced files don't exist
- Incomplete examples or broken scripts

### Grade Benchmarks

**A grade (90-100)**: Exemplary skills serving as templates for others
- All dimensions score 85+
- Clear, specific descriptions
- Excellent progressive disclosure
- Consistent imperative style
- Complete, well-organized structure

**B grade (80-89)**: High-quality skills with minor improvements needed
- Most dimensions score 75+
- Good descriptions and organization
- Generally follows best practices
- May have minor style inconsistencies

**C grade (70-79)**: Acceptable skills requiring moderate improvements
- Key areas meet minimum standards
- Some weaknesses in organization or style
- Functional but not exemplary

**D/F grade (below 70)**: Skills needing significant work
- Multiple dimensions below 70
- Major structural or style issues
- Requires comprehensive revision

## Usage Examples

**Example 1: Analyze a local skill**

User: "Analyze skill quality for ~/.claude/skills/git-workflow"

[Claude executes the 8-step workflow and generates:]

• quality-report-git-workflow.md
• improvement-plan-git-workflow.md

**Example 2: Review before sharing**

User: "Review my new skill before I publish it"

[Claude analyzes the skill and provides:]

• Detailed quality assessment
• Specific improvement recommendations
• Expected score after implementing fixes

**Example 3: Quality check for existing skill**

User: "Check skill quality of api-helper"

[Claude evaluates and reports:]

• Current grade and score
• Top improvement opportunities
• Quick wins for easy score gains

**Example 4: Batch portfolio review**

User: "Review all skills in ~/.claude/skills and tell me what to fix first"

[Claude evaluates and reports:]

• portfolio matrix
• grouped issue clusters
• shortlist for second-pass remediation