Skill Scaffold

Coverage

• Authoring flow: copy → rename → adapt → strip teaching annotations → verify → commit
• Frontmatter identity: name, description, version, type, category, scope, owner, plus the eval-health triple and drift_check required by every Skill Metadata Protocol skill
• Archetype selection: how to pick between capability, workflow, router, and overlay and which ## H2 body sections each archetype requires
• Semantic-layer discipline: how description: (≤ 3 sentences, pushy, boundary-aware routing contract) differs from ## Coverage (bulleted scope map of distinct topics) and why each must stay in its own layer
• Teaching-layer mechanics: how to use > **TEMPLATE NOTE:** blockquotes and # TEMPLATE NOTE: YAML comments to teach without cargo-culting meta sections into derived skills
• Lint-first authoring gate: passing node scripts/skill-lint.js --strict against your new skill before commit, every time, no exceptions
• Routing-eval honesty: defaulting to routing_eval: absent and only flipping to present after node scripts/skill-graph-routing-eval.js --skill <name> exits 0
• Grounding declarations: when to populate grounding.truth_sources vs leaving the block off, and how the drift sentinel consumes recorded truth_source_hashes

Philosophy

A scaffold teaches by example, not by placeholder. A concrete, internally consistent specimen of a finished skill is a more reliable authoring reference than any amount of abstract instruction. The teaching layer — meta-commentary about how to read and adapt the scaffold — must live in structurally distinct slots that disappear when the author tightens a new skill, never in the ## H2 section slots that AI agents copy verbatim. Authoring is also a lint-first discipline: the lint output is the primary debugging surface for new skills, deliberately verbose, and the canonical answer to "did I do this right?" — not a senior reviewer's pattern-match.

Authoring Flow