validate-skills

name	validate-skills
description	Use when verifying all skills in the repository are well-formed before a release or after adding/editing a skill.

Validate Skills

Steps

1. Run the validator across all skills — public and internal:

   uv run scripts/validate-skill.py
   uv run scripts/validate-skill.py .claude/skills/*/SKILL.md
   

   To validate only public skills:

   uv run scripts/validate-skill.py
   

   To validate only internal skills:

   uv run scripts/validate-skill.py .claude/skills/*/SKILL.md
   

2. If any errors are reported, fix them before proceeding. Errors are blocking.

3. Warnings should be reviewed; fix if the skill is being released.

4. Run the version sync check:

   uv run scripts/check-version-sync.py
   

5. If all checks pass, skills are release-ready.

What is checked

Check	Level
Frontmatter present	Error
name field present	Error
description field present	Error
Description contains "Use when" trigger clause	Error
Description ≤ 1024 chars	Error
Skill name matches directory name	Error
Header level progression (no skipping levels)	Error
Description with ': ' must be single-quoted	Error
Command tables (## Commands, ## Internal commands) ↔ commands/*.md files 1:1 (skills with a commands/ dir)	Error
Duplicate headers within a SKILL.md body	Error
Command file h1 is # /<skill> <command> — …	Error
Command file has ## When to use	Error
Command file header level progression	Error
Legacy output paths (./codereview.md etc.)	Warning
Body exceeds 500 lines	Warning