validate-skills · diff
git:20260528.8ea6e5a to git:20260710.dc3c074
21 added, 12 removed. Audit A to A.
---
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 |
- | Legacy output paths (`./codereview.md` etc.) | Warning |
- | Body exceeds 500 lines | Warning |
+ | 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 |