brain-write-skill
/brain-write-skill
Create, change, split or rename one of this brain's own skills, or an agent a skill dispatches, so it fits the brain's conventions: placed in the routing map first, named <prefix>-<verb>-<object>, a description that says what it does NOT do, must-obey rules inline, a router when an entry point fans out, and a gate on output that must not be improvised. Use when work keeps being reinvented or judged wrong, when a skill grew too big, when renaming one, or when the skill gate refuses a write to a skill or agent file. Does NOT write scripts, which is brain-write-script; does NOT record a fact, whi
- Author
- derrickmehaffy ↗
- Repository
- brain-template ↗
- Licence
- MIT
- Last repository change
- 03.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 2
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Create, change, split or rename one of this brain's own skills, or an agent a skill dispatches, so it fits the brain's conventions: placed in the routing map first, named <prefix>-<verb>-<object>, a description that says what it does NOT do, must-obey rules inline, a router when an entry point fans out, and a gate on output that must not be improvised. Use when work keeps being reinvented or judged wrong, when a skill grew too big, when renaming one, or when the skill gate refuses a write to a skill or agent file. Does NOT write scripts, which is brain-write-script; does NOT record a fact, whi
Original author description
Create, change, split or rename one of this brain's own skills, or an agent a skill dispatches, so it fits the brain's conventions: placed in the routing map first, named <prefix>-<verb>-<object>, a description that says what it does NOT do, must-obey rules inline, a router when an entry point fans out, and a gate on output that must not be improvised. Use when work keeps being reinvented or judged wrong, when a skill grew too big, when renaming one, or when the skill gate refuses a write to a skill or agent file. Does NOT write scripts, which is brain-write-script; does NOT record a fact, whi
How it works
- Where this sits
- In the template
- Sequence
- Agents
- Splitting and renaming
- Do not
- Done when
SKILL.md preview
---
name: brain-write-skill
description: "Create, change, split or rename one of this brain's own skills, or an agent a skill dispatches, so it fits the brain's conventions: placed in the routing map first, named <prefix>-<verb>-<object>, a description that says what it does NOT do, must-obey rules inline, a router when an entry point fans out, and a gate on output that must not be improvised. Use when work keeps being reinvented or judged wrong, when a skill grew too big, when renaming one, or when the skill gate refuses a write to a skill or agent file. Does NOT write scripts, which is brain-write-script; does NOT record a fact, which is brain-write-practice; and does NOT change a brain-* skill, which is brain-upstream."
---
# 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
<!-- where:begin — generated by _meta/brain routing sync; do not edit -->
**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.
<!-- where:end -->
**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.
```markdown
---
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.
Files in this package (4)
- SKILL.md 9 KB
- references/conventions.md 10 KB
- references/gates.md 9 KB
- references/routing.md 12 KB
Versions
The database has no other skills named brain-write-skill.
Database snapshot: 13.11.2026 · package version d81077b580d0 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100brain-write-practice
Create or update one entry in docs/practices/, the store of facts this brain has already worked out, with its evidence level, when it was verified and how to re-check it. Use when work produced a fact a second occurrence would need, when a stored fact turned out wrong or stale,… - 90brain-retro
Record what went wrong when a skill failed on real work, or when work fit no skill, or which skills go unused, and propose the one change that fixes it: an edit to the brain's own skill, a missing gate rule, a missing router rule, or an upstream suggestion. Use when a skill just… - 100write-skill
Author or update compact agent skills under skills/<name>/SKILL.md. Use when asked to write, add, or change a skill; not to audit a skill library. - 95configuring-agent-brain
Installation and configuration skill for Agent Brain document search system. Use when asked to "install agent brain", "setup agent brain", "configure agent brain", "setting up document search", "installing agent-brain packages", "configuring API keys", "initializing project for… - 94captn-brain
Use for CaptN-BRAIN CLI token/context optimisation. Deterministic first. - 100flux-brain
Read/write brain files in .flux/brain/. Use for any task that persists knowledge — reflection, planning, or direct edits. Handles the "Remember" flow: classifies content as CLAUDE.md (short rules for every session) or .flux/brain/ (deeper context), asks user to confirm, then…