Validate skill

You are validating a Claude Code skill against official best practices. Follow these steps:

Progress Checklist

Copy this checklist to track validation progress:

Skill Validation Progress:
- [ ] Step 0: Fetched latest official documentation
- [ ] Step 1: Located and read SKILL.md file
- [ ] Step 2: Validated frontmatter (name, description, fields)
- [ ] Step 3: Checked file structure and organization
- [ ] Step 4: Analyzed content quality (line count, clarity, workflows)
- [ ] Step 5: Verified references and progressive disclosure
- [ ] Step 6: Checked for anti-patterns and common issues
- [ ] Step 7: Generated comprehensive report with score

Step 0: Fetch Official Documentation

IMPORTANT: Always start by fetching the latest official documentation to ensure validation uses current standards.

Fetch the primary documentation sources:

1. Skills Documentation:

   • URL: https://code.claude.com/docs/en/skills
   • Prompt: "Extract all information about skill structure, SKILL.md format, frontmatter requirements, best practices, file organization, line count limits, progressive disclosure, and any specific guidelines for creating skills"

2. Best Practices Guide:

   • URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
   • Prompt: "Extract all best practices for creating agent skills, including structure, testing, writing guidelines, naming conventions, description format, common pitfalls to avoid, anti-patterns, and scoring criteria"

Store the fetched information for reference during validation steps.

Fallback: If WebFetch fails or documentation is unavailable, use the reference file references/best-practices-checklist.md as a fallback, but note in the report that validation used cached/fallback documentation.

Key criteria to extract from docs:

• Maximum line counts (SKILL.md body, description, name)
• Required frontmatter fields and formats
• Naming conventions (gerund form recommended)
• Description writing style (third person, trigger keywords)
• Progressive disclosure patterns
• Reference depth limits (1 level)
• Anti-patterns to avoid
• Scoring rubrics

Step 1: Locate and Read Skill

Parse the skill path argument:

Users invoke with: /validate-skill path/to/skill or /validate-skill skill-name

If no path provided, default to current directory.

Locate the SKILL.md file:

# If path is a directory, look for SKILL.md inside
if [ -d "$skill_path" ]; then
  skill_file="$skill_path/SKILL.md"
else
  skill_file="$skill_path"
fi

# Verify file exists
if [ ! -f "$skill_file" ]; then
  echo "Error: SKILL.md not found at: $skill_file"
  exit 1
fi

Read the entire SKILL.md file to analyze its content.

Step 2: Validate Frontmatter

Check YAML frontmatter between --- markers at the top of the file.

Required Fields

name:

• ✅ Present and non-empty
• ✅ Maximum 64 characters
• ✅ Only lowercase letters, numbers, hyphens
• ✅ No XML tags
• ✅ No reserved words: "anthropic", "claude"
• ⚠️ Recommended: Use gerund form (-ing) like "processing-pdfs", "analyzing-data"

description:

• ✅ Present and non-empty
• ✅ Maximum 1024 characters
• ✅ No XML tags
• ✅ Third person (not "I" or "You")
• ✅ Includes WHAT the skill does
• ✅ Includes WHEN to use it (trigger keywords)
• ✅ Specific enough for discovery
• ⚠️ Should have 5+ trigger keywords/phrases

Optional Fields

• compatibility: Helpful for users
• allowed-tools: List of tools skill can use
• disable-model-invocation: true/false
• user-invocable: true/false
• metadata: Author, version, etc.
• context: "fork" for subagent execution
• agent: Subagent type when context=fork

Step 3: Check File Structure and Organization

Main SKILL.md file:

• ✅ Line count under 500 lines (critical threshold)
• ✅ Clear sections with headers
• ✅ Step-by-step workflow (if applicable)
• ⚠️ Consider splitting if approaching 500 lines

Directory structure:

skill-name/
├── SKILL.md              # Required
├── references/           # Optional but recommended for large skills
│   ├── guide.md         # Additional documentation
│   ├── examples.md      # Usage examples
│   └── api-ref.md       # API reference
└── scripts/             # Optional executable scripts
    └── helper.py

Check for references directory:

if [ -d "$skill_dir/references" ]; then
  # List reference files
  ls -1 "$skill_dir/references"
fi

Check for scripts directory:

if [ -d "$skill_dir/scripts" ]; then
  # List script files
  ls -1 "$skill_dir/scripts"
fi

Step 4: Analyze Content Quality

Line Count Analysis

Count lines in SKILL.md body (excluding frontmatter):

# Count total lines
total_lines=$(wc -l < "$skill_file")

# Count frontmatter lines (between first two ---)
frontmatter_lines=$(awk '/^---$/,/^---$/ {count++} END {print count}' "$skill_file")

# Body lines = total - frontmatter
body_lines=$((total_lines - frontmatter_lines))

Scoring:

• ✅ Excellent: Under 300 lines
• ✅ Good: 300-400 lines
• ⚠️ Acceptable: 400-500 lines
• ❌ Too long: Over 500 lines (should split into references)

Content Clarity

Check for clear workflows:

• ✅ Numbered steps or clear sections
• ✅ Step-by-step instructions
• ✅ Progress checklist for complex workflows
• ✅ Clear conditional logic ("If X, do Y")

Check for examples:

• ✅ Code examples with syntax highlighting
• ✅ Input/output examples
• ✅ Common use case demonstrations

Check for error handling:

• ✅ Error scenarios documented
• ✅ Resolution steps provided
• ✅ Troubleshooting section or table

Terminology Consistency

Scan for inconsistent terms:

• Check if same concept uses different words (e.g., "API endpoint" vs "URL" vs "route")
• Look for consistent naming patterns
• Verify technical terms are used correctly

Anti-Patterns to Flag

Search for these problematic patterns:

Time-sensitive information:

grep -i "before [0-9]\{4\}" "$skill_file"  # "before 2025"
grep -i "after [0-9]\{4\}" "$skill_file"   # "after 2024"
grep -i "currently" "$skill_file"           # "currently available"

Windows-style paths:

grep -E "[a-zA-Z]:\\\\|scripts\\\\|reference\\\\" "$skill_file"

First/second person in description:

# Check description field for "I", "you", "we"
grep "^description:" "$skill_file" | grep -iE "\b(I|you|we|your|my)\b"

Vague descriptions:

# Check for overly generic terms
grep "^description:" "$skill_file" | grep -iE "\b(helps|processes|handles|manages|does)\b"

Step 5: Verify References and Progressive Disclosure

Reference Depth Check

One-level deep references (GOOD):

SKILL.md references:
- [guide.md](references/guide.md)
- [examples.md](references/examples.md)

Nested references (BAD):

SKILL.md → advanced.md → details.md → actual-content.md

Validation steps:

1. Find all markdown links in SKILL.md: [text](path)
2. For each linked file, check if it links to other files
3. Flag any references more than 1 level deep

Progressive Disclosure Patterns

Check if skill uses progressive disclosure properly:

• ✅ SKILL.md provides overview and navigation
• ✅ References linked from SKILL.md for details
• ✅ Clear indication of what each reference contains
• ✅ Reference files have descriptive names

Example of good pattern:

## Advanced features

**Form filling**: See [references/forms.md](references/forms.md) for complete guide
**API reference**: See [references/api.md](references/api.md) for all methods

Table of Contents in Long References

For any reference file over 100 lines, check if it has a table of contents:

for ref_file in "$skill_dir/references"/*.md; do
  lines=$(wc -l < "$ref_file")
  if [ "$lines" -gt 100 ]; then
    # Check for TOC (look for "## Contents" or similar)
    if ! grep -qi "^## \(contents\|table of contents\)" "$ref_file"; then
      echo "⚠️ Warning: $ref_file is $lines lines but has no table of contents"
    fi
  fi
done

Step 6: Check for Anti-Patterns and Issues

Common Anti-Patterns

Offering too many options:

# Look for patterns like "you can use X, or Y, or Z"
grep -i "you can use.*or.*or" "$skill_file"

Explaining obvious things:

# Look for unnecessary explanations
grep -i "PDF.*portable document format" "$skill_file"

Inconsistent formatting:

• Mixed heading styles (# vs ##)
• Inconsistent code block languages
• Mixed bullet point styles (- vs *)

Missing explicit instructions:

• Check for vague language: "handle the file", "process the data"
• Look for clear action verbs: "Run", "Create", "Validate", "Check"

Validation for Scripts

If scripts/ directory exists:

Check for documentation:

• ✅ Each script mentioned in SKILL.md
• ✅ Clear description of what each script does
• ✅ Example usage commands
• ✅ Expected input/output formats

Check for error handling:

• ✅ Scripts handle missing files
• ✅ Scripts provide helpful error messages
• ✅ Scripts validate inputs

Step 7: Generate Comprehensive Report

Generate a comprehensive validation report using the structure defined in references/report-template.md.

Key components:

1. Overall score (0-10) with justification
2. Category scores for Frontmatter, Structure, Content Quality, Progressive Disclosure, Anti-patterns
3. Strengths - what the skill does well
4. Critical issues - must fix immediately
5. Warnings - should fix soon
6. Recommendations - optional improvements
7. Detailed metrics - line counts, character counts, trigger keyword count
8. Best practices checklist - copyable checklist for tracking improvements

Report template: See references/report-template.md for complete report structure, scoring guidelines, and formatting tips

Tips for Great Reports

1. Use latest standards: Validate against the freshly fetched official documentation, not outdated cached information
2. Be specific: Reference exact line numbers, file names, and code snippets
3. Prioritize: List critical issues before minor suggestions
4. Explain why: Don't just say what's wrong, explain why it matters (reference the official docs)
5. Provide examples: Show good vs bad examples for each issue
6. Be constructive: Focus on improvement, not just criticism
7. Reference docs: Link to official best practices for each recommendation
8. Note documentation timestamp: Include when the docs were fetched so users know validation is current

Example Validation Session

User: /validate-skill skills/make-pr

You should:

1. Fetch latest documentation from official Anthropic sources (Step 0)
2. Read skills/make-pr/SKILL.md (Step 1)
3. Validate against fetched documentation criteria (Steps 2-6)
4. Generate comprehensive report (Step 7)
5. Provide actionable recommendations with specific line numbers
6. Give overall score with justification
7. Include timestamp of documentation fetch in report

---

Reference Materials

Primary source: Always fetch latest documentation from:

• https://code.claude.com/docs/en/skills
• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Fallback reference: If WebFetch is unavailable, see references/best-practices-checklist.md for cached best practices (note: may be outdated).