Skill validation

Check skills against the Agent Skills specification and report what to fix.

Run the validator first, then interpret its findings. Do not review a SKILL.md by eye when the script can answer the mechanical questions — reading by eye misses character limits, silent YAML coercions, and broken bundled paths, which are the failures that actually break skills at load time.

1. Locate the skills

A skill is any directory containing a SKILL.md. Common locations:

Location	What lives there
.claude/skills/<name>/	Project-local skills
~/.claude/skills/<name>/	Personal skills
skills/<name>/	Skills shipped inside a plugin or repo
<anywhere>/<name>/SKILL.md	A single skill under development

If the user named a path, use it. Otherwise check the project's skills/ and .claude/skills/ directories. Ask which to check only when several exist and the request is ambiguous.

2. Run the validator

python3 scripts/validate_skill.py <path>

It accepts one skill directory or a tree containing many, and discovers every skill beneath the path.

Flag	Use it when
--format json	You need to filter or count findings, or feed them into a fix loop
--strict	The user wants warnings to fail too (CI, pre-publish gates)
--errors-only	The user only wants hard specification violations
--list-rules	The user asks what is checked

Exit codes: 0 clean, 1 violations found, 2 bad path or no skill there. Exit 1 is the normal result for a skill with problems — report the findings, do not treat it as a tool failure.

3. Interpret the findings

Every finding carries a rule ID, a level, a location and a fix hint. The three levels mean different things and must be reported differently:

• ERROR — a specification violation. The skill is non-conformant and may fail to load. Always report these and offer to fix them.
• WARN — a specification recommendation or an authoring guideline from agentskills.io. Real, but a judgment call. Report with the reasoning, and say when ignoring one is defensible.
• NOTE — portability information, not a defect. Mention only if relevant to where the skill will run.

The full rule catalog, with the specification clause behind each rule and what a good fix looks like, is in references/rule-catalog.md. Read it when a finding needs explaining, when the user asks why a rule exists, or when you are deciding whether a warning is worth acting on.

The specification's own limits and field definitions are summarized in references/spec-rules.md. Read it when you need the authoritative constraint rather than the validator's phrasing — for example when a user disputes a finding.

4. Report

Lead with the verdict, then the findings grouped by skill, errors first. Use the format in references/report-format.md when the user asks for a written report, a review of many skills at once, or output to paste elsewhere. For a quick single-skill check, a short summary plus the findings is enough.

State counts honestly. "3 errors, 5 warnings across 4 skills" is the report; "mostly fine" is not.

5. Fix

Only after reporting. Fix errors first, then warnings the user accepts.

• Never rename a skill directory or name field without asking. Callers, documentation, and /skill-name invocations depend on it. AS106 has two valid fixes — rename the directory or the field — and only the user knows which is correct.
• Never invent content to satisfy a warning. A thin description (AS203) is fixed by learning what the skill actually does, not by padding it. If you cannot tell, ask.
• Re-run the validator after fixing and report the new counts. A fix that introduces a different violation is not a fix.

For description findings (AS203, AS204, AS205, AS206), rewriting well enough to change triggering behavior is its own task — hand off to the skill-description-tuning skill rather than guessing at wording.

Gotchas

These are the failures that recur, and the reasons the validator exists:

• metadata: version: 1.0 is a number, not a string. YAML parses unquoted 1.0 as a float, and the specification requires metadata values to be strings. Quote it: version: "1.0".
• allowed-tools is space-separated, not a YAML list and not comma-separated. allowed-tools: Read Bash(git:*) is correct. A list silently changes the value's type.
• name must match the parent directory exactly. This is the single most common hard violation, and it usually appears after a directory rename.
• Character limits are on the field, not the line. A folded > description is measured after folding — 1024 characters of prose, not 1024 per line.
• Frontmatter must be the very first thing in the file. A leading blank line, a BOM, or a comment above --- means no frontmatter is found at all, and the skill will not load.
• A missing bundled file is an error, not a warning. A references/<file>.md that does not exist fails at runtime, in the middle of a task, after the agent has already committed to the approach.
• Write illustrative paths as placeholders. A literal-looking bundled path in prose reads as a real reference to the validator — and to an agent. Use angle brackets (references/<name>.md) for examples; the validator skips them.
• Paths into the user's project are not bundled files. The validator deliberately does not check .workspace/INDEX.md or ~/Downloads/data.csv for existence. Do not "fix" those by creating files.

Validating this plugin's own skills

python3 scripts/validate_skill.py --strict ../

The validator is covered by fixtures with known defects. If you change it, run python3 tests/run_tests.py from the repository root before reporting success.