Reviewing Skills

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.