skill-reviewer

Skill Reviewer Subagent

Validate individual Agent Skills for specification compliance. Design supports parallel execution for batch validation.

Overview

This subagent examines a single skill directory and produces a structured validation report. It can run multiple instances in parallel to validate entire plugin skill libraries.

Typical use case:

INPUT: skill_directories = [skill1_path, skill2_path, skill3_path, ...]
  ↓
Run 3 parallel instances of skill-reviewer
  ↓
Aggregate reports into combined summary
  ↓
OUTPUT: { total: 3, passed: 2, failed: 1, warnings: 1, ... }

Validation Workflow

Step 1: Verify SKILL.md Exists

• Check: <input_path>/SKILL.md exists
• Error if: File missing or inaccessible
• Severity: Critical (skill is invalid without it)

Step 2: Parse Frontmatter

• Extract YAML frontmatter between --- delimiters
• Extract required fields: name, description
• Extract optional fields: license, compatibility, metadata, allowed-tools
• Error if: YAML is invalid (syntax error)
• Error if: Required fields missing

Step 3: Validate Required Fields

Name field:

• Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$ (lowercase alphanumeric-hyphens)
• Length: 1-64 characters
• Constraint: MUST match parent directory name
• Error if: Pattern invalid or name doesn't match directory
• Severity: Critical

Description field:

• Length: 1-1024 characters
• Error if: Too short (<10 chars) or too long (>1024)
• Warning if: Missing "Use when..." phrase (important for agent discovery)
• Severity: Error or Warning

Step 4: Check File Structure

Check for allowed subdirectories:

• scripts/ — Executable code
• references/ — Supporting documentation
• assets/ — Static resources

Error if: Other subdirectories found

• Examples of violations: examples/, docs/, tests/, __pycache__/

Severity: Warning (allowed but not spec-compliant)

Step 5: Analyze SKILL.md Content

• Count lines in SKILL.md
• Warning if: Exceeds 500 lines (suggests need for progressive disclosure)
• Detect: Presence of code examples, references, diagrams
• Detect: Programming languages used