Skip to content
Skills Library
AI & agents · Building & coding

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

Licence
MIT
Last repository change
03.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Where this sits
  2. In the template
  3. Sequence
  4. Agents
  5. Splitting and renaming
  6. Do not
  7. Done when
Original SKILL.md headings · 133 lines, 1,391 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.