Skills¶
A skill is one directory holding one SKILL.md. That is the shape Claude Code, Codex and
Cursor all discover a skill in, so the procedure is the file the host loads — no wrapper, no
second copy.
Three kinds¶
Every skill declares its **Kind**, and the kind fixes the body shape.
| Kind | Body | Read it as |
|---|---|---|
| procedure | numbered ## 1. … steps, then ## Output, ## Stop conditions |
every step is a gate — do not advance until it holds |
| reference | topic sections, then ## Gotchas |
look up what you need |
| template | ## Fill rules, then ## Template |
copy the block, fill it, delete what does not apply |
Procedures (15): develop-flow · spike · plan-review · implement-change ·
internal-review · run-unit-tests · qa-verify · release-pr · pr-review · fix-pr ·
ticket-intake · incident-triage · demo-prep · release-cut · release-notes
References (5): worktree · scratchpad · memory · cross-repo · tracker
Templates (2): plan-template · pr-template
Only some procedures become commands¶
A command exists for the eight procedures you start a session with — dev, spike,
review, fix, qa, triage, release, demo — under a short name, listed in COMMANDS
in plugin/generate.py.
Everything else stays a skill. A reference is read by a procedure and a template is filled
by one, so neither can be "finished"; and the procedures the flow runs for you (plan-review,
implement-change, internal-review, run-unit-tests, release-pr, release-notes,
ticket-intake) are read as SKILL.md by the role running them, so a menu entry would only
offer a starting point that is wrong on its own. All three hosts still discover them, and a
model pulls one in when you name it.
The commands are generated from the procedure's own frontmatter:
check.py fails if a command is stale, missing, or orphaned by a deleted procedure — an
orphan still shows in the / menu and sends the model to read a file that is gone.
Adding a skill
Every step is a gate¶
A procedure is not a checklist to skim. Its steps are ordered because each one's output is the
next one's input, and its ## Stop conditions say when to stop rather than improvise. When a
step cannot be completed — a command the profile does not define, a stack that will not boot,
a proof that cannot be captured — the procedure stops and says so. It never substitutes a
weaker step and reports success.
Skills contain no organisation facts¶
A skill says "run the profile's verification commands", never pytest -q. It says "the
base ref from the profile", never origin/main. That is what lets the same procedure run in
a workspace with one repo and no tracker, and in a workspace with six repos and a strict
transition policy. Facts come from the profile, cited by anchor.