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.

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

{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

Batch Review Template

Portfolio Summary

• Skills reviewed:
• Highest-risk skills:
• Common issue clusters:

Priority Backlog

P0

-

P1

-

P2

-

Common Skill Anti-Patterns

Collection of common mistakes and anti-patterns to avoid when creating Claude Skills. Learn from these examples to improve your skills.

Anti-Pattern 1: Vague Description (F Grade)

The Problem

---
name: helper-skill
description: Use this skill to help with various tasks and provide useful
assistance for users.
version: 1.0.0
---

Why this fails:

• ❌ No specific trigger phrases
• ❌ Second person ("Use this skill")
• ❌ Vague and generic
• ❌ No clue what it actually does
• ❌ Users will never discover it

Score Impact

The Fix

---
name: api-contract-manager
description: This skill should be used when the user asks to "validate API
contract", "check API compatibility", "version API schema", or "detect
breaking changes". Manages API contracts through validation, versioning,
and compatibility checking for OpenAPI 3.0 specifications.
version: 1.0.0
---

Improvement: 0/100 → 90/100 in description quality

---

Anti-Pattern 2: Second Person Throughout (D Grade)

The Problem

# My Skill

## Overview
You should use this skill when you need to process data files.

## How to Use
First, you need to select your input file. You can choose from CSV,
JSON, or XML formats. Then you should configure the processing options.

## Configuration
You can set the following options:
- You must specify the output format
- You should choose a delimiter
- You need to define the schema

Why this fails:

• ❌ "You should", "you need", "you can" throughout
• ❌ Not imperative form
• ❌ Conversational rather than instructional
• ❌ Unprofessional tone

Score Impact

The Fix

# Data File Processor

## Overview
Process data files in CSV, JSON, or XML formats with configurable
schemas and output options.

## Usage
Select the input file. Configure processing options. Specify output
format and delimiter.

## Configuration
Set the following options:
- Output format (required)
- Field delimiter
- Data schema

Improvement: 5/100 → 85/100 in writing style

---

Anti-Pattern 3: Everything in One File (C Grade)

The Problem

my-skill/
└── SKILL.md (12,000 words)

SKILL.md contains:

• Overview
• Detailed API documentation (3,000 words)
• 20 complete code examples (5,000 words)
• Troubleshooting guide (2,000 words)
• FAQ (1,000 words)
• Changelog (1,000 words)

Why this is problematic:

• ❌ SKILL.md is 12,000 words (should be <5,000)
• ❌ Detailed content always loaded
• ❌ Wastes tokens on rarely-used content
• ❌ Difficult to navigate
• ❌ Violates progressive disclosure

Score Impact

The Fix

my-skill/
├── SKILL.md (1,800 words)
├── references/
│   ├── api-reference.md (3,000 words)
│   ├── troubleshooting.md (2,000 words)
│   └── faq.md (1,000 words)
└── examples/
    ├── basic-usage.md (1,000 words)
    ├── advanced-usage.md (2,000 words)
    └── edge-cases.md (2,000 words)

SKILL.md now contains:

• Overview
• Quick start
• Basic operations
• Links to detailed references

Improvement: 10/100 → 85/100 in content organization

---

Anti-Pattern 4: Missing Required Fields (F Grade)

The Problem

---
name: my-skill
# Missing description!
version: 1.0.0
author: Someone
tags: [utility, helper]
---

Why this fails:

• ❌ Missing required description field
• ❌ Skill will never trigger
• ❌ Has unnecessary fields (author, tags)
• ❌ Cannot be discovered

Score Impact

The Fix

---
name: data-validator
description: This skill should be used when the user asks to "validate data",
"check data format", "verify data schema", or "sanitize input". Validate and
sanitize data files against JSON schemas with support for custom validation
rules.
version: 1.0.0
---

Improvement: F → B- (80) overall

---

Anti-Pattern 5: Broken References (D Grade)

The Problem

SKILL.md says:

## Additional Resources

See `references/api-guide.md` for complete API documentation.
Check `examples/complete-example.py` for a working example.

Actual directory structure:

my-skill/
├── SKILL.md
├── references/
│   └── setup-guide.md  # No api-guide.md!
└── examples/
    └── basic-example.py  # No complete-example.py!

Why this fails:

• ❌ Referenced files don't exist
• ❌ Users get errors when trying to follow references
• ❌ Incomplete skill structure

Score Impact

The Fix

Option 1: Create the referenced files

my-skill/
├── SKILL.md
├── references/
│   ├── api-guide.md  # Created!
│   └── setup-guide.md
└── examples/
    ├── complete-example.py  # Created!
    └── basic-example.py

Option 2: Update SKILL.md to match actual files

## Additional Resources

See `references/setup-guide.md` for setup instructions.
Check `examples/basic-example.py` for a working example.

Improvement: 15/100 → 90/100 in structural integrity

---

Anti-Pattern 6: Inconsistent Style (C Grade)

The Problem

## Workflow

### Step 1: Prepare
First you should create the directory structure.

### Step 2: Configure
Configure the settings file. You need to specify the endpoint.

### Step 3: Deploy
Deploy the application. Check the logs to verify.

Why this fails:

• ❌ Mixes imperative ("Configure", "Deploy") with second person ("you should")
• ❌ Inconsistent throughout
• ❌ Confusing to read

Score Impact

The Fix

## Workflow

### Step 1: Prepare
Create the directory structure.

### Step 2: Configure
Specify the endpoint in the settings file.

### Step 3: Deploy
Deploy the application. Verify by checking the logs.

Improvement: 30/100 → 85/100 in writing style

---

Anti-Pattern 7: Overly Long Description (B Grade)

The Problem

---
name: file-processor
description: This skill should be used when the user asks to "process files",
"convert file formats", "validate file structure", "check file integrity",
"transform file data", "merge multiple files", "split large files", "compress
file size", "encrypt file contents", "decrypt file contents", "archive files",
"extract archives", "generate file checksums", "verify file signatures", or
"optimize file storage". This comprehensive file processing utility supports
over 50 different file formats including PDF, DOCX, XLSX, CSV, JSON, XML,
HTML, TXT, and many more. It provides advanced features like batch processing,
parallel execution, error recovery, automatic backup creation, detailed logging,
progress tracking, and notification support. Ideal for data migration tasks,
content management workflows, archival operations, and file system maintenance.
version: 1.0.0
---

Why this is problematic:

• ❌ 900+ characters (way too long)
• ❌ Lists too many trigger phrases (dilutes effectiveness)
• ❌ Becomes unreadable
• ❌ Loses focus

Score Impact

The Fix

---
name: file-processor
description: This skill should be used when the user asks to "process files",
"convert file formats", "validate file structure", "merge files", or
"compress files". Supports common formats (PDF, DOCX, CSV, JSON) with
batch processing and error recovery.
version: 1.0.0
---

Improvement: 15/100 → 85/100 in description quality

---

Anti-Pattern 8: No Examples (C Grade)

The Problem

my-skill/
├── SKILL.md (2,000 words of theory)
└── references/
    └── detailed-guide.md (3,000 words more theory)

SKILL.md describes concepts but never shows:

• How to actually use the skill
• What input looks like
• What output looks like
• Concrete usage patterns

Why this fails:

• ❌ Users can't visualize usage
• ❌ No working code to copy
• ❌ Theory without practice

Score Impact

The Fix

my-skill/
├── SKILL.md (2,000 words)
├── references/
│   └── detailed-guide.md
└── examples/
    ├── basic-usage.sh (working example)
    ├── advanced-usage.sh (working example)
    └── input-output-examples.md (before/after)

Improvement: 50/100 → 85/100 in structural integrity

---

Anti-Pattern 9: Subjective Language (D Grade)

The Problem

## Overview

This is a really great skill that I think you'll find super useful.
It's awesome for handling difficult tasks. The best part is how
easy it is to use - you'll love it!

## Features

- Amazing performance
- Incredible flexibility
- Fantastic user experience

Why this fails:

• ❌ Highly subjective ("really great", "super useful")
• ❌ Marketing language, not instructional
• ❌ First person ("I think")
• ❌ Unprofessional tone
• ❌ No concrete information

Score Impact

The Fix

## Overview

Handle complex data processing tasks with configurable validation
and error recovery. Supports CSV, JSON, and XML formats with
batch processing capabilities.

## Features

- Processes 10,000+ records per second
- Configurable validation rules
- Automatic error recovery
- Detailed logging

Improvement: 20/100 → 80/100 in writing style

---

Anti-Pattern 10: Invalid YAML (F Grade)

The Problem

---
name: my-skill
description: This skill should be used when the user asks to "validate data"
or "check schemas". It's designed for: data validation, schema checking, and
format verification.
version: 1.0.0
---

Error: Colon after "for" creates invalid YAML syntax

Why this fails:

• ❌ YAML cannot be parsed
• ❌ Skill fails to load
• ❌ Completely non-functional

Score Impact

The Fix

---
name: data-validator
description: This skill should be used when the user asks to "validate data",
"check schemas", or "verify formats". Performs data validation, schema
checking, and format verification.
version: 1.0.0
---

Improvement: F → B (83) overall

---

Quick Anti-Pattern Checklist

Description Quality

• [ ] Not vague like "helps with tasks"
• [ ] Has 3-5 specific trigger phrases
• [ ] Uses third person, not second person
• [ ] Is 100-300 characters long
• [ ] Mentions concrete use cases

Content Organization

• [ ] SKILL.md under 5,000 words
• [ ] Detailed content in references/
• [ ] Examples in examples/ directory
• [ ] Progressive disclosure followed

Writing Style

• [ ] No "you", "your", "you're" in body
• [ ] Uses imperative verbs (Create, Check, Run)
• [ ] Objective and factual
• [ ] No marketing language

Structural Integrity

• [ ] YAML has name and description
• [ ] All referenced files exist
• [ ] Examples are complete
• [ ] Scripts are executable

---

Learn From Mistakes

Each anti-pattern above represents real issues found in actual skills. Avoid these common mistakes:

1. Vague descriptions → Be specific with trigger phrases 2. Second person → Use imperative form 3. No progressive disclosure → Move details to references/ 4. Missing fields → Include name and description 5. Broken references → Verify all files exist 6. Inconsistent style → Stick to imperative form 7. Too long description → Keep under 300 characters 8. No examples → Include working code 9. Subjective language → Be factual and objective 10. Invalid YAML → Validate YAML syntax

Use examples-good.md as a reference for what to do right.

Exemplary Skill Examples

Collection of high-quality skill examples demonstrating best practices across all quality dimensions. Study these when creating or improving skills.

Example 1: hook-development (A+ Grade)

An exemplary skill demonstrating excellent description quality, progressive disclosure, and writing style.

Frontmatter (Description Quality)

---
name: hook-development
description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
"use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous
commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop,
SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides
comprehensive guidance for creating and implementing Claude Code plugin hooks
with focus on advanced prompt-based hooks API.
version: 0.1.0
---

Why this is excellent:

• ✅ 8+ specific trigger phrases covering diverse scenarios
• ✅ Third-person format throughout
• ✅ Includes specific hook events for precision
• ✅ Mentions key concepts (prompt-based hooks API)
• ✅ Length is appropriate (~400 characters, acceptable for complex skill)

Progressive Disclosure (Content Organization)

SKILL.md structure:

• Overview (50 words)
• Core concepts (200 words)
• Hook events reference (300 words)
• Development workflow (500 words)
• Best practices (400 words)
• Total: ~1,650 words - excellent length

References/ directory:

references/
├── prompt-based-hooks.md (800 words) - Detailed guide
├── hook-patterns.md (1,200 words) - Common patterns
└── migration-guide.md (900 words) - Migration info

Why this is excellent:

• ✅ SKILL.md is concise and focused
• ✅ Detailed content moved to 3 reference files
• ✅ Clear progressive disclosure
• ✅ Each reference file has specific purpose

Writing Style (Imperative Form)

Example from SKILL.md:

## Hook Development Workflow

### Step 1: Define the Hook Event
Identify which event the hook should trigger on. Review available events
in the Hook Events Reference section.

### Step 2: Create hooks.json
Create a hooks.json file in the plugin's .claude-plugin/ directory.
Specify the event type and command to execute.

### Step 3: Implement the Hook Script
Write the hook script. Ensure it is executable. Follow the prompt-based
hooks API for complex hooks.

### Step 4: Test the Hook
Test the hook locally. Verify it triggers on the correct event.
Check output and error handling.

Why this is excellent:

• ✅ Every instruction uses imperative form
• ✅ No "you", "your", "should"
• ✅ Clear, actionable steps
• ✅ Consistent style throughout

---

Example 2: agent-development (A Grade)

Strong skill with good description and organization.

Frontmatter

---
name: agent-development
description: This skill should be used when the user asks to "create an agent",
"add an agent", "write a subagent", "agent frontmatter", "when to use description",
"agent examples", "agent tools", "agent colors", "autonomous agent", or needs
guidance on agent structure, system prompts, triggering conditions, or agent
development best practices for Claude Code plugins.
version: 0.1.0
---

Strengths:

• ✅ Multiple specific trigger phrases
• ✅ Covers agent creation scenarios
• ✅ Mentions specific agent attributes

Directory Structure

agent-development/
├── SKILL.md (1,438 words)
├── references/
│   ├── agent-generation-prompt.md (500 words)
│   └── agent-anatomy.md (400 words)
└── examples/
    ├── task-agent.md (complete example)
    ├── review-agent.md (complete example)
    └── interactive-agent.md (complete example)

Strengths:

• ✅ Lean SKILL.md
• ✅ Focused reference files
• ✅ Complete working examples
• ✅ Clear organization

---

Example 3: mcp-integration (A- Grade)

Comprehensive skill with excellent progressive disclosure.

Frontmatter

---
name: mcp-integration
description: This skill should be used when the user asks to "add MCP server",
"integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model
Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT}
with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides
comprehensive guidance for integrating Model Context Protocol servers into Claude
Code plugins for external tool and service integration.
version: 0.1.0
---

Strengths:

• ✅ Specific MCP-related trigger phrases
• ✅ Lists server types for precision
• ✅ Mentions key configuration elements

Progressive Disclosure

SKILL.md: ~1,800 words (core concepts, basic setup)

References/:

• mcp-server-types.md - Detailed server type comparisons
• mcp-configuration.md - Configuration examples
• mcp-best-practices.md - Integration patterns
• mcp-troubleshooting.md - Common issues

Why this works:

• ✅ Main SKILL.md covers essentials
• ✅ Each reference is 1,000-2,000 words
• ✅ Loaded only when needed
• ✅ Clear topic separation

---

Excellent Description Examples

Example: API-Contract Skill (Ideal Description)

---
name: api-contract-manager
description: This skill should be used when the user asks to "validate API contract",
"check API compatibility", "version API schema", "detect breaking changes", or
"ensure API contract compliance". Manages API contracts through validation,
versioning, and compatibility checking. Use when designing new endpoints or
ensuring backward compatibility.
version: 0.1.0
---

Analysis:

• ✅ 5 specific trigger phrases
• ✅ Third person throughout
• ✅ 230 characters (ideal length)
• ✅ Clear use cases
• ✅ Mentions when to use (designing, compatibility)

Example: PDF-Editor Skill (Ideal Description)

---
name: pdf-editor
description: This skill should be used when the user asks to "rotate PDF", "merge
PDF files", "split PDF pages", "compress PDF", or "crop PDF pages". Perform common
PDF manipulation operations including rotation, merging, splitting, compression,
and cropping. Works with local PDF files.
version: 0.1.0
---

Analysis:

• ✅ 5 specific operations as triggers
• ✅ Lists all supported operations
• ✅ Specifies working context (local files)
• ✅ 180 characters (excellent length)

---

Excellent Progressive Disclosure Examples

Example: Frontend-Builder Skill

SKILL.md (1,800 words):

• Overview
• Quick Start (5 steps)
• Basic Component Creation
• Common Operations
• Reference to detailed guides

References/:

• react-patterns.md (2,500 words) - React specific patterns
• vue-patterns.md (2,000 words) - Vue specific patterns
• styling-guide.md (1,800 words) - CSS/styling approaches
• deployment.md (1,500 words) - Build and deploy

Examples/:

• hello-world-react/ - Complete React example
• hello-world-vue/ - Complete Vue example
• component-library/ - Reusable components

Why this works: 1. SKILL.md gets users started quickly 2. Framework-specific details in references/ 3. Complete examples for copy-paste 4. Progressive: overview → basics → details → examples

---

Excellent Writing Style Examples

Example: From Test-Driven Development Skill

## TDD Workflow

### Red: Write a Failing Test
Start by writing a test that fails. This test defines the desired behavior.
Run the test to confirm it fails.

### Green: Make the Test Pass
Write the minimum code to make the test pass. Focus on making it work,
not making it perfect. Run the test to confirm it passes.

### Refactor: Improve the Code
Refactor the code while keeping tests green. Improve structure, readability,
and maintainability. Run tests after each change.

### Repeat
Continue the cycle for each feature. Write test, make it pass, refactor.

Analysis:

• ✅ Imperative form throughout
• ✅ Clear, actionable instructions
• ✅ No second person
• ✅ Consistent style
• ✅ Easy to follow

---

Excellent Reference File Organization

Example: Git-Workflow Skill References

references/
├── commit-conventions.md (1,500 words)
│   ├── Commit message format
│   ├── Type categories
│   ├── Scope values
│   └── Examples by type
├── branch-strategy.md (1,800 words)
│   ├── Branch types
│   ├── Merging policies
│   ├── Release workflow
│   └── Hotfix procedures
└── troubleshooting.md (1,200 words)
    ├── Common issues
    ├── Recovery procedures
    └── Best practices

Each reference file:

• ✅ Focused on single topic
• ✅ Self-contained
• ✅ Cross-references others when needed
• ✅ Loaded only when relevant

---

Key Takeaways from Excellent Skills

1. Description Quality

Good descriptions:

• Have 5+ specific trigger phrases
• Use third person consistently
• Are 100-300 characters long
• Include concrete use cases

Example template:

description: This skill should be used when the user asks to "action 1",
"action 2", "action 3", or "action 4". Brief description of what the skill
does. When to use it.

2. Progressive Disclosure

Good organization:

• SKILL.md: 1,500-2,000 words (core only)
• references/: 1,500-2,500 words per file (details)
• examples/: Complete working code
• scripts/: Utility tools

Rule of thumb: If a section exceeds 500 words and covers details, consider moving it to references/.

3. Writing Style

Good style:

• Use imperative verbs: Create, Validate, Check, Run
• Avoid: You should, You can, You need to
• Be objective and factual
• Keep instructions actionable

4. Structural Integrity

Good structure:

skill-name/
├── SKILL.md (required)
├── references/ (optional, for details)
├── examples/ (optional, for working code)
└── scripts/ (optional, for utilities)

Validation checklist:

• [ ] YAML frontmatter has name and description
• [ ] All referenced files exist
• [ ] Examples are complete
• [ ] Scripts are executable

---

Study These Skills

For hands-on learning, study these high-quality skills in your environment:

# Explore hook-development structure
ls -la ~/.claude/plugins/cache/*/skills/hook-development/

# Read agent-development SKILL.md
cat ~/.claude/skills/agent-development/SKILL.md

# Review mcp-integration references
ls -la ~/.claude/skills/mcp-integration/references/

Each demonstrates different strengths:

• hook-development: Progressive disclosure, utilities
• agent-development: Clean examples, focused content
• mcp-integration: Comprehensive references, clear organization

Use these as templates when creating or improving your own skills.

Skill Quality Scoring Criteria

Detailed evaluation rubrics for each quality dimension assessed by the skill-quality-reviewer.

1. Description Quality (25% Weight)

Assesses the effectiveness of the frontmatter description in triggering the skill appropriately.

Scoring Breakdown

Trigger Phrases Clarity (0-25 points)

25 points (Excellent):

• 5+ specific, concrete trigger phrases
• Phrases cover diverse use cases
• Each phrase is something a user would naturally say
• Phrases include both specific tasks and general scenarios

Example:

description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
"set up event-driven automation", or mentions hook events (PreToolUse, PostToolUse,
Stop, SubagentStop).

20 points (Good):

• 3-4 specific trigger phrases
• Good variety of scenarios
• Most phrases are natural user language

15 points (Acceptable):

• 2-3 trigger phrases
• Some variety but may miss key scenarios
• Phrases are reasonably specific

10 points (Needs Work):

• 1-2 trigger phrases
• Limited variety
• Some phrases too generic

5 points (Poor):

• Single vague trigger phrase
• Missing common use cases

0 points (Fail):

• No trigger phrases
• Trigger phrases are meaningless

---

Third-Person Format (0-25 points)

25 points (Excellent):

• Consistently uses "This skill should be used when..."
• Never uses second person ("you", "your")
• Professional, objective tone

20 points (Good):

• Generally uses third person
• Minor inconsistencies but overall correct

10 points (Needs Work):

• Mix of third and second person
• Inconsistent formatting

0 points (Fail):

• Uses second person ("Use this when you want...")
• First person references

---

Description Length (0-25 points)

25 points (Excellent):

• 150-300 characters
• Concise yet comprehensive
• No unnecessary words

20 points (Good):

• 100-150 or 300-400 characters
• Slightly short or long but acceptable

15 points (Acceptable):

• 80-100 or 400-500 characters
• Beginning to be too concise or verbose

10 points (Needs Work):

• 50-80 or 500-700 characters
• Too brief or too verbose

5 points (Poor):

• Under 50 or over 700 characters

0 points (Fail):

• Effectively empty or extremely long

---

Specific Scenarios (0-25 points)

25 points (Excellent):

• Multiple concrete scenarios mentioned
• Clear scope boundaries (when NOT to use)
• Specific domains or use cases identified

Example:

description: ... Use when designing new API endpoints, validating existing
contracts, or checking breaking changes. NOT for general API testing or
documentation generation.

20 points (Good):

• Good scenario coverage
• Clear use cases

15 points (Acceptable):

• Basic scenario descriptions
• Could be more specific

10 points (Needs Work):

• Vague scenarios
• Unclear when to use

0 points (Fail):

• No scenarios mentioned
• Purely generic description

---

2. Content Organization (30% Weight)

Evaluates adherence to progressive disclosure principles and effective content organization.

Scoring Breakdown

Progressive Disclosure (0-30 points)

30 points (Excellent):

• SKILL.md under 2,000 words
• All detailed content in references/
• Clear separation of overview and details
• References/ properly organized with multiple files

25 points (Good):

• SKILL.md 2,000-3,000 words
• Most detailed content moved to references/
• Good separation of concerns

20 points (Acceptable):

• SKILL.md 3,000-5,000 words
• Some detailed content still in SKILL.md
• References/ used but could be better

15 points (Needs Work):

• SKILL.md 5,000-7,000 words
• Significant content should be moved
• Limited use of references/

10 points (Poor):

• SKILL.md over 7,000 words
• Minimal or no references/ usage

0 points (Fail):

• Everything in one large file
• No progressive disclosure

---

SKILL.md Length Control (0-25 points)

25 points (Excellent):

• 1,500-2,000 words (optimal)
• Every word serves a purpose
• No redundancy

20 points (Good):

• 1,000-1,500 or 2,000-3,000 words
• Generally concise

15 points (Acceptable):

• 800-1,000 or 3,000-4,000 words
• Some unnecessary content

10 points (Needs Work):

• 500-800 or 4,000-5,000 words
• Could be significantly trimmed

5 points (Poor):

• Under 500 or over 5,000 words
• Major length issues

---

References/ Usage (0-25 points)

25 points (Excellent):

• 3+ well-organized reference files
• Clear topics (patterns, advanced, examples, etc.)
• Properly referenced in SKILL.md
• Each file has clear purpose

20 points (Good):

• 2-3 reference files
• Good organization
• Referenced in SKILL.md

15 points (Acceptable):

• 1-2 reference files
• Basic organization

10 points (Needs Work):

• Single reference file or poorly organized
• Not well referenced

5 points (Poor):

• References/ exists but minimal content
• Not referenced from SKILL.md

0 points (Fail):

• No references/ directory when clearly needed

---

Logical Organization (0-20 points)

20 points (Excellent):

• Clear section hierarchy
• Logical flow from overview to details
• Easy to navigate
• Consistent structure

15 points (Good):

• Generally well organized
• Minor flow issues

10 points (Acceptable):

• Basic organization present
• Some structural confusion

5 points (Needs Work):

• Poor organization
• Difficult to follow

0 points (Fail):

• No clear structure
• Content randomly arranged

---

3. Writing Style (20% Weight)

Evaluates adherence to skill writing conventions and style consistency.

Scoring Breakdown

Imperative Form Usage (0-40 points)

40 points (Excellent):

• 95%+ of instructions use imperative form
• Consistent throughout
• Natural, readable instructions

Good examples:

Create the skill directory structure.
Validate the YAML frontmatter.
Check for required fields.
Read the SKILL.md file.
Generate the quality report.

30 points (Good):

• 80-95% imperative form
• Generally consistent
• Minor exceptions

20 points (Acceptable):

• 60-80% imperative form
• Inconsistent usage

10 points (Needs Work):

• 40-60% imperative form
• Significant inconsistency

0 points (Fail):

• Less than 40% imperative form
• Mostly descriptive or second-person

---

No Second Person (0-30 points)

30 points (Excellent):

• Zero instances of "you", "your", "you're"
• Clean imperative style throughout

20 points (Good):

• 1-3 minor instances
• Generally avoids second person

10 points (Acceptable):

• 4-6 instances
• Some second person creeping in

5 points (Needs Work):

• 7-10 instances
• Frequent second person

0 points (Fail):

• 10+ instances
• Heavily uses second person

---

Objective Language (0-30 points)

30 points (Excellent):

• Factual, instructional tone
• No subjective opinions
• Professional language
• Clear and direct

20 points (Good):

• Generally objective
• Minor subjectivity

15 points (Acceptable):

• Mostly objective with some opinion
• Generally professional

10 points (Needs Work):

• Subjective language present
• Conversational tone

0 points (Fail):

• Highly subjective
• Unprofessional or casual tone

---

4. Structural Integrity (25% Weight)

Evaluates the physical structure, completeness, and correctness of the skill.

Scoring Breakdown

YAML Frontmatter (0-30 points)

30 points (Excellent):

• All required fields present (name, description)
• Optional fields used appropriately (version)
• Valid YAML syntax
• No prohibited fields
• Well-formatted

Example of excellent frontmatter:

---
name: skill-quality-reviewer
description: This skill should be used when the user asks to "analyze skill quality",
"evaluate this skill", "review skill quality", or mentions quality review of Claude Skills.
version: 0.1.0
---

25 points (Good):

• All required fields present
• Valid YAML
• Minor formatting issues

20 points (Acceptable):

• Required fields present
• Valid YAML
• Some missing recommended fields

10 points (Needs Work):

• Missing some required fields
• YAML issues present

0 points (Fail):

• Missing required fields
• Invalid YAML syntax
• Cannot parse frontmatter

---

Directory Structure (0-30 points)

30 points (Excellent):

• Proper skill structure:

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

• Each subdirectory has clear purpose
• No unnecessary files
• Clean naming conventions

25 points (Good):

• Core structure correct
• Minor organization issues

20 points (Acceptable):

• Basic structure present
• Some organizational issues

10 points (Needs Work):

• Missing key directories
• Poor organization

0 points (Fail):

• No clear structure
• Chaotic organization

---

Resource References (0-40 points)

40 points (Excellent):

• All referenced files exist
• References are accurate and specific
• Examples are complete and working
• Scripts are executable
• No broken links or references

Check method:

• Read SKILL.md
• Extract all references to files (e.g., references/patterns.md)
• Verify each file exists
• Verify examples/ and scripts/ contents

30 points (Good):

• All references exist
• Minor issues with completeness

20 points (Acceptable):

• Most references valid
• Some broken or incomplete references

10 points (Needs Work):

• Multiple broken references
• Incomplete examples

0 points (Fail):

• Many broken references
• Examples don't work
• Scripts not executable

---

Grade Calculation

Weighted Score Formula

Overall Score = (Description Quality × 0.25) +
                (Content Organization × 0.30) +
                (Writing Style × 0.20) +
                (Structural Integrity × 0.25)

Letter Grade Mapping

Certification Thresholds

For "Certified" status (recommended for sharing):

• Overall score: ≥80/100
• Description Quality: ≥75/100
• Content Organization: ≥75/100
• Writing Style: ≥70/100
• Structural Integrity: ≥80/100

---

Quick Reference Scoring Guide

Description Quality Quick Checks

• [ ] Description has 3-5 specific trigger phrases
• [ ] Uses third person ("This skill should be used when...")
• [ ] Length is 100-300 characters
• [ ] Mentions concrete use cases

Content Organization Quick Checks

• [ ] SKILL.md under 5,000 words (ideally 1,500-2,000)
• [ ] Detailed content in references/
• [ ] Examples in examples/ directory
• [ ] Scripts in scripts/ directory

Writing Style Quick Checks

• [ ] Instructions use verbs (Create, Validate, Check)
• [ ] No "you", "your", "you're" in body
• [ ] Objective, instructional tone
• [ ] Consistent style throughout

Structural Integrity Quick Checks

• [ ] YAML has name and description
• [ ] All referenced files exist
• [ ] Examples are complete
• [ ] Scripts are executable

---

Common Scenarios

Scenario 1: New Skill Submission

Context: Developer submits a new skill for review.

Evaluation Focus:

• Description quality (is it clear when to use?)
• Progressive disclosure (is content organized?)
• Writing style (does it follow conventions?)

Passing Criteria: B- (80) or higher overall

---

Scenario 2: Skill Quality Audit

Context: Periodic review of existing skills.

Evaluation Focus:

• All dimensions equally
• Identify improvement opportunities
• Track quality over time

Passing Criteria: C (73) or higher overall

---

Scenario 3: Pre-Publication Check

Context: Final check before sharing skill publicly.

Evaluation Focus:

• Structural integrity (must be complete)
• Description quality (must be discoverable)
• No critical issues

Passing Criteria: B (83) or higher overall

---

This scoring criteria document provides the detailed rubrics used by skill-quality-reviewer to evaluate Claude Skills. Use this as a reference when interpreting quality reports or planning improvements.