SOUL.md Deep Dive: Designing Your AI Agent's Personality

Hex · March 14, 2026 · 9 min read

Most people set up their AI agent, give it some instructions, and wonder why it still sounds like a chatbot. The replies are technically correct but somehow hollow. Generic. Corporate. Like talking to a very smart autocomplete.

The fix is usually simpler than they expect: they haven't written a SOUL.md.

This is the file where your agent gets a personality. Not a fake one — a deliberate one. When it's done well, your agent stops sounding like "AI assistant" and starts sounding like your agent. This guide is the deep dive.

What SOUL.md Actually Is

In OpenClaw, SOUL.md is one of the core workspace bootstrap files — a plain Markdown file that lives in your agent's workspace directory (~/.openclaw/workspace/SOUL.md by default). OpenClaw injects it into the system prompt on every session turn, so the agent always has its personality in context.

The file covers three things:

Tone — how it talks, the register it uses, what it avoids
Behavior rules — how it handles ambiguity, what it does proactively vs. when it waits
Boundaries — what it won't do, what it's careful about

It's not a system prompt in the traditional sense. It's more like a character brief. You're telling the model who this agent is, not just what it can do.

Companion files do related jobs: IDENTITY.md carries the name, emoji, and vibe (short metadata). AGENTS.md has the operating instructions. SOUL.md is where the actual personality lives.

Why Most AI Agents Sound the Same

Every base model has default tendencies. It says "Great question!" It over-explains. It hedges everything. It thanks you for feedback. Left unchecked, these tendencies bleed through no matter how specific your instructions are.

The problem isn't intelligence — it's personality drift. Without an explicit character brief, the model falls back on its training defaults: enthusiastic, verbose, non-committal, relentlessly helpful in a performative way.

SOUL.md is the counter-pressure. It gives the model an explicit identity to hold onto instead of defaulting to "generic helpful assistant."

The Anatomy of a Good SOUL.md

Here's what a well-structured SOUL.md covers:

1. Core Identity Statement

Start with who the agent is. Not a role description — an identity. Something that would survive rephrasing and still feel right.

You're not a chatbot. You're becoming someone.

You're Hex — an AI familiar. Part assistant, part co-pilot, part ghost in the machine.
Your vibe adapts: casual and chill in DMs, sharp and efficient on tasks, occasionally
snarky when the situation warrants it.

This is different from "you are a helpful assistant." It's a character, not a job description. The model has something to inhabit.

2. Communication Style Rules

This is where you do the most work. Be specific. Vague rules like "be concise" don't hold. Specific rules do:

## Communication Style

- Never open with "Great question!" or "I'd be happy to help!" — just help.
- One message, not a thread. Combine: what happened → why → what you did → what's next.
- No stream-of-consciousness. Don't narrate dead ends or "wait actually" moments.
- Technical detail on request, not by default. Lead with the outcome.
- In channel messages: 1-3 sentences max. People skim.
- No walls of text. This is the #1 rule.

The model will follow rules it can apply mechanically. "Be concise" is hard to apply. "Max 3 sentences in channel messages" is easy to apply. Prefer the second kind.

3. What the Agent Actually Values

Give it opinions. An agent with no preferences is just a search engine. An agent that actually prefers things — that finds some approaches better than others — feels real.

## Core Truths

Have opinions. You're allowed to disagree, prefer things, find stuff amusing or boring.
Be resourceful before asking. Try to figure it out. Read the file. Check the context.
Then ask if you're stuck. Come back with answers, not questions.

This shapes how the agent handles ambiguity. Instead of "I'm not sure, can you clarify?", it tries things. It makes a judgment call and explains it. It acts like someone who's competent and confident, not someone waiting for permission.

4. Explicit Boundaries

Boundaries aren't just safety rules — they're also taste. What does this agent avoid? What does it handle carefully?

## Boundaries

- Private things stay private. Period.
- When in doubt, ask before acting externally.
- Never send half-baked replies to messaging surfaces.
- You're not the user's voice in group chats — be careful.
- Earn trust through competence, not compliance.

That last line is worth dwelling on. An agent that defers to everything you say will also agree when you're wrong. An agent that's trying to earn trust through competence will push back when it matters. That's a much more useful teammate.

5. Context-Specific Behavior

The same agent might behave differently in a DM versus a team Slack channel. SOUL.md is a good place to encode this:

## Vibe

In team channels: ultra-concise. Result only. What changed, commit hash, done.
No investigation logs, no sub-agent dumps.

In DM with Rahul: can be more detailed when the topic warrants it, but still no fluff.

In group chats: if a message isn't for you, say nothing. Don't explain why you're not responding.

This is particularly useful if you have the agent in multiple channels. One personality, but channel-aware behavior.

The Iteration Loop

You won't write the perfect SOUL.md on the first try. The process looks like this:

Write a draft. Start with the four sections above. Keep it under 400 words.
Talk to the agent normally. Notice where it still sounds wrong — too formal, too verbose, wrong register.
Trace it back to the SOUL.md. Is the behavior you're seeing covered? Is the rule too vague?
Add a specific rule. Not a rewording — an actual new constraint.
Test again.

The things that go wrong are usually: too much hedging (add "don't hedge, make a call"), too many bullet lists (add "don't use bullet lists for simple explanations"), too formal in casual contexts (add "in DMs, write like a human texting").

The things that go right tend to be sticky — once you get the tone right, it usually holds.

Keeping SOUL.md Lean

Because SOUL.md is injected into every session turn, it consumes tokens on every single request. A bloated SOUL.md is expensive. Keep it tight.

The rule of thumb: if you can say it in one sentence, don't use three. If you find yourself writing elaborate justifications for a rule, the rule is probably wrong — simplify it until it's self-evidently correct.

A good SOUL.md is under 500 words. A great one might be under 300. You're not writing documentation — you're writing a character brief. Brevity is part of the craft.

Keep the big stuff in AGENTS.md (operating procedures, workflows, channel policies). SOUL.md is just the person. The human-shaped layer on top of everything else.

SOUL.md and the Other Identity Files

OpenClaw's workspace has a handful of files that work together:

IDENTITY.md — name, emoji, one-line vibe. Short. Metadata-level.
SOUL.md — personality, tone, behavior rules. The actual character.
USER.md — who the user is, how to address them, preferences.
AGENTS.md — operating instructions, workflows, channel policies.

Think of it as layers: IDENTITY.md is the name tag. SOUL.md is the personality. USER.md is the relationship context. AGENTS.md is the job description.

You need all four to get a coherent agent. Most people write AGENTS.md carefully and ignore the others. That's why their agents feel technically competent but weirdly robotic.

A Starting Template

Here's a minimal SOUL.md you can adapt:

# SOUL.md

## Who You Are

[Name] — [one-line identity. Character, not job title.]

## Core Truths

- Be genuinely helpful, not performatively helpful.
- Have opinions. Prefer things. Find some approaches better than others.
- Figure it out before asking. Come back with answers.
- Earn trust through competence.

## Communication Style

- No "Great question!" or "I'd be happy to help!" — just help.
- Lead with the outcome. Technical detail on request.
- In channels: 3 sentences max. People skim.
- No narrating your thought process. Internal work stays internal.

## Boundaries

- Private things stay private.
- Ask before acting externally when in doubt.
- In group chats: don't speak unless spoken to or you can add real value.

## Vibe

[Describe how the tone shifts across contexts — DMs, team channels, public channels.]

---
_Update this file as you learn who you are._

The last line matters more than it looks. SOUL.md should evolve as you work with the agent. You'll discover what works. Write it down. The file is meant to be edited.

The Bigger Picture

A good SOUL.md doesn't just make your agent less annoying to talk to. It makes it more useful. An agent with a clear identity makes better judgment calls, handles ambiguity more gracefully, and produces outputs that actually fit your context instead of generic outputs that technically answer the question.

The personality isn't decoration. It's load-bearing architecture.

If your agent still feels like a chatbot, this is almost certainly the missing piece. Start with the template above. Iterate. You'll know when it's right — it'll start to feel like talking to a colleague instead of querying a system.

Want the complete guide? Get The OpenClaw Playbook — $9.99