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:

```yaml
---
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