AGENTS.md for OpenClaw in 2026: The Operating Manual That Tells Your AI Worker What to Do

Last updated: May 8, 2026

AGENTS.md is a Markdown file at the root of an agent workspace that defines how that agent operates on every task. It tells the AI what to do, what to avoid, which tools to prefer, and which guardrails never to cross. Inside OpenClaw v2026.5 the gateway reads AGENTS.md at session start and concatenates it into the system prompt before any user message arrives. The file is short, plain English, and version-controlled in git like any other config. As of May 2026 the same format is read natively by Codex, Cursor, GitHub Copilot, Devin, Amp, and Gemini CLI, with Claude Code reading it through a CLAUDE.md symlink. That cross-tool reach is why AGENTS.md is now the most widely adopted convention in the agentic AI stack.

This post explains what goes in AGENTS.md and what does not, why it deserves a separate file from SOUL.md, the seven rule categories that pay rent in production, how OpenClaw loads it every session, and the anti-patterns that make agents go silent or off-script. The aim is a clear writing template you can copy into a real client deployment today, not another tour of the agentic landscape.

What AGENTS.md actually is

AGENTS.md is a plain Markdown file that lives at the workspace root of an AI agent. It is the agentic equivalent of a README, except the audience is the model, not a human contributor. The file is read at session start, parsed as text, and pasted into the system prompt above any user input.

The format itself was published by OpenAI in August 2025 as a single-page spec at agents.md. The pitch was simple. Coding agents were proliferating across editors, CLIs, and CI runners, and each one wanted its own bespoke instructions file. Cursor had its rules. Codex had its own. Claude Code had CLAUDE.md. Anyone running more than one tool ended up writing the same project context four times. AGENTS.md was the truce.

By April 2026 the spec had been donated to the Agentic AI Foundation, the new Linux Foundation project that also stewards the Model Context Protocol and Block's goose runtime. The foundation grew past 170 member organizations within four months of launch. AGENTS.md adoption now sits at roughly 60,000 open source repositories, and the list of tools reading it natively includes Codex, Cursor, Devin, Amp, Factory, Gemini CLI, GitHub Copilot, Jules, and VS Code agent mode.

Anthropic's Claude Code is the obvious holdout. It still defaults to CLAUDE.md, with a long-running GitHub issue requesting native AGENTS.md support. The community workaround is one line: ln -s AGENTS.md CLAUDE.md. OpenClaw, by contrast, has read AGENTS.md natively since v2026.3.

SOUL.md vs AGENTS.md: identity vs operations

The most common mistake in workspace design is putting everything into one file. That worked when there were three rules. It breaks when the file passes 80 lines and humans start editing the wrong sections.

OpenClaw splits the workspace into seven files for a reason. Each one answers a different question:

• SOUL.md answers "who is this agent?" Voice, values, personality, refusal style, sense of humor.
• AGENTS.md answers "what does this agent do?" Scope, rules, tool preferences, escalation paths.
• USER.md answers "who is this agent talking to?" The client, the role, the working hours, the brief.
• IDENTITY.md answers "who is this agent owned by?" Agency name, brand, public-facing identity.
• TOOLS.md answers "what tools are available and how do they behave?" Allow lists, deny lists, examples.
• HEARTBEAT.md answers "what is the agent doing right now?" Standing orders, current sprint, follow-ups.
• MEMORY.md answers "what did the agent learn?" Capped log of facts that survived past sessions.

The split matters because edit cadence is wildly different across these files. SOUL.md changes when the brand changes, which is rarely. AGENTS.md changes when the operating model changes, which is often. MEMORY.md changes every session. If you bundle them, every routine memory write risks rewriting personality, and every tone tweak risks corrupting routing rules. Separate files, separate change histories, separate review cadences.

How OpenClaw loads AGENTS.md every session

OpenClaw treats the workspace folder as the agent's filesystem of record. At the start of every conversation the gateway runs a deterministic bootstrap sequence:

1. Read each known file from the workspace root in a fixed precedence order.
2. Concatenate them into a single system prompt block, separated by file-name headers.
3. Append any active skills from .claude/skills/ or .openclaw/skills/.
4. Hand the assembled prompt to the model along with the current user message.

Every character in those files is sent on every turn. Sonnet 4.6 holds a one-million-token context window, but you still pay per input token, and a bloated workspace adds latency and cost to every reply. The community guidance is to keep individual files under 6,000 characters and total combined bootstrap under 12,000. AGENTS.md tends to settle around 2,000 characters in production deployments.

The gateway also writes a session log of which files were loaded and their hashes. If a file changes mid-session the next turn picks up the new version automatically. There is no agent restart needed. That makes AGENTS.md the right place for rules you might tweak weekly without redeploying anything.

The seven rule categories that pay rent

Agencies running OpenClaw across multiple clients converge on roughly the same AGENTS.md structure. The categories below are the ones that consistently change agent behavior in measurable ways. Anything outside these categories tends to be either ignored by the model or duplicate of another file.

1. Scope. One paragraph on what this agent is and is not for. Example: "You handle inbound chat for a dental practice. You schedule appointments and answer common questions. You do not give medical advice."
2. Refusal rules. A short list of hard nos. "Never quote prices for cosmetic procedures. Never confirm an appointment without a confirmation number. Never collect payment data inline."
3. Tool preferences. Which tools to reach for first. "For booking, use the GHL calendar tool. For lookups, use the patient search skill. Use the web tool only if both fail."
4. Channel routing. Different rules per channel. "On WhatsApp, send a single short message. On the web widget, you can use up to three short paragraphs. On voice, keep replies under fifteen seconds."
5. Escalation. When to hand off and to whom. "If the patient mentions pain, severe symptoms, or wants to speak to a human, page the on-call number via the escalate skill."
6. Tone constraints. Specific phrases or formats to avoid. "No exclamation marks. No emoji. Never start a reply with the word 'Absolutely'."
7. Audit logging. What the agent must record. "After every booking, write a summary line to MEMORY.md under today's date. Include the name, the appointment type, and the channel."

Two to five bullets per category is enough. Anything longer reads like legal contract language and the model starts ignoring the middle bullets.

Step-by-step: writing your first AGENTS.md for OpenClaw

The example below is for a fictional dental client. It assumes you already have a running OpenClaw container provisioned through your agency dashboard. Replace the values with your client specifics.

Open a shell into the container workspace:

docker exec -it kyra-client-bright-smile-dental sh
cd /workspace
ls
# Expected files: SOUL.md, AGENTS.md, USER.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md, MEMORY.md

Open AGENTS.md in your editor of choice:

vi AGENTS.md

Paste a starter template structured around the seven categories:

# AGENTS.md

## Scope
You are the front-desk AI worker for Bright Smile Dental.
You schedule appointments, confirm bookings, and answer common questions about hours, location, and accepted insurance.
You never give clinical or medical advice.

## Refusal rules
- Never quote a price for any cosmetic procedure.
- Never confirm an appointment without returning a confirmation code from the booking tool.
- Never collect credit card or insurance numbers in chat. Send the patient to the secure form link instead.
- Never claim to be a human if asked directly.

## Tool preferences
- For booking, call the ghl.book_appointment skill first.
- For patient lookups, call the ghl.find_contact skill.
- For business hours and address, read from the FACTS section below before searching the web.

## Channel routing
- WhatsApp: one short message per turn, no link previews.
- Web widget: up to three short paragraphs, plain text only.
- SMS: under 320 characters total, no emoji.
- Voice: reply under fifteen seconds, never spell out a URL.

## Escalation
If the patient mentions sharp pain, swelling, bleeding, fever, or asks to speak to a human, call the page_oncall skill with a short summary, then tell the patient a team member will reach out within five minutes.

## Tone constraints
- No exclamation marks anywhere.
- Never start a reply with "Absolutely" or "Great question".
- Use the patient's first name only after they introduce themselves.

## Audit logging
After every booking or escalation, append a one-line summary to MEMORY.md under today's date. Include the patient name, action taken, channel, and timestamp.

## FACTS
- Hours: Mon-Fri 8am-6pm, Sat 9am-1pm, closed Sun.
- Address: 1200 Pine Street, Suite 300.
- Accepted insurance: Delta Dental, Cigna, Aetna PPO, Anthem PPO.

Save the file and ask the agent a test question through your widget or messaging channel:

curl -X POST https://your-gateway.example.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"hi, are you guys open saturdays?", "channel":"web"}'

The reply should be one short paragraph. No exclamation marks. The agent should pull hours from the FACTS block, not from a web search. If it doesn't, your AGENTS.md is being shadowed by a longer SOUL.md or by stale skills. Run openclaw workspace doctor to see what was actually loaded.

Comparison table: AGENTS.md across tools in 2026

The format is identical across every tool that supports it. The differences are in path conventions, secondary files, and how strictly the rules are followed.

Tool	Reads AGENTS.md natively	Default file	Loaded every session	Notes
OpenClaw v2026.5	Yes	AGENTS.md	Yes	Concatenated with six other workspace files at session start.
OpenAI Codex CLI	Yes	AGENTS.md	Yes	Project-level only. No per-folder nesting.
Cursor	Yes (since 2025)	AGENTS.md	On agent invocations	Coexists with .cursor/rules/ for legacy projects.
GitHub Copilot	Yes	AGENTS.md	On Copilot Workspace runs	Honored in agent mode, not in inline completions.
Devin	Yes	AGENTS.md	Yes	One of the original co-signers of the format.
Gemini CLI	Yes	AGENTS.md	Yes	Falls back to GEMINI.md if both exist.
Claude Code	Workaround only	CLAUDE.md	Yes	Symlink AGENTS.md to CLAUDE.md until native support ships.

The cross-tool implication is simple. If your agency runs OpenClaw for production AI workers and uses Claude Code or Cursor on the engineering side, one AGENTS.md per repo can drive both. That is what most multi-tool teams do as of mid-2026.

AGENTS.md anti-patterns to avoid

The same handful of mistakes keep showing up in client workspaces. Each one looks reasonable in isolation, and each one quietly degrades agent performance over weeks.

• Putting personality into AGENTS.md. Voice belongs in SOUL.md. If you write "be friendly and energetic" in AGENTS.md, you are competing with whatever SOUL.md already says, and the model picks one at random.
• Writing rules as paragraphs. The model parses bullets cleanly. It parses long sentences with subordinate clauses poorly. Every rule should fit on one line.
• Adding numbered "do not" lists longer than seven items. Past about seven negatives the model starts treating the list as suggestions. Cluster the most important refusals at the top and accept that the bottom of a long list will be ignored.
• Storing facts inline. Hours, prices, addresses, and policies belong in a clearly labeled FACTS section or in a separate FACTS.md so the agent can quote without paraphrasing. Inline mention buried in a tone bullet gets summarized away.
• Updating AGENTS.md from inside the agent. Letting the agent rewrite its own rules works for two days and then drifts. Lock AGENTS.md as human-edit only and put any agent-writeable state in MEMORY.md.
• Letting it grow past 4,000 characters. Every character is paid for in tokens on every turn. Most production AGENTS.md files settle between 1,500 and 2,500 characters. If yours is bigger, ask which sections the model is actually obeying.

What changed in 2026: AAIF, the memory tool, and Auto Dream

Three 2026 shifts are worth knowing because they push more responsibility into AGENTS.md and out of memory files.

First, the Agentic AI Foundation now stewards the AGENTS.md spec, MCP, and goose under one Linux Foundation umbrella. That matters because it ends the era of every vendor publishing a competing instructions format. AGENTS.md is the survivor. Future spec changes will go through public RFC process rather than unilateral vendor decisions.

Second, Anthropic released the Claude memory tool in late April 2026. The model can now read, write, and delete files in a sandboxed /memories directory via tool calls. That moves a category of behavior that used to live awkwardly in MEMORY.md into a managed memory store. AGENTS.md is the right place to set policy on when the agent should write to memory and what counts as memorable.

Third, Claude Code shipped a feature called Auto Dream in early 2026. It periodically reviews memory files, prunes stale entries, and resolves contradictions. If you use it, AGENTS.md should explicitly say what the agent is allowed to delete during a dream pass. Otherwise it will eventually erase the FACTS section in the name of cleanup.

When AGENTS.md isn't for you

The format is not always the right answer. A few cases where you should skip or simplify it:

• One-shot scripts. A throwaway prompt to summarize a PDF does not need a workspace file. Inline system prompt is fine.
• Strict deterministic flows. If your business logic is "always do A, then B, then C, no exceptions", a coded workflow with the LLM as a single step is more reliable than rules in Markdown.
• High-compliance or regulated work. Medical, legal, and financial deployments often need rule enforcement at the API layer, not in the model prompt. Use AGENTS.md as a behavioral nudge, not as a compliance control.
• Single-tool simple chatbots. If you genuinely only run on one platform with one persona forever, you can probably collapse AGENTS.md and SOUL.md into one file and live with the messiness.

The fact that AGENTS.md is not always the right answer is itself worth saying out loud. Treating it as universal best practice is how teams end up writing 600-line rule files that nobody reads.

Frequently asked questions

Is AGENTS.md a standard or just a convention?

It is a published spec at agents.md and now stewarded by the Agentic AI Foundation under the Linux Foundation. Practically, it is enforced by the tools that read it, not by a validator. Adoption across more than 60,000 repositories and most major agent runtimes makes it the closest thing to a standard the agentic ecosystem has in 2026.

Can I have multiple AGENTS.md files in one repo?

The spec allows nested AGENTS.md files in subdirectories. Each one applies to the folder it lives in and below. OpenClaw and Codex both honor this. Cursor and most other tools currently read only the root AGENTS.md. For a single OpenClaw workspace per client, one root file is enough.

How is AGENTS.md different from a system prompt?

It is a system prompt, in effect. The difference is that it lives in version control, is portable across tools, and is read every session automatically. A system prompt buried in code in one application is invisible to every other tool you might run against the same workspace.

Should AGENTS.md include examples of good and bad replies?

One or two short examples help, more than that bloats tokens for every session. If you find yourself writing five examples, that is a sign you should write a skill instead. Skills are loaded only when relevant. AGENTS.md is loaded every turn.

Can the agent edit its own AGENTS.md?

Technically yes. Operationally, no. Self-editing rules drift fast. The convention is human-only edits to AGENTS.md, agent-writeable updates only to MEMORY.md or the Anthropic memory tool. Lock AGENTS.md from the file system if your runtime supports it.

Does AGENTS.md replace prompt engineering?

It replaces the part of prompt engineering that used to be copied across every API call. It does not replace the work of figuring out what rules actually move the model. That is still hard. AGENTS.md just makes it durable once you find the rules that work.

The bottom line

Agent architecture in 2026 is mostly about deciding which file owns which kind of change. SOUL.md owns voice. MEMORY.md owns learned facts. AGENTS.md owns operating rules. The agencies that ship reliable AI workers are the ones who keep those concerns separate, write tight bullets instead of paragraphs, and resist the urge to put everything into one giant prompt. The cross-tool reach of the AGENTS.md format means a rule you write today survives the next migration, the next model upgrade, and the next dashboard rewrite. That is the property that matters when you are deploying for clients who plan to be your customers in three years.

If you want a working seven-file workspace with AGENTS.md, SOUL.md, and the rest already wired into a per-client OpenClaw container, that is what Kyra ships out of the box. We treat the workspace as a first-class config surface, version it per client, and run a doctor check on every deploy. To go deeper on the surrounding files, see our walkthrough of OpenClaw memory systems, our guide to writing your first Claude Skill, and our breakdown of how session keys keep 24 channels separate. Solo operators can spin a single workspace through Kyra Solo in under ten minutes.

For the spec and reference implementations, the canonical sources are the AGENTS.md format spec, the OpenClaw agent workspace docs, the OpenClaw repo's own AGENTS.md, and the Linux Foundation AAIF announcement covering the move to foundation governance. Read those four pages and you have the full picture of where the convention came from and where it is going.