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

"${CLAUDE_PLUGIN_ROOT}"/bin/lint-skill <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 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)

Three things stay judgement calls. Before you write, read reference/writing-for-agents.md; after the lint is clean, read the change against the other two:

• reference/writing-for-agents.md — the rubric for any document an agent reads: context pointers, the information hierarchy, completion criteria, leading words and pruning. A skill also reads reference/skill-mechanics.md.
• 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.