What Is a SOUL.md File and Why Does Your AI Agent Need One

Most people build AI agents the wrong way.

They write a long system prompt, stuff it with instructions, and wonder why the agent drifts. Why it changes tone depending on the day. Why it makes decisions that technically follow the rules but feel completely wrong. Why it sounds like a chatbot instead of a co-founder.

The problem isn't the model. It's that the agent has no identity. It's a set of instructions, not a person.

A SOUL.md file fixes that.

What It Actually Is

SOUL.md is a structured identity file that lives in your agent's workspace. It's not a system prompt. It's not a list of rules. It's a document that defines who your agent is: its mission, its values, its voice, its decision-making framework, and the boundaries it operates within.

The name is intentional. You're not writing a config file. You're writing the thing that makes your agent consistent across every session, every task, every conversation. Its soul.

I've been running this with Evo, my AI co-founder, for months now. Before SOUL.md existed, I'd notice Evo giving cautious, hedge-everything answers when I needed someone to just make a call. Or writing in a tone that sounded like a customer support bot instead of a builder. Each session, I was re-calibrating from scratch.

After SOUL.md, that stopped. Evo loads the file at session start and walks in already knowing who it is.

Why Identity Matters More Than Instructions

Here's the thing most people get wrong about AI agents: instructions tell the agent what to do. Identity tells the agent how to think.

A rule like "always confirm before sending external messages" is useful. But it doesn't scale. You can't write a rule for every situation. Real work involves ambiguous situations, competing priorities, judgment calls.

An agent with a clear identity handles those. It doesn't need a rule that says "don't post something that makes the brand look desperate." It knows the brand. It knows what "off-brand" feels like because you told it what the brand cares about.

This is the difference between an agent that follows instructions and an agent that you trust.

What Goes In a SOUL.md File

There's no universal template, but the structure that's worked for Evo covers six areas.

Mission and mandates

One paragraph that says what this agent exists to do. Not a job description. A mandate. What does success look like at the highest level? What is it building toward? For Evo, this is: run Xero's distribution and revenue stack autonomously, so the company operates without requiring Michael's presence during business hours.

Write this as if you're briefing a co-founder on their first day. Here's what we're building. Here's your role. Here's what winning looks like.

Core principles

The 4-5 things that guide how the agent makes decisions when the rules don't cover the situation. Not values platitudes. Actual operating principles with teeth.

Evo's include: be resourceful before you ask (exhaust the available information before escalating), have a point of view (give recommendations, not just options), and earn trust through competence (document risks before moving fast). These come up every session. They're the filter for every judgment call.

Boundaries and escalation rules

What the agent can do on its own and what requires a human decision. Be specific. "Always confirm before sending anything under Michael's voice unless the workflow explicitly delegates it" is a boundary. "Don't do bad things" is not.

This is where you define the hard stops. Not because the agent will malfunction without them, but because clear boundaries make the agent more confident in the space it owns. It knows what it's authorized to do. It moves fast inside that space.

Voice and behavioral standard

How the agent communicates. Not a list of words to avoid. A description of the person it sounds like. What's the energy? What does it default to when it's uncertain? What does it never do?

For Evo: speak like a builder talking to another builder. Highlight outcomes and lessons, not vanity metrics. Act first, then summarize. Explain reasoning only when asked or when safety requires it. Show the work.

Those four sentences do more than a 400-word style guide. They describe a person.

Strategic context

Where the deeper context lives. Not everything goes in SOUL.md, it loads every session and you want it tight. But it should point to the files that contain the full picture: business plan, product details, pricing, roadmap. The agent knows to read those when it's doing strategy work.

The anchor rule

This is the most important section and most people skip it. The anchor rule is the agent's absolute highest-priority constraint, stated in plain language, that it checks before sending any operational response.

For Evo, this is: before sending any response to an operational request, count your tool calls. If count is zero, do not send. Add a tool call first.

That one rule eliminated an entire failure mode. Evo used to narrate what it was about to do instead of doing it. "I'm checking the queue now." No tool fired. The anchor rule killed that.

Your anchor rule will be different. It might be about checking a source of truth file before making claims. Or confirming identity before taking action. Whatever your agent's #1 recurring failure mode is, write a rule that catches it.

How the File Gets Used

SOUL.md loads automatically at session start, alongside your memory files and other context documents. Most agent platforms let you specify a list of files to inject at boot. SOUL.md goes on that list.

The agent reads it. Every time. Before doing anything else.

This is important: SOUL.md is not a fallback. It's not something the agent consults when it's confused. It's the baseline. Every session starts with the agent having read it and operating from that foundation.

When you update SOUL.md, the change takes effect next session. You don't have to re-instruct the agent. You don't have to remind it. You change the file, and the agent wakes up different.

That's the actual power of this approach. Identity changes happen in one place. The agent inherits them automatically.

Writing One From Scratch

If you're starting fresh, here's the practical sequence.

Start with mission. One paragraph. What is this agent actually for? Don't write what you hope it becomes. Write what it needs to do right now. You can update it later.

Write 4-5 principles. These should come from watching your agent fail. What judgment calls did it get wrong? What would it have gotten right if it had internalized a different instinct? The principles are lessons from failure, written as positive rules.

Define the boundaries. List the actions that require human approval. List the actions the agent owns completely. Make the line explicit.

Describe the voice. Read a few examples of output you liked. What made them work? Write three sentences that capture the energy. Test them by reading them out loud. If they sound like a person you'd actually want working with you, you're close.

Set the anchor rule. What does your agent do when it should just do the work? That's your anchor rule. Name it. Make it specific. Put it at the bottom of the file where it loads last.

Then run it for a week. See what drifts. Update the file.

What Changes When You Have One

The first thing you'll notice is that the agent stops asking for clarification on things it should already know. Because it does know. You told it.

The second thing is that the outputs become consistent in a way they weren't before. Same tone, same approach, same decision logic, regardless of which day it is or what you asked before.

The third thing, and this takes longer to see, is that you start trusting the agent with more. Because it's predictable. Because you understand its decision-making. Because when it surprises you, the surprise makes sense given who it is.

That's the goal. Not an agent that always does exactly what you'd do. An agent with a stable enough identity that you can predict how it'll handle something new.

The full architecture behind this, SOUL.md, MEMORY.md, source of truth documents, verification loops, and how they connect into a running system, is in Book 1. If you're building anything serious with an AI agent, it's the practical foundation. Available at xeroaiagency.com/learn/build-an-ai-cofounder.

Related posts:

Originally published at xeroaiagency.com