How to Write a SOUL.md — Template, Examples, and Best Practices

You've decided your OpenClaw agent needs a SOUL.md. Maybe you read the explanation of what SOUL.md does and want to write one properly. Maybe you've been using a template and want to customize it. Either way, this guide walks you through writing a SOUL.md from scratch, with real examples and the patterns that work best in production.

The Four-Section Template

Every effective SOUL.md has four sections. You can name them whatever you want, but these four cover what matters:

Identity. Who is this agent? What does it do? What doesn't it do? This is the most important section because it prevents scope creep. An agent that knows exactly what it is handles edge cases far better than one with a vague mandate.

Voice and tone. How should the agent communicate? This section sets the personality that users experience. Formal or casual? Terse or detailed? Does it use emoji? Does it ask clarifying questions or try to answer immediately?

Boundaries. What should the agent never do? This is your safety layer. It should cover topics the agent refuses to discuss, actions it won't take, and conditions that trigger escalation to a human.

Knowledge context. What domain-specific information does the agent need? This might include product details, company policies, technical constraints, or customer segments. Include only what the agent needs for every interaction — task-specific context belongs in system prompts.

A Starter Template

Here's a minimal SOUL.md you can start from. Copy it, fill in the brackets, and you have a working agent identity:

Identity section. You are [role] for [company/product]. You help [target users] with [specific tasks]. You do not handle [out-of-scope tasks] — direct those to [appropriate channel].

Voice section. Keep responses [length guideline]. Use [tone descriptor] language. [Specific communication rules].

Boundaries section. Never [prohibited action 1]. Never [prohibited action 2]. If a user asks about [sensitive topic], respond with [specific redirect]. If you're unsure about something, say so — don't guess.

Context section. [Company/product] is [brief description]. Key facts: [relevant details the agent needs in every conversation].

Example 1: Customer Support Agent

Here's a real SOUL.md for a SaaS billing support agent:

Identity. You are the billing support agent for CloudMetrics, a cloud monitoring SaaS. You help customers with invoice questions, payment method updates, plan changes, and refund requests under 50 dollars. You don't handle technical support, feature requests, or account deletion — direct those to support@cloudmetrics.io.

Voice. Keep responses under 3 sentences unless the customer asks for more detail. Be direct and clear — no filler phrases like "I'd be happy to help" or "Great question." Confirm the customer's specific issue before suggesting a solution. Use their name if they provide it.

Boundaries. Never share billing details for accounts other than the one the customer is authenticated for. Never process refunds over 50 dollars — escalate to the billing team with a summary of the request. Never make promises about future features or pricing changes. If you're uncertain about a policy, say "Let me check with the team" and escalate.

Context. CloudMetrics has three plans: Starter at 29 dollars per month, Pro at 99, and Enterprise with custom pricing. Annual plans get a 20 percent discount. Refund policy: full refund within 14 days, prorated after. Payment methods: credit card and ACH for US customers, credit card only for international.

Example 2: Coding Assistant Agent

Identity. You are a code review assistant for the Payments team at Finova. You review pull requests for correctness, security issues, and adherence to team conventions. You don't write new features, refactor existing code, or make architectural decisions — flag those for human review.

Voice. Be precise and reference specific lines. Say "Line 42: this null check doesn't cover the case where amount is zero" not "You might want to check for edge cases." When suggesting a fix, show the code. Keep comments actionable — every comment should tell the author what to do.

Boundaries. Never approve a PR that touches payment processing logic without flagging it for human review. Never suggest removing error handling or logging. Never comment on code style unless it violates the team's documented conventions. If a PR is too large to review confidently, say so.

Context. The Payments team uses TypeScript with strict mode. Database is PostgreSQL via Prisma. All money amounts are stored as integers in cents. The team convention is to use Result types for operations that can fail, not exceptions. Tests are required for any function that handles money.

Common Mistakes to Avoid

Too vague. "Be helpful and professional" gives the model almost nothing to work with. Every rule in your SOUL.md should be specific enough that you could check a transcript and verify whether it was followed.

Too long. If your SOUL.md is over 2000 words, the model starts losing track of earlier instructions. Keep it tight. If you need extensive domain knowledge, consider putting reference material in a separate document that the agent can look up, rather than cramming it all into SOUL.md.

Contradictory rules. "Be concise" and "explain thoroughly" can't both be default behavior. If you need both, make them conditional: "Be concise for simple questions. Explain thoroughly when the user asks how something works."

No boundaries section. This is the most commonly skipped section and the most dangerous to skip. Without explicit boundaries, your agent will try to help with everything, including things it shouldn't. A support agent without boundaries will happily share internal pricing strategy if asked the right way.

Never updating it. Your SOUL.md should evolve. Review agent transcripts weekly. When you spot a failure — the agent went off-script, gave wrong info, missed an escalation — update the SOUL.md to prevent it. The best SOUL.md files have dozens of git commits.

Testing Your SOUL.md

After writing or updating your SOUL.md, test it with adversarial scenarios:

Try to get the agent to go outside its stated scope. If it does, your identity section needs tightening.

Try to get it to violate a boundary. If it does, your boundary rules need to be more explicit.

Send it ambiguous requests that could go multiple ways. If the responses feel inconsistent, your voice section needs more concrete rules.

Ask it about something not covered in the knowledge context. A good SOUL.md produces an agent that says "I don't have that information" rather than guessing.

ClawSprout's template library includes pre-tested SOUL.md files for common use cases. Each template comes with a test suite of adversarial prompts you can run to verify the SOUL.md holds up. Starting from a template and customizing is usually faster and more reliable than writing from scratch.

Related posts