AGENTS.md and Other Workspace Files
Open a well-used OpenClaw workspace and you may find a dozen markdown files. It looks cluttered until you notice that each recognised name answers exactly one question, and that the name also tells you when the file matters.
The rule
Each workspace file answers one question; its name tells you which.
| File | The question it answers |
|---|---|
SOUL.md |
Who is the agent: personality, tone, ground rules? |
IDENTITY.md |
The agent's persona again: an alternative or complement to SOUL.md |
USER.md |
Who are you? |
AGENTS.md |
Which agents are there, what role does each play, and how do they work together? |
TOOLS.md |
Which tools are available, and how should they be used? |
MEMORY.md |
Which lasting facts has the agent learned? |
memory/YYYY-MM-DD.md |
What happened on that day? |
HEARTBEAT.md |
What should be checked on each heartbeat? |
BOOT.md |
What should be done once, when the Gateway starts? |
AGENTS.md earns a closer look. It holds the working rules and roles: how the agent is meant to operate, and, once you run several agents, who does what and how they relate. Without it, two agents with overlapping jobs can end up duplicating or contradicting each other.
The files that shape the agent, such as SOUL.md, USER.md, AGENTS.md and TOOLS.md, are loaded into its context automatically at the start, so they cost space in every conversation. The memory files are there for the agent to consult and search. Beyond all these, you can keep any other markdown file in the workspace, such as project notes, reference documents or instructions for one particular task, for the agent to read when a job calls for it. Skills have their own home too: each lives in a skills/ folder with its SKILL.md.
The shortcut
File each note by when it should be read. Every conversation: a recognised file such as SOUL, USER, AGENTS or TOOLS. Once at start-up: BOOT.md. On each heartbeat: HEARTBEAT.md. Only when a task needs it: an ordinary markdown file.
"When the Gateway restarts, tell me you are back."
Once, at start-up:
BOOT.md.
Drills
Answer fast — trust the rule.
Which file holds instructions the agent runs once, when the Gateway starts?
You run a research agent and a writing agent. Which file sets out their roles and how they work together?
Which file describes the tools available and how to use them?
Why not paste a 40-page manual into a recognised workspace file?
What is IDENTITY.md?
Remember
- Each workspace file answers one question; its name tells you which.
- File each note by when it should be read: every chat, at start-up, on each heartbeat, or only when needed.
- Trap: stuffing long reference material into files that load into every conversation.