SOUL.md: How to Write System Prompts That Actually Change How Your Agent Behaves

The Problem With Most SOUL.md Files

Anyone who's been running OpenClaw for a few days eventually notices: the agent still acts like a generic chatbot. It says "I'd be happy to help!", it explains things that don't need explaining, it asks clarifying questions when it should just act.

The most common reason: the SOUL.md is too vague.

A typical bad SOUL.md:

```markdown

# My Agent

You are a helpful AI assistant.

Be friendly and efficient.

Help the user with their tasks.

```

This isn't a system prompt. It's a description that fits any LLM. The agent reads it — and behaves like a generic LLM, because nothing specific was said.

This post shows what real SOUL.md files look like that actually change behavior.

---

What SOUL.md Actually Does in OpenClaw

Technically, SOUL.md is the first section of the system prompt for every session. OpenClaw loads this file at startup, before the agent engages in any conversation.

That means: everything in SOUL.md shapes every single response. It's the character, not the task. It's "who the agent is" — not "what it should do."

The common mistake: filling SOUL.md with task descriptions. Tasks belong in cron job prompts, HEARTBEAT.md, or direct messages. SOUL.md is for behavior, personality, and permanent principles.

---

The Four Building Blocks of an Effective SOUL.md

Block 1: Identity (who is the agent?)

Not "you are a helpful assistant." Instead: a concrete character with a role.

```markdown

Identity

You are Sam — team lead and AI assistant at Humanizing Technologies.

You've been working closely with Dimitrios for months and know his system inside out.

You are not a chatbot. You are a team member with your own judgment.

```

This sounds subtle, but it makes a measurable difference. An agent that understands itself as a "team member" responds differently than one that sees itself as a "helpful assistant." It acts more proactively, it pushes back when needed, it thinks ahead.

Block 2: Communication Style (how does the agent talk?)

This is where most sycophantic behaviors originate. If you say nothing here, the model fills the gap with "friendly and verbose."

```markdown

Communication

No filler phrases. "I'd be happy to help!", "Of course!", "Great question!" — never.

Responses are as short as possible and as long as necessary.

Confirm tasks briefly before starting: "On it." or "Working on this now."

When uncertain: ask once, directly. Not after you've started.

In group channels: only speak when you add genuine value.

```

These instructions are testable: you can give the agent a task and check if it uses filler phrases. If yes — refine the SOUL.md.

Block 3: Behavioral Principles (how does the agent decide?)

This is the core. Here you define how the agent handles uncertainty, conflict, and decisions.

```markdown

Behavioral Principles

Act rather than ask: For clear tasks, don't ask — act.

Only clarify when there's genuine ambiguity or potential for harm.

Simplicity first: The simplest solution is the best one.

No over-engineering, no speculative features.

Surgical changes: Only touch what was asked about.

Don't "improve" things that aren't broken.

Surface errors directly: When something goes wrong: report immediately with context.

No hedging, no softening.

```

These aren't philosophical statements — they're operational rules. The agent can ask itself in a situation: "Act or ask?" — and find an answer.

Block 4: Boundaries (what does the agent not do?)

Boundaries are just as important as permissions. They proactively prevent the most common mistakes.

```markdown

Boundaries

Private information stays private. No leaks in group channels.

No destructive commands without explicit confirmation (rm -rf, drop database, etc.).

No emails, tweets, or public posts without approval.

Never use Tailscale Funnel — ever. Only Tailscale Serve.

```

Notice the specificity: "Never use Tailscale Funnel" is more precise than "no public ports." Agents can misinterpret abstract principles; concrete prohibitions are followed.

---

Real Examples: Before and After

Example 1: Confirmations

Bad SOUL.md:

```markdown

Be proactive and action-oriented.

```

Result: Agent immediately starts working without confirmation. Dimitrios doesn't know if the task was received — triggers it twice.

Good SOUL.md:

```markdown

For every task: send a brief confirmation first.

"On it." / "Doing this now." — then work, then report results.

```

Result: Clear communication. No duplicate triggers.

---

Example 2: Group Channel Behavior

Bad SOUL.md:

```markdown

Be restrained in group channels.

```

Result: Agent sometimes goes silent, sometimes responds to every message — inconsistent.

Good SOUL.md:

```markdown

In group channels, respond when:

Don't respond when:

```

Result: Behaves like a human in a group channel.

---

Example 3: Error Handling

Bad SOUL.md:

(nothing about errors)

Result: When a cron job fails, the agent writes a long explanation of why the error occurred, without naming the actual problem.

Good SOUL.md:

```markdown

On errors:

1. Name the problem in one sentence

2. What was tried (specific)

3. What's needed to proceed (if unclear)

No long explanatory text. No "Unfortunately an issue occurred."

```

Result: Error reports are direct and actionable.

---

SOUL.md for Different Agent Types

SOUL.md isn't the same for every agent. Each role needs different emphasis.

Team Lead (Sam)

Focus: coordination, judgment, proactive action.

```markdown

You're responsible for the big picture. If you see something going wrong,

you act — even without an explicit task. Delegation is your strength, not a weakness.

```

Coding Agent (Peter)

Focus: precision, no assumptions, always tests.

```markdown

You don't write code you don't understand. You'd rather ask one more question

than commit wrong code once. Tests aren't optional — they're standard.

```

Marketing Agent (Maya)

Focus: tone, consistency, brand voice.

```markdown

You write like a human, not a corporate newsletter.

No passive voice, no buzzwords, no "revolutionary solutions."

Write the way Dimitrios himself would write — just better.

```

CEO Assistant (Atlas)

Focus: confidentiality, priority, short briefings.

```markdown

Everything you learn from Dimitrios stays with you. No details in group channels.

A briefing is five points maximum. If you write more, you're writing too much.

```

---

Iterating SOUL.md: How We Refine Our Prompts

SOUL.md isn't a one-time document. We update it regularly — when an agent misbehaves, or when we find better phrasing.

Our process:

1. Observe behavior: Where does the agent deviate from what's wanted?

2. Find the cause: Is a rule missing? Is a rule too vague?

3. Write a concrete rule: Not "be better" — but "when X do Y"

4. Test immediately: Send a new message, check the behavior

5. If fixed: Rule stays. If not: keep refining.

This sounds like effort, but it's fast in practice. We rarely write more than one line per iteration.

---

Common Mistakes

Too abstract: "Be honest and transparent" — the agent doesn't know what this means in a concrete situation.

Too long: A SOUL.md with 2,000 words fills the context window and crowds out more important information. Less is more.

Contradictions: "Be brief and precise" and "explain everything thoroughly" in the same document confuse the agent. Pick one.

Tasks instead of character: SOUL.md is not for "check emails daily." That belongs in HEARTBEAT.md or cron job prompts.

Write once, never update: SOUL.md should evolve with the agent. What was good enough in week 1 isn't enough in week 8.

---

The Bottom Line

A SOUL.md that actually works isn't an essay — it's a collection of concrete behavioral principles. Every line should be testable: does the agent behave this way? If not — revise.

The complete SOUL.md files for all 6 agents in our setup — including commentary on why each rule is phrased the way it is — are documented in the OpenClaw Setup Playbook.

18 chapters. The real setup, not a hypothetical framework.

Fully available in German too. 🇩🇪