Reviewing Skills

Comprehensive review of agent skills against Claude's official best practices.

Quick Start

To review a skill:

1. •Ask user for skill path (e.g., .claude/skills/skill-name/)
2. •Read SKILL.md and analyze structure
3. •Check against best practices
4. •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:

## 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.