01
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, loaded when a chat starts and kept for the rest of that chat.
02
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.
03
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.
04
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.
05
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.