Skill Review Skill | Agent Skills

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

[Actionable fix]
[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.

Agent Skills: Skill Review

Install this agent skill to your local

Skill Files