Comprehensive review of agent skills against Claude's official best practices.
Quick Start
To review a skill:
- Ask user for skill path (e.g.,
.claude/skills/skill-name/) - Read SKILL.md and analyze structure
- Check against best practices
- Provide detailed feedback with priorities
Example review output:
## Compliance Score
- Naming: ✓ Excellent - `processing-pdfs` (gerund form)
- Description: ⚠ Needs work - Missing "when to use"
- Size: ✓ Good - 234 lines
Important Issues
- Add "Use when..." to description for better triggering
## Review Process
### Step 1: Initial Analysis
Read and analyze:
- SKILL.md (frontmatter and body)
- Directory structure
- Reference files (if any)
- Scripts/assets (if any)
### Step 2: Core Compliance Checks
**Naming** (gerund form preferred):
- ✓ Good: `processing-pdfs`, `analyzing-data`, `managing-workflows`
- ✗ Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
- Requirements: max 64 chars, lowercase/numbers/hyphens only, no XML tags
**Description** (third person, what + when):
- ✓ Specific with key terms
- ✓ Includes both what it does and when to use it
- ✗ Vague ("helps with documents")
- Requirements: non-empty, max 1024 chars, no XML tags, third person only
**SKILL.md Size**:
- Target: <500 lines (ideally 200-400)
- If >500 lines: suggest moving content to references
**Progressive Disclosure**:
- Level 1: Metadata (name + description) always loaded
- Level 2: SKILL.md body loaded when triggered
- Level 3: References loaded as needed
- Check: Are details properly split into reference files?
**Single Responsibility**:
- Does skill focus on one clear purpose?
- Or does it try to be a multi-purpose helper?
**allowed-tools** (if present):
- ✗ Too broad: `Bash(git:*)` (includes destructive operations)
- ✓ Specific: `Bash(git status:*) Bash(git diff:*) Bash(git log:*)`
- ✗ Unnecessary: `Read`, `Glob` (already allowed by default)
- ✗ Dangerous: `Edit`, `Write`, `Bash(rm:*)` (destructive tools should not be pre-approved)
- Check: Are only non-destructive commands allowed?
- Check: Are subcommands specified explicitly?
### Step 3: Detailed Structure Review
**File Organization**:
- Required: SKILL.md, tests/scenarios.md
- Optional: README.md (human-facing), references/, scripts/, assets/
- Should NOT exist: CHANGELOG.md, INSTALLATION_GUIDE.md
**Reference Depth**:
- References should be one level deep from SKILL.md
- Avoid: SKILL.md → ref1.md → ref2.md (too nested)
- Good: SKILL.md → ref1.md, ref2.md, ref3.md
**Reference Files**:
- Files >100 lines should have table of contents
- **Check TOC presence**: If reference file >100 lines, verify table of contents exists at top
- Descriptive file names (not `doc1.md`, `misc.md`)
- Domain-specific organization when appropriate
**Content Quality**:
- Concise (only what Claude doesn't know)
- No time-sensitive information
- Consistent terminology
- Concrete examples
- Clear workflows
**Workflows and Validation** (see checklist.md for detailed criteria):
- [ ] Complex workflows include checklists for progress tracking
- [ ] Validation patterns used appropriately (plan-validate-execute, validate script, feedback loop)
- [ ] Validation scripts have clear, actionable error messages
- [ ] Workflows explain recovery steps when validation fails
- [ ] Validation level matches task risk (high-risk tasks should have validation)
**README.md** (optional but recommended):
- [ ] If exists, includes installation instructions and required permissions
- [ ] Explains file structure (especially `tests/scenarios.md` as self-evaluation scenarios)
- [ ] Clearly human-facing (not duplicating SKILL.md content)
- [ ] Provides overview and usage guidance
### Step 4: Generate Feedback
Organize feedback by priority:
**Critical Issues** (must fix):
- Name violates requirements
- Description missing or invalid
- SKILL.md >500 lines without good reason
**Important Issues** (should fix):
- Poor naming (not gerund form, too vague)
- Weak description (missing "when to use", too vague)
- Duplicate information between SKILL.md and references
- Deeply nested references
- Missing progressive disclosure
- Missing tests/scenarios.md (required for multi-model testing)
**Suggestions** (nice to have):
- Could be more concise
- Could improve examples
- Could reorganize for clarity
- Could add reference files for long sections
### Step 5: Provide Actionable Feedback
For each issue:
1. Explain the problem
2. Show why it matters
3. Suggest specific fix
4. Provide example if helpful
Format:
```markdown
## Critical Issues
- **Issue**: [Problem description]
- **Why it matters**: [Impact explanation]
- **Fix**: [Specific action]
- **Example**: [If applicable]
## Important Issues
[Same format]
## Suggestions
[Same format]
Output Format
Structure review with these sections:
- Summary: Overall assessment, key strengths, areas for improvement
- Compliance Score: Naming, Description, Size, Progressive Disclosure, Structure (each with ✓/⚠/✗)
- Critical Issues: Must fix (with explanations and fixes)
- Important Issues: Should fix (with explanations and fixes)
- Suggestions: Nice to have (with improvements)
- Next Steps: Prioritized actions
See references/checklist.md for detailed criteria.