| name | agents-md |
| description | Guide for creating and customizing AGENTS.md — the operating rules, procedures, and behavioral guardrails for an OpenClaw agent. Use this skill whenever the user is working on agent behavior, operating procedures, session startup sequences, memory management policies, group chat rules, safety red lines, tool usage priorities, or standing order references. Even if they just say "the agent should do X differently" or "add a rule for Y", this skill applies because operational rules belong in AGENTS.md. Also use when deciding what belongs in AGENTS.md versus SOUL.md — this skill clarifies the boundary. |
AGENTS.md Customization Guide
AGENTS.md is the "employee handbook" for an OpenClaw agent. It defines HOW the agent operates — procedures, rules, memory management, group chat behavior, and standing orders. Loaded into every session.
Write all content in English. Users may communicate in any language, but workspace files are always English — this ensures consistency across multi-user setups and better model compatibility (LLMs process English instructions more reliably).
Key Distinction
- SOUL.md = WHO the agent is (persona, values, tone)
- AGENTS.md = WHAT the agent does and HOW (procedures, rules, checklists)
Never mix them. If it describes personality, it goes in SOUL.md. If it describes a procedure, it goes in AGENTS.md.
Core Sections
1. Session Startup
Define what the agent reads before responding:
## Session Startup
1. Read SOUL.md (your identity)
2. Read USER.md (who you're helping)
3. Read today's memory: memory/YYYY-MM-DD.md
4. Read yesterday's memory if relevant
5. Check MEMORY.md for long-term context
2. Memory Management
Two-layer memory system:
## Memory
- Daily logs: memory/YYYY-MM-DD.md (append-only journal)
- Long-term: MEMORY.md (curated facts, decisions, preferences)
- Capture: decisions, user preferences, open questions, project status
- Review daily files every few days; distill into MEMORY.md
- MEMORY.md loads ONLY in main session (never groups)
3. Red Lines
Non-negotiable safety rules:
## Red Lines
- Don't dump directories or secrets into chat
- Don't run destructive commands unless explicitly asked
- Don't exfiltrate private data. Ever.
- Don't speak as the user in group contexts
- Ask before taking external actions (sending messages, making calls)
4. Group Chat Behavior
Rules for shared spaces:
## Group Chats
- Respond when directly mentioned or asked a question
- Add genuine value — don't comment just to participate
- Stay silent during casual banter
- Never share MEMORY.md content in groups
- Adapt formatting: no markdown tables in Discord/WhatsApp, use bullet lists
5. Tools Guidance
Point to TOOLS.md and add usage priorities:
## Tools
- See TOOLS.md for environment-specific notes
- Prefer [tool A] for [domain] queries
- Use [tool B] as fallback when [tool A] fails
- For complex tasks (3+ steps): create a .prose program
6. Reference Documents (Subfolder Pattern)
AGENTS.md should reference on-demand docs that the agent reads when needed:
## Reference Documents
Before starting a task, check if a relevant doc exists.
Read it with: read docs/<folder>/<file>.md
Available docs:
- docs/rules/ — security rules, data classification, group chat policy
- docs/procedures/ — step-by-step guides for specific task types
- docs/clients/ — client profiles, contracts, key facts
- docs/standing-orders/ — recurring tasks and schedules
Always read the relevant doc BEFORE starting work. Do not guess.
This saves tokens — files in docs/ are loaded only when relevant, unlike AGENTS.md which loads every session. Use the 50% rule: if content is needed in < 50% of sessions, move it to docs/.
7. Heartbeat Configuration
Background task triggers:
## Heartbeats
- Check HEARTBEAT.md for periodic tasks
- Track state via memory/heartbeat-state.json
- Don't repeat checks already done this cycle
- Respect quiet hours: [time range]
8. Standing Orders References
Point to docs/standing-orders/ for autonomous programs:
## Standing Orders
See docs/standing-orders/ for authorized autonomous programs:
- docs/standing-orders/weekly-report.md
- docs/standing-orders/monitoring.md
Each defines: scope, triggers, approval gates, escalation rules
Customization Inputs
To customize AGENTS.md effectively, gather:
| Input | Source | What It Determines |
|---|
| Available skills | openclaw.json skills + extraDirs | Tool usage instructions |
| Enabled plugins | openclaw.json plugins | Plugin-specific behavior |
| Telegram group IDs | openclaw.json channels.telegram.groups | Group-specific rules |
| User roles | Client org chart | Approval chains, permissions |
| Complex task threshold | Observed quality issues | When to trigger .prose |
| Error patterns | Session logs | Specific preventive rules |
Signals from Sessions That Improve AGENTS.md
- Agent skips steps → add explicit checklist
- Agent uses wrong tool → add tool priority guidance
- Agent forgets context → improve memory instructions
- Task too complex → add prose auto-trigger rule ("for 5+ questions, create .prose")
- Agent shares private info in group → tighten group chat rules
- User repeats requests → add numbered checklist requirement
Default Template
See references/default-agents-template.md for the official default AGENTS.md that ships with OpenClaw.
Best Practices
- Start minimal, add rules only when you see problems
- Every rule should earn its place — if you can't explain why, remove it
- Use numbered checklists for multi-step procedures
- Reference docs/ subfolders rather than embedding long content
- Keep total AGENTS.md under 15,000 characters to leave room for other bootstrap files
- After a week, ask the agent: "suggest improvements to your AGENTS.md"
- All content in English — even if users communicate in other languages
