Author every primitive's template as a skeleton — named sections with empty slots, never a filled-in example, so instances fill the contract instead of cloning the sample.

Guide

How to Author Templates

The load-bearing distinction

A skeleton names sections. An example fills them. Never ship the example as the template.

Example-as-templatefiller leaks downstream

# Feature: Add OAuth## DescriptionAdd Google OAuth login so users can sign in with Google accounts.## Phase 1- Wire Google client creds - Add /auth/google route - Test with jane@example.com

Every instance starts as a fork of the sample. Authors skim, tweak a line, ship the filler. The sections look right; the content is someone else's problem.

Skeleton templateinstance must fill

# Feature: {name}## Description{one-paragraph problem + intended outcome}## Phase 1{3–6 ordered, verifiable steps — no prose}

The section contract is the only thing inherited. Slots are empty and explicit — you cannot ship the template. The filler cannot leak because there is no filler.

If the template reads like a finished file, the next author ships a copy-paste of your filler. Sections must be named and empty.

The reading path

Seven stops. Two foundations, then one skeleton per primitive.

1

The Plan is the Promptprinciplestart here

Why templates exist at all. Without the template, Plan-is-the-Prompt discipline collapses to prose. Templates are how it becomes mechanical.

2

Template-Declared Contractspattern

The pattern that formalizes skeleton-vs-example. Required sections named, optional marked, hooks enforce presence — the contract is enforced, not advisory.

3

Planprimitive

The canonical 8-section spec skeleton — Metadata, Description, Relevant Files, Phase 1–3, Tasks, Validation, Notes. Extended sections per variant.

4

Commandprimitive

Five-section minimum — Variables, Instructions, Relevant Files, Format, Report. Nine-section extended menu when the minimum runs out.

5

Agentprimitive

YAML frontmatter — description, model, tools, skills, expertise — plus a body shape.

6

Skillprimitive

Markdown with use-when frontmatter and an imperative body. 30–60 lines. One rule, sharp.

7

Hookprimitive

Shell script — event on stdin, validate, exit 0 or 2 with structured error stdout. The simplest template; the sharpest feedback loop.

Read 1 and 2 first. After that, stops 3–7 are independent — read the primitive whose template you are authoring.

What a skeleton looks like on disk

Section headers, required/optional tags, and slots — nothing filled.

templates/command.template.md

skeleton

# {command-name}## Variablesrequired{inputs this command consumes — named, typed, one per line}## Instructionsrequired{imperative steps — the agent executes these verbatim}## Relevant Filesrequired{paths the agent must read, with line ranges where useful}## Formatrequired{exact output shape — schema, headings, or example delimiter}## Reportrequired{what to surface back to the caller — ≤ N words, no prose}## Contextoptional{background the agent needs but shouldn't echo}## Constraintsoptional{hard limits — time, budget, format rules}

REQUIREDHook rejects the instance on absence. Non-negotiable sections.

OPTIONALSkippable when genuinely N/A. Never padded with filler.

{slot}Empty by design. Instance fills it; you never do.

A validation hook greps for each REQUIRED header on save. Missing → exit 2, blocked. The contract is mechanical, not polite.

The five skeletons at a glance

Each instantiable primitive has a shape. Know yours before you start.

MetadataDescriptionRelevant FilesPhase 1Phase 2Phase 3TasksValidationNotes

Extended sections for feature/bug/chore variants. Phases stay — their content differs.

VariablesInstructionsRelevant FilesFormatReport+ 4 extended

Start at five. Reach for the extended menu only when the minimum leaves ambiguity.

descriptionmodeltoolsskillsexpertise

Frontmatter is the contract. Body describes role; skills carry the rules.

use-whenimperative body

One rule, phrased sharply. Line budget is non-negotiable — past 60, it's becoming an agent.

read eventvalidateexit 0 (pass)exit 2 (block + stderr)

The simplest template of all five. Exit 2 blocks the action; stdout tells the agent how to fix it. Feedback loop is the whole spec.

Pick the primitive, open its skeleton, fill the slots. Never invent sections not in the template — that's how forks start.

Where to go next

Two guides branch from here. Each specializes one primitive's template.

→ next

how-to-prompt

A slash command is a Command-primitive template. Follows the same skeleton/example discipline — read this after you've internalized the five-section shape.

→ next

how-to-use-hooks

The Hook skeleton is tiny; the feedback loop is the interesting part. Exit 2 blocks, stdout instructs. Read this once your template has required sections worth enforcing.

Both guides assume you've read Template-Declared Contracts. That's the load-bearing pattern; these guides specialize it.

The discipline

A template is a contract of sections, not a filled-in sample.

Name required sections. Mark optional ones. Leave slots empty. Let the validation hook reject instances that skip the contract. When the skeleton is clean, instances stay consistent — and Plan-is-the-Prompt stops being aspirational.