# Skill Validator

> Validate Claude Code SKILL.md files for correct YAML frontmatter, structure, and markdown syntax

- Skill: `lodetomasi/skill-validator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lodetomasi/skill-validator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lodetomasi/skill-validator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: lodetomasi (https://skillmd.com/u/lodetomasi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lodetomasi/skill-validator

---


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

```bash
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
```yaml
# ❌ BAD
name: PythonProfiler  # Uppercase
name: python_profiler # Underscores

# ✅ GOOD
name: python-profiler
```

### Description Too Long
```yaml
# ❌ 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
```markdown
# 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
```yaml
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:
```bash
# Validate all skills
python .claude/skills/skill-validator/skill-validator.py .claude/skills

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