brain-write-script

A query, probe or API call worth keeping becomes a file: placed by the system it touches, read-only unless its name says otherwise, secrets from the environment, tested, and backed by a dated row in docs/CAPABILITIES.md. Paths are from the brain root: ./scripts/ is the brain's, not this skill's.

Where this sits

Runs after: brain-setup · brain-write-mod · brain-write-skill

Hand to next: brain-sync

Reserved output: writing .mcp.json needs this skill to have run.

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

Reserved output: writing scripts/** needs this skill to have run.

Call it directly when: you are about to write a query or API call you have written before, a system should be reached through an MCP server, or the gate refused a write under ./scripts/, to docs/CAPABILITIES.md or to .mcp.json; nothing has to run first.

1. Does it earn a file?

Make it a file when any one of these holds; otherwise run it inline and carry on:

• you have written it, or something close to it, before;
• it encodes a non-obvious fact about a system (a paging quirk, a field's real units);
• it touches data that matters (a live config, save files, a release, someone else's data);
• it took minutes to work out.

Look first in ./scripts/ and docs/CAPABILITIES.md: changing a script beats writing a second one. When the system has an MCP server that already does the job, connecting it can beat a script: see "An MCP server" below.

2. Probe before writing logic

Read docs/CAPABILITIES.md: the answer may be there, dated. Otherwise find out what the system really does, with reads only (its version, its --help, one request with the script's own access), after reading the rules that bite in CLAUDE.md. Note what failed or is missing as carefully as what worked: a dated negative stops the next session walking into the same wall. If finding out would need a write, do not try it; record it as not tried, and why.

3. Place and name it

• ./scripts/<system>/: one folder per system it touches, named as a Python identifier (hypervisor, mod_loader, files) that no imported module already has, with an __init__.py.
• ./scripts/common/: code that two or more systems share, starting with the .env loader.
• A skill's own scripts/ folder only when that skill is the sole caller (the gate then also wants brain-write-skill).
• Name it for what it does (list_vms.py), and start the name apply_, write_ or delete_ exactly when it changes something, so the name alone says whether running it is safe.

4. Write it

Read references/conventions.md; copy its docstring, root finding, .env loader and read-only guard.

• The docstring opens WHY THIS EXISTS: with the question it answers or the fact it encodes: that line is how the next session decides to reuse the script instead of writing another.
• No absolute or home path. Find the brain root by walking up from __file__ to brain.json: the brain is cloned on more than one machine, and a home path leaks a username into git.
• Read-only unless the name says otherwise: no code path that writes, and every request through one function that refuses anything but a read. A script that does change things shows what it would change and changes nothing without --apply. Never run it, or anything destructive, unless the person asked for that run.
• Secrets come from the environment through the loader in ./scripts/common/env.py, which reads .env itself: you are denied reading .env, deliberately. A value there may be an op:// 1Password reference, which the loader reads with op read. Never take a secret as an argument (argv shows in ps, shell history and this transcript), never print one, and pass any output that could echo one (an error body, a URL, an exception) through env.redact first.
• A private endpoint (hostname, internal address) is configuration: take it from the environment too.
• Anything that is not one of these scripts (a CLI tool, an MCP server, a one-off command) gets its secrets through _meta/brain secret run KEY[,KEY] COMMAND [ARG...]: the loader's rules, and the values go only into that command's environment.
• A new secret name: _meta/brain env-sync --add KEY, then _meta/brain env-sync --open, which opens .env in the person's text editor to paste the value after the =. Never ask for a value in the chat. _meta/brain env-sync --list shows which are set; never read, write or print a value.
• Run another program with an argument list, never a shell string: a path with a space breaks it.
• Follow brain.json scripts.packages: stdlib-only means the standard library and nothing else; allowed means a third-party package that earns its place, named in the docstring.

5. Test it

Tests go in ./scripts/tests/test_<system>_<name>.py. Cover the logic (parsing, paging, the decision the script makes) and the refusal paths (a missing secret, a write refused, a secret kept out of the output), never the network: fake the reply. Every read-only script has a test asserting it only reads. Run them from the brain root under the interpreter brain.json scripts.python names:

<scripts.python> -m unittest discover -s ./scripts/tests -t ./scripts

6. Record and hand on

Add or update the system's row in docs/CAPABILITIES.md, in the format references/conventions.md gives: what it can do, what it cannot, the day the probe ran (today if you probed; never move the date without a check), and how you checked; never a secret or a hostname. Then hand to brain-sync, which runs the checks and commits.

An MCP server

A system with a usable MCP server can be connected instead of scripted. A server only this brain needs goes in the brain's .mcp.json, never in the person's user settings, where every session in every folder would load its tools. Probe it as in step 2: list its tools, call only ones that read, and note which of them write. Declare it with its secrets through secret run, because ${VAR} in .mcp.json reads the environment Claude Code started in, never .env:

{"mcpServers": {"<system>": {"command": "sh", "args": ["-c",
  "exec \"$CLAUDE_PROJECT_DIR/_meta/brain\" secret run SYSTEM_TOKEN <server command> <arg>"]}}}

sh -c because Claude Code sets CLAUDE_PROJECT_DIR in the server's environment but does not expand it in .mcp.json, and does not promise the server's working directory. A remote server that needs a token runs the same way through a local bridge command. Then record its docs/CAPABILITIES.md row as in step 6, its tools that write under Can, and hand to brain-sync. The person approves a project server the first time Claude Code starts it.

In the template

When brain.json role is template, a harness change in _meta/ that template-intake accepted is written here, following the template's CLAUDE.md. Steps 3 and 6 and their Done-when lines do not apply; the template's tests pass.

Done when

• The script is in ./scripts/<system>/, ./scripts/common/ or its sole caller's scripts/, and its name starts apply_, write_ or delete_ if and only if it changes something.
• Its docstring opens WHY THIS EXISTS:, and it names no absolute or home path.
• Tests for its logic and refusal paths, including one asserting it only reads when it is read-only, pass under scripts.python.
• docs/CAPABILITIES.md has the system's row, dated the day the probe ran, with what it cannot do.
• No secret is in the script, its arguments or any output; new names went in through env-sync --add.
• An MCP server is in .mcp.json with its secrets through secret run, and its CAPABILITIES row names the tools that write.
• Handed to brain-sync.