validate-skills git:20260710.dc3c074A

Immutable. This exact content is served forever at /api/v1/blob/de13b12f575e7c69.

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

# Validate Skills

## Steps

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

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

   To validate only public skills:

   ```bash
   uv run scripts/validate-skill.py
   ```

   To validate only internal skills:

   ```bash
   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:

   ```bash
   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 |