/skill-quality-reviewer

name: skill-quality-reviewer
description: This skill should be used when the user asks to "analyze skill quality", "evaluate this skill", "review skill quality", "check my skill", or "generate quality report". Evaluates local skills across description quality, content organization, writing style, and structural integrity.
version: 0.1.0

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.

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