skill-review

Skill Review

Overview

Validates agent skills against the Agent Skills standard and compiled best practices. Reviews structure, frontmatter, description quality, progressive disclosure, and common anti-patterns.

When to Use

• User asks to review or validate a skill
• User is creating a new skill and wants feedback
• User asks "is this skill well-written?"
• User mentions skill quality, best practices, or improvement

Review Process

Phase 1: Load References

Before reviewing, read:

• references/best-practices.md — Comprehensive guidelines
• references/checklist.md — Quick validation checklist

Phase 2: Identify Target

Determine what to review:

• Single skill: Review skills/<name>/SKILL.md and its structure
• All skills: Audit entire skills/ directory
• New skill draft: Review provided content before creation

Phase 3: Structural Audit

Check the skill directory structure:

skill-name/
├── SKILL.md              # Required
├── references/           # Optional - loaded docs
├── scripts/              # Optional - executable code
└── assets/               # Optional - output files (not loaded)

Verify:

• SKILL.md exists
• Directory name matches name in frontmatter
• References are one level deep (no nested chains)
• Scripts use forward slashes (no Windows paths)
• No extraneous files (README.md, CHANGELOG.md, etc.)
• Script paths in SKILL.md body (scripts/foo.py) exist in directory
• If scripts use external binaries, dependencies are documented

Phase 4: Frontmatter Validation

Check YAML frontmatter:

---
name: skill-name          # Required: lowercase, hyphens, ≤64 chars
description: >-           # Required: ≤1024 chars, third-person
  What it does. When to use it.
---

Validate:

• name: Lowercase with hyphens only ([a-z0-9-])
• name: ≤64 characters
• name: No "anthropic" or "claude" in name
• description: Non-empty, ≤1024 characters
• description: Third-person voice (not "I can" or "You can")
• description: Includes what it does AND when to trigger
• description: Contains specific trigger phrases

Phase 5: Description Quality

The description is the triggering mechanism. Evaluate:

Good descriptions include:

• Specific actions: "Extract text and tables from PDF files"
• Trigger phrases: "Use when analyzing Excel files, spreadsheets, or .xlsx"
• Synonyms users might say: "tabular data, CSV, workbooks"

Bad descriptions:

• Vague: "Helps with documents"
• Generic: "Processes data"
• Missing triggers: "Analyzes spreadsheets" (no "when to use")

Phase 6: Body Analysis

Review SKILL.md body content:

Length:

• Under 500 lines (check with wc -l)
• If longer, split into reference files

Progressive Disclosure:

• Quick start or overview near top
• Details moved to references/
• Long reference files (>100 lines) have TOC

Token Efficiency:

• No obvious explanations (Claude already knows)
• Examples over lengthy prose
• Each line justifies its token cost

Degrees of Freedom:

• High freedom for context-dependent tasks
• Low freedom for fragile/error-prone tasks
• Defaults provided when multiple options exist

Phase 7: Anti-Pattern Check

Scan for common issues:

Anti-Pattern	Look For
Windows paths	scripts\file.py instead of scripts/file.py
Nested references	A.md → B.md → C.md chains
Time-sensitive info	"If before August 2025..."
Magic numbers	Unexplained values
Too many options	"You can use X, or Y, or Z..." without default
Inconsistent terms	Mixing "endpoint"/"URL"/"route"
User-facing docs	README, CHANGELOG, installation guides
First/second person descriptions	"I can help" or "You can use"

Phase 8: Report Findings

Present findings using this format:

## Skill Review: [skill-name]

### Summary
[1-2 sentence overall assessment]

### Structure
[✓/✗] Directory organization
[✓/✗] File presence
[✓/✗] Reference depth

### Frontmatter
[✓/✗] name validation
[✓/✗] description validation

### Description Quality
**Score**: [Strong / Adequate / Needs Work]
**Issues**: [List specific problems]
**Suggested rewrite** (if needed):
```yaml
description: >-
  [Improved description]

Body Analysis

Line count: [X] lines Token efficiency: [Good / Could trim] Progressive disclosure: [✓/✗]

Anti-Patterns Found

• [Issue 1] — Location: file:line
• [Issue 2] — Location: file:line

Recommendations

1. [Actionable fix]
2. [Actionable fix]

## Quick Review Mode

For rapid validation, run through the checklist in `references/checklist.md` and report only failures.

## Resources

### references/best-practices.md
Comprehensive guide covering architecture, design principles, writing effective descriptions, bundled resources, workflow patterns, and advanced patterns from production skills.

### references/checklist.md
Quick-reference validation checklist for fast reviews.