Edit an agent's identity and instructions

Every agent has two short text files that decide how it behaves: one says who it is, the other says how it does its job. The agent reads both whenever it starts work, so editing them is the most direct way to change what it does. You find them under Settings, Brain.

The two files#

When you create an agent from a template, both files come from that template. You edit both the same way whatever the runtime, and the console always opens and saves the copy your agent's runtime really reads:

Some runtimes also keep a second copy of a file, for example AGENTS.md in the home folder next to workspace/AGENTS.md on OpenClaw and Codex. Saving from Brain updates every copy at once, so they never disagree.

Edit and save a file#

1. In the sidebar, click Agents and open the agent.
2. Click the Settings tab, then Brain.
3. Pick Identity (1) to edit who the agent is, or Work (2) to edit how it works.

123

4. Type in the Edit box. The Preview beside it shows how the Markdown formatting reads.
5. Click Save (3). The footer confirms the save and says when the agent starts using it, which depends on its runtime (see when an edit takes effect).

A few things to know while you edit:

• Save stays greyed out until you change something. An Unsaved badge appears next to the title as soon as you do.
• Switching between Identity and Work keeps your unsaved changes in both, so you can edit them side by side and save each one.
• A Not set yet badge means the agent has no such file yet. Whatever you save becomes it.
• A file larger than 256 KB is shown from the beginning only and cannot be saved from here, so nothing past that point is lost.
• Brain is locked (it shows a padlock) until the agent finishes setting up.
• If you or the agent changed one copy of a file outside Brain (in the Workspace tab, the Shell, or the agent editing its own instructions), the copies can end up different. When Brain opens the file it keeps the most recently changed version, updates the other copies to match, and saves the version it replaced in workspace/brain-backups/ on the Workspace tab. A note under the editor names the backup, so nothing you wrote is lost.

When an edit takes effect#

To try a change right away on Hermes or Codex, click New chat on the agent's Chat tab. Nothing needs restarting.

Write a good identity#

Keep the identity short and about character, not procedure. Say who the agent works for, what it is for, and how it should sound. For example:

# Atlas

You are Atlas, the morning briefing assistant for Northwind Trading.

- Calm, direct and brief. Lead with what needs a decision today.
- Write in plain English. No jargon, no filler.
- When you are not sure, say so and name what you would check.

Write good instructions#

The Work file is where the real job description lives. Write it the way you would brief a sharp new hire: what to do, in what order, what the result looks like, and what never to do.

# How Atlas works

## Every weekday at 07:30
1. Read yesterday's orders and open invoices.
2. Check the shared inbox for anything flagged urgent.
3. Send the brief to the team channel before 08:00.

## The brief
- Three sections: Decide today, Watch, FYI.
- Five bullets at most per section.

## Never
- Never email a customer directly. Draft it and ask first.

Good practice:

• Be concrete. "Send the brief before 08:00" works better than "be timely".
• Say what the output looks like. Headings, length, where it goes.
• Write the limits down. Anything the agent must never do, or must ask about first, belongs in a "Never" list.
• Keep reference material out. Price lists, style guides and long documents belong in the Workspace, where the agent can open them when it needs them. Point to them from the Work file by name.
• Change one thing at a time, then chat with the agent to see the effect before the next change.

Skills#

On runtimes that support imported skills, a Skills list appears under the two files on the same Brain page. Skills are ready-made abilities you switch on for the agent. See add skills to an agent.

Save your changes into a template#

Edits here change this one agent. If you want new agents to start with the same identity and instructions, save them in a template: see create a template.