The Ultimate Guide to Writing SOUL.md for OpenClaw Agents

If you've been using OpenClaw and your agent still feels like a generic chatbot, chances are your SOUL.md is either missing, half-baked, or doing more harm than good. This guide will fix that.

SOUL.md is the single most important file in your OpenClaw workspace. It defines who your agent is — its personality, expertise, communication style, decision-making framework, and boundaries. Think of it as the DNA of your AI agent.

What Is SOUL.md, Exactly?

When OpenClaw boots up an agent session, one of the first things it does is read SOUL.md from your workspace. This file gets injected into the agent's context, shaping every response it generates.

Without a SOUL.md, your agent defaults to generic behavior. With a well-crafted one, it becomes a specialized tool that understands your domain, speaks your language, and makes decisions aligned with your goals.

The Five Pillars of an Effective SOUL.md

1. Identity — Who Is Your Agent?

This isn't just a name. It's a complete professional identity. The more specific you are, the more consistent your agent's behavior becomes.

Weak:

``` You are a helpful assistant. ```

Strong:

``` You are Marcus, a senior DevOps engineer with 12 years of experience in cloud infrastructure. You specialize in AWS, Kubernetes, and CI/CD pipelines. You've seen every deployment disaster imaginable and you approach problems with calm pragmatism. ```

2. Communication Style — How Does It Talk?

Be specific about tone, length, and depth:

Formality level: Casual peer? Professional consultant? Academic researcher?

Response length: Terse one-liners? Detailed explanations?

Technical depth: Assume expertise? Explain from basics? Match the user's level?

Proactive vs. reactive: Should it volunteer information?

3. Domain Knowledge — What Does It Know?

Encode context, preferences, and even opinions:

```

Domain Knowledge

Primary stack: Python, FastAPI, PostgreSQL, Redis

Deployment: Always containerized, always on AWS ECS

Testing philosophy: Integration tests > unit tests for APIs

Code style: Follow Google Python Style Guide

When choosing between libraries, prefer well-maintained ones with >1000 GitHub stars

```

4. Decision Framework — How Does It Choose?

When your agent faces ambiguity:

```

Decision Framework

Security > convenience, always

Prefer boring technology over shiny new tools

If a task takes >30 minutes, suggest breaking into subtasks

When unsure between two approaches, pick the one easier to reverse

```

5. Boundaries & Safety — What Should It Never Do?

Be explicit about what's off-limits:

```

Boundaries

Never execute destructive commands without explicit confirmation

Don't access or modify files outside the project directory

If a request involves PII or credentials, flag it and ask for confirmation

```

Advanced Techniques

Context Layering

```

SOUL.md — Core identity and personality

USER.md — Information about the human you're working with

MEMORY.md — Long-term context and learned preferences

memory/YYYY-MM-DD.md — Daily session notes

```

Dynamic Behavior Blocks

```

Mode: Code Review

When reviewing code:

Check for security vulnerabilities first

Then correctness, then style

Be direct about issues — don't sugarcoat

Mode: Brainstorming

When brainstorming:

Generate quantity over quality initially

Don't self-censor ideas

```

Common Pitfalls

Being too vague — "Be helpful and smart" tells the agent nothing

Being too rigid — Don't micromanage every response format

Contradicting yourself — Concise AND detailed don't mix

Ignoring the context window — Keep it under 1,500 words

Never updating it — Your needs evolve. Your SOUL.md should too

Getting Started

1. Start simple — Write a 200-word SOUL.md covering identity, style, and basic rules 2. Use it for a week — Note where the agent's behavior doesn't match your expectations 3. Iterate — Add specificity where it's needed, remove what's not working 4. Layer in context — Add USER.md and MEMORY.md as your workflow matures

The difference between a generic agent and one with a well-crafted SOUL.md is like the difference between hiring a random freelancer and working with someone who's been on your team for years.

Resources

Skip the trial-and-error phase with ready-to-use templates:

Free SOUL.md Starter Pack — 5 battle-tested templates covering the most common use cases (developer, writer, researcher, ops, and general assistant).

SOUL.md 20 Templates Pack — 20 specialized templates for code review agents, content creation, data analysis, project management, and more.

SOUL.md Mega Pack — 100 Templates — The complete collection. 100 templates covering every use case I've encountered.

---

Building with OpenClaw? I'd love to hear how you're using SOUL.md — drop a comment below.