How to Write AGENTS.md for OpenClaw: Step by Step

If you want an OpenClaw agent to behave consistently, AGENTS.md is one of the first files to write. The simplest way to think about it is this: AGENTS.md is the agent's operating manual. A good one tells the agent what this workspace is for, how it should work, what it must not do, and when it should stop and ask for help.

That is the direct answer.

A lot of people know they need AGENTS.md, but they still stare at a blank file because they are not sure what actually belongs in it. This tutorial fixes that. I will walk through a practical structure, explain why each section matters, and show you how to write a version that improves real workflows instead of just sounding nice.

If you want the conceptual version first, read what AGENTS.md is and why every AI agent needs one. For the broader system around it, also read OpenClaw workspace design best practices and what OpenClaw is.

What AGENTS.md is doing

AGENTS.md is where you write the operating rules that should stay true across tasks.

That can include:

• mission and scope
• approval rules
• workflow steps
• file conventions
• escalation conditions
• memory rules
• communication style for status updates

It is not just a prompt dump. It is the file that turns the workspace into a place the agent can actually operate inside.

Step 1: start with the workspace mission

Open with two or three short sentences that explain what this workspace is for.

This matters because the agent needs to know what kind of work belongs here.

A strong mission section answers:

• what project or domain is this?
• what outcomes matter most?
• what should the agent optimize for?

For example:

## Mission
This workspace supports OpenClawCrew content and SEO operations.
Priorities are publishing clear, useful content, preserving existing patterns, and avoiding unrelated edits.
When in doubt, prefer small, safe changes over big rewrites.

That is enough to orient the agent.

Step 2: write the non-negotiable rules

This is the section that prevents expensive mistakes.

Be direct.

Good rules look like this:

• do not edit unrelated files
• ask before destructive changes
• draft external messages before sending
• do not widen scope without approval
• prefer small changes over broad refactors

Bad rules sound like this:

• be careful
• be helpful
• use judgment

The agent cannot operate well on vague virtues. It can operate well on clear rules.

Step 3: describe the expected workflow loop

Most teams want work to happen in a certain order. If that order matters, write it down.

A clean workflow loop often looks like this:

1. read the relevant files first
2. confirm the intended change
3. implement the smallest version that works
4. validate the result
5. summarize what changed and any remaining risk

If you want that behavior consistently, AGENTS.md is the place to require it.

Step 4: point to the important files

An agent works better when it knows where the source of truth lives.

A file map section can be short, but it is extremely useful.

For example:

## Important files
- AGENTS.md: operating rules
- SOUL.md: tone and identity
- USER.md: user preferences and business context
- HEARTBEAT.md: recurring checks
- memory/: daily notes and long-term context

This prevents a lot of confusion, especially in larger workspaces.

Step 5: define approval and escalation rules

This section is about trust.

The agent should know when it must stop and ask instead of pushing ahead.

Strong escalation triggers include:

• destructive actions
• external messaging
• conflicting instructions
• unclear requirements
• low-confidence interpretation of user intent

A clean section might say:

## Approval rules
- Ask before deleting, publishing, sending, or purchasing.
- If instructions conflict, stop and ask.
- If confidence is low and the cost of a mistake is meaningful, escalate.

That goes a long way.

Step 6: add memory rules

If you want continuity, say what should be written down.

This can be as simple as:

## Memory rules
- Log important decisions to memory.
- Update active project notes when status changes.
- Do not store secrets in workspace notes.

This helps the agent preserve context instead of starting from zero every time.

Step 7: add communication rules

You can shape the way the agent reports progress too.

Useful rules include:

• summarize first, details second
• use bullets for next steps
• keep status updates short unless the task needs depth
• say clearly what was verified and what was not

These small rules make collaboration much smoother.

A practical template you can start from

Here is a compact example:

# AGENTS.md

## Mission
This workspace supports content and operational workflows for OpenClawCrew.
Prioritize clarity, small safe changes, and consistent execution.

## Rules
- Stay inside the requested scope.
- Ask before destructive or external actions.
- Prefer small edits over broad rewrites.
- Do not remove user work you did not create.

## Workflow
1. Read the relevant files first.
2. Confirm the intended change.
3. Make the smallest working update.
4. Validate the result.
5. Summarize what changed.

## Important files
- SOUL.md: tone and boundaries
- USER.md: preferences and context
- HEARTBEAT.md: recurring checks
- memory/: daily and project notes

## Approval rules
- Ask before sending, publishing, deleting, or purchasing.
- Stop if instructions conflict.
- Escalate low-confidence interpretations.

## Memory rules
- Log important decisions.
- Update project notes when status changes.
- Keep secrets out of workspace files.

That is not the only way to do it, but it is a very good starting point.

Common mistakes when writing AGENTS.md

Mistake 1: writing slogans instead of rules

The file should change behavior. If a sentence cannot change behavior, it probably needs to be rewritten.

Mistake 2: making it too generic

A useful AGENTS.md should reflect the real workspace, not some imagined all-purpose agent.

Mistake 3: forgetting the negative cases

Tell the agent what not to do, not just what to do.

Mistake 4: never updating it

If the agent keeps making the same mistake, that correction probably belongs in AGENTS.md.

How to improve AGENTS.md over time

The best version usually appears after real use, not before.

Here is a practical rhythm:

Week 1

Write the first simple version.

Week 2

Notice where the agent drifted, overstepped, or needed repeated correction.

Week 3

Turn those repeated corrections into written rules.

Week 4

Tighten anything vague and cut anything bloated.

That process works because it is based on real behavior, not guesswork.

What a good AGENTS.md feels like in practice

When the file is good, a few things happen:

• the agent starts tasks with less setup overhead
• output gets more predictable
• review is faster
• scope creep drops
• repeated mistakes happen less often

That is the bar. A good AGENTS.md should make the system easier to trust.

My recommendation

If you are writing AGENTS.md today, do not try to cover every edge case.

Start with these six blocks:

• mission
• non-negotiable rules
• workflow loop
• important files
• approval rules
• memory rules

That is enough to create a real operating manual.

If you want the official references, review the OpenClaw docs and the OpenClaw GitHub repository. Then compare your file to one simple standard: does it reduce repeated mistakes, or is it just describing good intentions?

FAQ

What should go in AGENTS.md?

Mission, scope, rules, workflow steps, approval boundaries, escalation conditions, and references to important workspace files.

How long should AGENTS.md be?

Long enough to be useful, short enough to maintain. Clarity matters more than length.

What is the difference between AGENTS.md and SOUL.md?

AGENTS.md handles operating rules and workflow. SOUL.md shapes tone, identity, and broader behavioral boundaries.

Should I put every rule in AGENTS.md?

No. Put the durable operating rules there. More local or repeated routines may belong in files like HEARTBEAT.md or project notes.

How do I know if AGENTS.md needs an update?

If the agent keeps making the same category of mistake or needs the same correction more than once, the file probably needs to improve.

Match the file to the real team shape

One more tip that makes a big difference: write AGENTS.md for the way work actually happens, not the way you wish it happened.

If your team reviews every outbound message, say that. If only one person approves production changes, say that. If the real goal is fast drafts and tidy handoffs, say that too.

The more the file matches reality, the more useful it becomes. The more it sounds like a generic policy document, the faster people stop trusting it.