richtabor/agent-skills/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:

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

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.