Write a skill for this brain

A skill here is placed in a routing map, gated by a hook and checked by lint; generic skill-writing advice covers none of that, so follow this sequence even when another skill-writing skill is installed.

Where this sits

Runs after: brain-retro · brain-setup

Hand to next: brain-sync · brain-write-script

Reserved output: writing .claude/agents/<prefix>-*.md needs this skill to have run.

Reserved output: writing .claude/skills/<prefix>-*/** needs this skill to have run.

Reserved output: writing docs/ROUTING.md needs this skill to have run.

Call it directly when: the skill gate refused a write to a skill or docs/ROUTING.md, or brain-retro proposed a skill edit the person accepted; steps 7 to 9 apply to every change.

In the template

When brain.json role is template, ask the person whether the skill ships to every brain (brain-*) or stays in the template (template-*). Editing a brain-* skill is allowed here. A brain-* skill is drawn in _meta/ROUTING-META.md, its gate rules go in _meta/gates.json, and it is written for any brain: conventions read from brain.json and CLAUDE.md, no prefix, path or person hard-coded. Run the template's tests after a change.

Sequence

For a new skill, run every step. For a change to an existing one, start with _meta/brain routing show <skill>, skip only the steps the change cannot touch, and always run 7 to 9. If the gate refused a write to a skill file, this sequence is the answer, not a waiver.

1. Does it earn a skill? Only work that will happen again and is not obvious to do well: a sequence someone would reinvent, or judgement someone would get wrong. A fact is a practice (brain-write-practice), a query or helper is a script (brain-write-script), and something done once is neither. Work already under way counts as covered: a skill on an unmerged branch, or an open suggestion in docs/UPSTREAM.md. Say so and stop: every skill costs every session its description.
2. Place it in the tree before writing it. Read references/routing.md. Run _meta/brain routing show and settle, with the person where it is not obvious: where the work enters (an existing entry node, or a new one in the words a person would say), what runs before it, what it hands to, whether it is a gate on someone's path, and whether it ends where a person acts. If an entry point now fans out to three or more skills by kind of input, write or extend a router, with a rule and a test case for the new skill. Draw it in docs/ROUTING.md, or list it under ## Not drawn with the reason. Placement sets the boundaries: a skill placed after it is written overlaps its neighbours, and nothing hands to it.
3. Name it <prefix>-<verb>-<object>: the prefix from brain.json, a verb from the families the brain already has (ls .claude/skills). Read references/conventions.md for steps 3 to 5.
4. Description, on one line in double quotes (unquoted, YAML refuses : and cuts at #): what it does; when to use it, in a person's words; what it does NOT do, naming the sibling ("which is <name>"). Routers and other skills read descriptions to decide; lint checks the names resolve.
5. Body, about 100 lines:
   • the sequence and the judgement inline, with the reason for any step that is not obvious: the reason is what survives a case the author never saw;
   • every must-obey rule inline: references/ do not load by themselves, so a rule left there is a rule skipped; lookup material goes there, behind "Read references/<file>" at its step;
   • where its output goes (a project folder, docs/, outside the brain; CLAUDE.md maps the folders), or the next agent writes it wherever it is standing;
   • an empty ## Where this sits for routing sync, and a hand-written **Call it directly when:** line under it; then ## Done when, as checkable conditions.
6. Gate its output when it must not be improvised. Read references/gates.md. Gate anything that leaves the brain (a post, PR or release text, config applied to a live system, a reply to someone) and anything a later step trusts without checking again. Add the rule to brain.json gates, with a why, and spend_on_revision when every revision needs the skill's review again. A path no rule covers is unguarded, so the body must say exactly where that output is written.
7. Check. Read references/conventions.md for what each finding means. Run _meta/brain routing sync, then _meta/brain lint (no BROKEN; tell the person why each GAP left stays), _meta/brain routing sync --check, and _meta/brain route <router> --check per changed router.
8. Run it on a real case before trusting it, through the Skill tool, or ask the person for one (and record why not, if there is none). Two runs that read a step differently mean that step is not doing its job: explain why it matters, rather than adding capitals or "NEVER", which get talked past.
9. Hand on. A script it needs goes to brain-write-script; never write one inline here. Then commit through brain-sync.

Agents

An agent (.claude/agents/<prefix>-<role>.md) is a helper a skill dispatches with the Agent tool: its own context for a large read, a cheaper model, or a narrower set of tools. Write one only when a skill's step needs that; otherwise the step stays in the skill. It is never an entry point, so it is not drawn in the map: the skill that dispatches it names it, and lint reports one no skill names.

---
name: <prefix>-<role>
description: "What it does and when a skill hands it work; what it does NOT do."
tools: Read, Grep, Glob
model: sonnet
---

List its tools, read-only unless its job is to write (without tools it gets every tool, MCP ones included), and give the reason in its body for any write tool or Bash. Name the cheapest model that does the job. The body says what it is given and what it returns: a report, never the files it read, so the dispatching skill makes any fix. A checker gives each claim a verdict: verified (with its source), unverified (with the risk of trusting it) or falsified; with no source to reach, a claim is unverified, never verified. Then run step 7.

Splitting and renaming

Split a skill that passed about 150 lines, or that has two entry points, by where its parts sit in the tree, not by topic: each part gets its own node, edges, description and ## Done when. Run the sequence from step 2 for each part, and move every edge, router rule and gate rule that named the old skill. Rename only with _meta/brain rename-skill OLD NEW: a dry run that lists every file it would change. Read the list, then add --apply; it rewrites the name in places no hand rename gets all of (router rules, map ids, brain.json gates). Then run step 7.

Do not

• Rename a skill by hand: references left behind break routing silently.
• Leave a skill out of the map without a ## Not drawn row saying why.
• Leave a must-obey rule only in references/.
• Arm a gate waiver, or add a gates_off or gate_exempt entry, yourself: each needs the person's express say-so, this time, with their reason. A refusal means invoke the skill it names.
• Edit between the where: markers (routing sync writes that block), or change a brain-* skill or _meta/ in a brain (record it through brain-upstream).

Done when

• The skill is drawn in the routing map, or listed under ## Not drawn with a reason.
• _meta/brain lint shows no BROKEN, and every GAP left was explained to the person.
• _meta/brain routing sync --check passes.
• If it joins a fan-out: the router's rules.json has a rule and a case for it, and _meta/brain route <router> --check passes.
• If its output must not be improvised: a brain.json gates rule covers the path it writes.
• It was tried on a real case, or the person said why not.
• An agent lists its tools and a model, and the skill that dispatches it names it.
• It is handed to brain-sync to commit.