validate-skills

Check that a skill is actually a valid skill — its SKILL.md frontmatter and layout conform to the Agent Skills specification — for one named skill or every skill in a repo, and report what fails and where. This is the gap nothing else closes: a repo's own sync-checks verify its generated artifacts, its tests verify its runtime code, but the frontmatter — the part that decides whether an agent finds a skill at all — goes unchecked, and a description over the spec's 1024-character limit still "works" in a lenient client while a conformant one rejects it.

Its three principles, from which everything else follows:

1. Drive the standard's own validator; never reimplement it. skills-ref is the specification's reference validator and tracks the spec as it moves — the same reason update-deps drives the repo's own updater instead of re-deriving what "allowed" means. So the spec verdict comes from skills-ref, not from a hand-rolled regex. Where skills-ref cannot be obtained, the skill says the spec tier is unverified — it never presents a weaker hand-check as a pass.

2. Separate the standard, client extensions, and local convention. A spec violation breaks portability — a conformant client will reject the skill. A client extension is a field the open standard does not define but a named client accepts — valid there, but non-portable: "this skill will not load in a strict client" is a wholly different finding from "this skill is malformed." A house-style deviation is a repo's own choice — its naming, its metadata.summary, its description phrasing. All three are different findings and are reported as such; collapsing them into one list is the mistake this skill exists to avoid.

3. Know every client's extension convention, not one client's. Which clients define a field is part of the finding: paths and disable-model-invocation are Cursor's as well as Claude Code's, so filing them as Claude-only is factually wrong and costs the author portability they never lost. And extending is not one design — Claude Code puts extensions in the frontmatter and spends conformance; Codex puts them beside it, in agents/openai.yaml, and spends nothing. A validator that knows only the first cannot tell an author the second exists. The four clients this covers, and why two more are deliberately left out: REFERENCE.md.

Reports, never repairs. This skill produces findings; it does not edit a SKILL.md to fix them. Fixing is the author's call (or a follow-up run of an editing skill).

Three tiers of finding

Every finding lands in exactly one tier, and the report keeps them apart. The client-extension tier sits between the other two — valid-but-non-portable, neither a spec breach nor a local convention: