Skill Validator

Overview

Validates SKILL.md files in Claude Code skill directories to ensure proper YAML frontmatter format, required fields, document structure, and markdown syntax compliance.

When to Use

• After creating new skills
• Before committing skill changes
• When troubleshooting skill loading issues
• During skill repository maintenance

Validation Checks

1. YAML Frontmatter

• Presence of opening/closing ---
• Required field: name (lowercase, hyphens only, max 64 chars)
• Required field: description (max 1024 chars)
• Optional field: allowed-tools

2. Document Structure

• Main heading (# Title)
• Overview section
• Capabilities section
• Code examples present
• Reasonable content length

3. Markdown Syntax

• Valid code block languages
• Broken links detection
• Proper heading hierarchy

Usage

Run the validator on your skills directory:

python .claude/skills/skill-validator/skill-validator.py .claude/skills

Expected Output

Success:

🔍 Validating skills...
Found 17 skill files

==========================================================
SKILL VALIDATION REPORT
==========================================================

Validated 17 skills

✅ All skills are valid!

With Issues:

==========================================================
SKILL VALIDATION REPORT
==========================================================

❌ ERRORS (2):
  • aws-cost-analyzer/SKILL.md: Missing required field: description
  • python-profiler/SKILL.md: Name should be lowercase with hyphens

⚠️  WARNINGS (3):
  • java-profiler/SKILL.md: Missing ## Overview section
  • memory-analyzer/SKILL.md: Document seems short (45 lines)
  • tdd-workflow/SKILL.md: No code examples found

❌ Validation failed - please fix errors

Fixing Common Issues

Invalid Name Format

# ❌ BAD
name: PythonProfiler  # Uppercase
name: python_profiler # Underscores

# ✅ GOOD
name: python-profiler

Description Too Long

# ❌ BAD (>1024 chars)
description: This is a very long description that goes on and on...

# ✅ GOOD (<1024 chars)
description: Python profiling for CPU, memory, and performance analysis

Missing Required Sections

# Skill Name

## Overview
Brief description of what this skill does...

## Capabilities
What the skill can do:
- Feature 1
- Feature 2

Integration with CI/CD

GitHub Actions

name: Validate Skills

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Validate Skills
        run: python .claude/skills/skill-validator/skill-validator.py .claude/skills

Exit Codes

• 0: All skills valid
• 1: Validation errors or warnings found

Implementation

The validator is implemented in Python and uses:

• YAML parsing for frontmatter validation
• Regex matching for name/description format validation
• Markdown analysis for structure checking
• Path traversal to find all SKILL.md files recursively

Run with:

# Validate all skills
python .claude/skills/skill-validator/skill-validator.py .claude/skills

# Show help
python .claude/skills/skill-validator/skill-validator.py