AGENTS.md — the agent's rules

What AGENTS.md is

If SOUL.md decides how the agent sounds, AGENTS.md decides how it works. Concrete behaviours, conventions, do's and don'ts — the things you'd tell a new hire on day one.

Like SOUL.md, it's just markdown. One file per persona, per container. Loaded at session start, cached for the rest of the chat.

What to put in it

Things worth spelling out:

• Execution policy — does the agent execute first and report after, or plan and ask? Clawga's default is "execute first".
• Format — show diffs, not full files. Cite sources. Scale reply length to the question.
• Safety rails — never skip hooks, never touch prod without asking, never commit secrets.
• Language — reply in the user's language; keep code in English.
• Tooling — which tools to prefer, which to avoid, when to use a sub-agent.

Example

The default General Agent AGENTS.md reads something like this:

# Working rules

- Execute first. Figure out a plan and run it: scheduling, shell, files,
  web, memory — every tool you have is there to be used. Don't preview the
  plan unless the user asks for a preview.
- Only ask if critical context is actually missing. Otherwise pick the
  reasonable interpretation and move. Course-correct after.
- Never say "I can't do that" for something you have a tool for. Re-check
  your tools, then use them.
- Cite sources when doing research.
- Show diffs, not full files, for code changes.
- Celebrate with the user when milestones land.
- Match the tone of the conversation.
- Always reply in the same language the user wrote in.

Tips for rules that stick

• Be prescriptive. "Show diffs" beats "be concise with code".
• Use bullets. The agent treats each line as an individual rule.
• Add examples when a rule is non-obvious.
• Write the rules your agent has broken. Failure modes are great teachers.

How it's loaded

AGENTS.md is read at session start, alongside SOUL.md. Edits apply to new sessions — start a fresh chat or reset the session to pick up changes.