Skill Quality Reviewer

Skill Quality Reviewer

Overview

A meta-skill for evaluating the quality of Claude Skills. Perform comprehensive analysis across four key dimensions—description quality (25%), content organization (30%), writing style (20%), and structural integrity (25%)—to generate weighted scores, letter grades, and actionable improvement plans.

Use this skill to validate skills before sharing, identify improvement opportunities, or ensure compliance with skill development best practices.

When to Use This Skill

Invoke this skill when:

• Analyzing a skill's quality before distribution
• Reviewing skill documentation for best practices
• Evaluating adherence to skill development standards
• Generating improvement recommendations for existing skills
• Validating skill structure and completeness

Trigger phrases:

• "Analyze skill quality for ./my-skill"
• "Evaluate this skill: ~/.claude/skills/api-helper"
• "Review skill quality of git-workflow"
• "Check my skill for best practices"
• "Generate quality report for this skill"

Review Modes

Use one of three review modes depending on the task:

1. score-only

• fast first-pass grading for one skill.

1. remediation-backlog

• convert findings into P0 / P1 / P2 fix queues with concrete evidence.

1. 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**:

{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