Skip to main content
This tutorial customizes the Scout agent from your first agent — any agent group works, just swap the folder and --id. An agent has three customization surfaces:
  1. Personality and rules — groups/<folder>/instructions.prepend.md, the agent’s editable standing instructions
  2. Brain — model, reasoning effort, and other container config fields, edited with ncl
  3. Capabilities — packages and MCP servers, which go through the approval flow covered in self-modification
One file you will not edit: groups/<folder>/CLAUDE.md. The host regenerates it on every container spawn from a shared base plus skill and MCP fragments, and mounts it read-only into the container. Anything you write there gets clobbered. instructions.prepend.md is the file that’s yours (and the agent’s); durable facts the agent accumulates over time live alongside it in the memory/ tree.
1

Personality, the conversational way

The simplest path is to just tell the agent:
The self-customize skill (on every agent by default) teaches the agent that edits to instructions.prepend.md and memory/ are free — no approval needed — so it writes the rule into its own groups/scout/instructions.prepend.md through the read-write workspace mount. The current conversation follows the rule immediately because you just said it; the file is what makes it stick for every future session.Check what it wrote:
2

Personality, the direct way

You can edit the same file yourself — useful for longer instructions you’d rather paste than dictate:
groups/scout/instructions.prepend.md
When does this take effect? Instructions load when a container spawns, so a warm container mid-conversation won’t pick up your edit. Either wait — containers exit after idling, and the next message spawns a fresh one — or force it now:
If you’d rather be guided than edit files, run /customize in Claude Code from your NanoClaw checkout. It’s an interactive skill: it asks what you want to change, hands off to a dedicated skill when one exists (/add-telegram, /manage-channels, /manage-mounts, …), and otherwise routes the change to the right surface — the agent group’s instructions.prepend.md for persona, container config for runtime behavior, wirings for triggers.
The /customize skill’s own text still points persona edits at the composed groups/<folder>/CLAUDE.md. Follow this tutorial instead: edit instructions.prepend.md — anything written to the composed file is clobbered at the next spawn.
3

Swap the brain

Model and reasoning effort live in the agent group’s container config, not in any file. Update them with ncl:
  • --model takes an alias (sonnet, opus, haiku) or a full model ID. Unset means the SDK default.
  • --effort is one of low, medium, high, xhigh, max.
Config values are read at every spawn, so a running container keeps its old config — the change applies to the next container automatically. To force it now:
A cheap-and-fast Scout (--model haiku --effort low) is great for routing or lookup duty in a multi-agent swarm; keep opus with higher effort for agents that do real work. The same command also takes --assistant-name, --provider, and more — see the container config reference.
4

Verify

Ask Scout something and confirm the haiku rule and the model change both took:
You can also peek at the composed file to see why it’s off-limits:
It’s a header and imports. Your instructions.prepend.md is inlined as the persona.md fragment and imported first, so it sits at the top of the system prompt, ahead of the shared base and the per-skill fragments. Editing the composed CLAUDE.md is pointless because the host rebuilds it from those sources on every spawn.

​
What you changed

Two surfaces, two mechanisms: personality went into a file the agent and you co-own (instructions.prepend.md), the brain went into a DB row (container_configs). Both are read at container spawn — edits apply to the next container, and ncl groups restart forces one now. The third surface — capabilities — works differently because it can change what the agent is able to do, so it goes through admin approval.

​
Next steps

Last modified on July 16, 2026