skill-quality-reviewer

Files (7)

• SKILL.md
• batch-review-template.md · references/
• examples-bad.md · references/
• examples-good.md · references/
• scoring-criteria.md · references/
• extract-yaml.sh · scripts/
• skill-audit.py · scripts/

SKILL.md (first lines)

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

From Galaxy-Dawn/claude-scholar, MIT.

More from Galaxy-Dawn/claude-scholar