> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize an agent

> Hands-on tutorial: change an agent's personality through instructions.prepend.md, swap its model and effort with ncl, and verify the changes landed.

This tutorial customizes the Scout agent from [your first agent](/guides/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](/reference/container-config) fields, edited with `ncl`
3. **Capabilities** — packages and MCP servers, which go through the approval flow covered in [self-modification](/extend/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](/concepts/agent-memory).

<Steps>
  <Step title="Personality, the conversational way">
    The simplest path is to just tell the agent:

    ```bash theme={null}
    pnpm run chat scout "scout, from now on answer in haiku and sign off as 'Scout'"
    ```

    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:

    ```bash theme={null}
    cat groups/scout/instructions.prepend.md
    ```
  </Step>

  <Step title="Personality, the direct way">
    You can edit the same file yourself — useful for longer instructions you'd rather paste than dictate:

    ```markdown groups/scout/instructions.prepend.md theme={null}
    ## Style

    - Answer in haiku
    - Sign off as "Scout"

    ## Standing rules

    - Always confirm before deleting anything
    ```

    **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:

    ```bash theme={null}
    ncl groups restart --id <agent-id>
    ```

    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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Swap the brain">
    Model and reasoning effort live in the agent group's container config, not in any file. Update them with `ncl`:

    ```bash theme={null}
    ncl groups config update --id <agent-id> --model sonnet --effort low
    ```

    * `--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:

    ```bash theme={null}
    ncl groups restart --id <agent-id>
    ```

    A cheap-and-fast Scout (`--model haiku --effort low`) is great for routing or lookup duty in a [multi-agent swarm](/guides/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](/reference/container-config#fields).
  </Step>

  <Step title="Verify">
    Ask Scout something and confirm the haiku rule and the model change both took:

    ```bash theme={null}
    pnpm run chat scout "which model are you running on?"
    ```

    You can also peek at the composed file to see why it's off-limits:

    ```bash theme={null}
    cat groups/scout/CLAUDE.md
    ```

    ```text theme={null}
    <!-- Composed at spawn - do not edit. Standing instructions: instructions.prepend.md. Memory: memory/. -->
    @./.claude-fragments/persona.md
    @./.claude-shared.md
    @./.claude-fragments/module-self-mod.md
    ...
    ```

    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.
  </Step>
</Steps>

## 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

* [Self-modification](/extend/self-modification) — let the agent install packages and MCP servers, with you as the approval gate
* [Container config reference](/reference/container-config) — every field, including skills selection and extra mounts
* [Multi-agent swarm](/guides/multi-agent-swarm) — put your customized agents to work together