skill-smith

skill-smith — lint a SKILL.md

A skill lives or dies on its routing and its shape. The script judges the deterministic half — frontmatter, line budget, reference depth — and hands you a checklist for the half it cannot.

When to use

• Authoring a new skill — run it before calling the skill done.
• Reviewing or editing an existing SKILL.md.
• After any edit under a skills/*/SKILL.md path.

Run the lint

python3 "${CLAUDE_PLUGIN_ROOT}"/skills/skill-smith/scripts/lint_skill.py <path-to-SKILL.md>

Pass a single SKILL.md, or a skills/ directory to lint every skill under it. Exit 1 when any FAIL is present; WARN alone exits 0.

What it checks, deterministically:

• name — present, matches the parent directory, and uses the kebab charset (lowercase / digits / single hyphens, no leading, trailing, or doubled hyphen).
• description — present, ≤ 1024 chars, carries a Use when / Invoke when trigger clause, and reads third-person (a first-person I … is flagged).
• body — under the 500-line budget (a warning fires past 400).
• reference depth — every bundled file (reference/…, scripts/…) stays one level deep; a file nested deeper is a WARN, so the run still exits 0 and the rule is yours to hold.

The loop

Fix the reported FAILs, re-run, repeat — cap at 3 rounds. Findings still standing after the third round go to the operator as a residual list. The exit criterion is lint_skill.py exiting 0, judged by the script.

WARNs exit 0 and are still worth reading — a first-person description or a body creeping toward the budget is cheapest to fix while you are here.

Manual pass (what the script cannot judge)

Two things stay judgement calls. After the lint is clean, read the change against them:

• reference/anatomy.md — the canonical section order and the frontmatter contract. Diff a new skill's shape against it.
• reference/failure-modes.md — the six ways a skill rots (premature completion, duplication, sediment, sprawl, no-op, negation). Use it as a read-through checklist.