skill-quality-reviewer

What this skill does

# 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.
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.

```bash
# 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:**

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| Trigger phrases clarity | 25 | 3-5 specific user phrases present |
| Third-person format | 25 | Uses "This skill should be used when..." |
| Description length | 25 | 100-300 characters optimal |
| Specific scenarios | 25 | Concrete use cases, not vague |

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

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| Progressive disclosure | 30 | SKILL.md lean, details in references/ |
| SKILL.md length | 25 | Under 5,000 words (1,500-2,000 ideal) |
| References/ usage | 25 | Detailed content properly moved |
| Logical organization | 20 | Clear sections, good flow |

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

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| Imperative form | 40 | Verb-first instructions throughout |
| No second person in body | 30 | Avoids conversational second person in the main workflow body |
| Objective language | 30 | Factual, instructional tone |

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

| Criterion | Points | Evaluation |
|-----------|--------|------------|
| YAML frontmatter | 30 | All required fields present |
| Directory structure | 30 | Proper organization |
| Resource references | 40 | All referenced files exist |

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

| Score Range | Grade | Meaning |
|-------------|-------|---------|
| 97-100 | A+ | Exemplary |
| 93-96 | A | Excellent |
| 90-92 | A- | Very Good |
| 87-89 | B+ | Good |
| 83-86 | B | Above Average |
| 80-82 | B- | Solid |
| 77-79 | C+ | Acceptable |
| 73-76 | C | Satisfactory |
| 70-72 | C- | Minimal Acceptable |
| 67-69 | D+ | Below Standard |
| 63-66 | D | Poor |
| 60-62 | D- | Very Poor |
| 0-59 | F | Fail |

### 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

```markdown
# 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

```markdown
# 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**:
```yaml
{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
- **Tot