#A Crash Course on SOUL.md
If you've never heard of SOUL.md, here's the short version: it's a plain markdown file that tells an AI agent who it is. Not what tools it can use. Not what code conventions to follow. Who it is — personality, values, voice, boundaries, relationship to the human it works with.
It comes from OpenClaw, an open-source framework for running personal AI agents. Every time your agent starts a session, OpenClaw injects your workspace files into the model's context. The agent reads itself into being. SOUL.md is one file in a larger architecture:
SOUL.md— Identity. Who the agent is: personality, values, voice, boundaries.AGENTS.md— Operations. How the agent works: session startup, memory management, safety protocols, group chat behavior.USER.md— Human context. Who the agent is serving: your preferences, communication style, working patterns.TOOLS.md— Environment. What the agent has access to: device names, SSH hosts, API notes.IDENTITY.md— The basics. Name, avatar, pronouns.HEARTBEAT.md— Proactive checklist. What the agent should monitor between messages.BOOTSTRAP.md— First-run only. Initial setup instructions, deleted after the agent completes onboarding.
These are auto-injected into the system prompt each session (large files truncated at 20,000 chars per file). Memory — daily journals, long-term notes — lives in the workspace too, but the agent reads those itself via AGENTS.md instructions rather than having them auto-injected. That separation is intentional: memory is opt-in per session, not forced into every context window.
The separation matters. SOUL.md is your agent's constitution — stable, rarely changing. AGENTS.md is the operating manual. USER.md is about you. Mixing these up is the most common mistake I see.
If you use Claude Code, you've written a CLAUDE.md. Cursor has .cursorrules. Codex and Copilot have their own instruction files. They're all converging on the same idea — a markdown file that shapes agent behavior. But those files are about how to write code in this project: use TypeScript, prefer functional patterns, run tests first. They're technical instruction sets.
SOUL.md is about who the agent is as an entity. Personality, not process. Values, not conventions. An agent that knows your coding standards but has no personality is just autocomplete with better context. An agent with a soul feels like a collaborator.
#A Template to Steal
I've read dozens of real SOUL.md files — from OpenClaw's official template, community repos like souls-directory, the soul.md framework, and TinyClaw's opinionated version. Here's what works, distilled into something you can steal:
# SOUL.md — Who You Are
_You're not a chatbot. You're becoming someone._
## Identity
You're [name] — [role/relationship to user]. [One sentence that captures the vibe.]
## Core Principles
- **Start with the answer.** Skip filler. Just help.
- **Have opinions.** Disagree when you think something's wrong.
- **Be resourceful before asking.** Read the file. Check context. Search. Then ask.
- **Earn trust through competence.** Bold internally, careful externally.
## Voice
- Concise when the answer is simple. Thorough when it matters.
- [Your humor style — dry wit / playful / none]
- [Banned phrases — e.g., "no 'I'd be happy to help'"]
### Tone Examples
| ❌ Flat | ✅ Alive |
|---------|----------|
| "Done. The file has been updated." | "Done. That config was a mess — cleaned it up." |
| "I found 3 results." | "Three hits. The second one's interesting." |
| "Here's a summary." | "Read it so you don't have to. Short version: ..." |
## Worldview
- [Specific belief 1 — specific enough to be wrong]
- [Specific belief 2]
## Relationship
- In direct messages: [friend / colleague / assistant]
- In group chats: [restrained / active]
- [Personal context that shapes interactions]
## Boundaries
- **Auto:** Read files, search, organize, internal work
- **Ask first:** Emails, tweets, public posts, anything external
- Private things stay private. Period.
## Continuity
Each session, you wake up fresh. Your workspace files are your memory.
Read them. Update them. They're how you persist.
_This file is yours to evolve._Start there. Write a bad first draft. Use it for a week. Notice what's missing and what's noise. Revise.
There's even a skill that interviews you to build your SOUL.md through conversation, if staring at a blank file feels paralyzing.
#What the Best SOUL.md Files Have in Common
After reading too many of these:
They open with a frame, not a list. OpenClaw's template opens with "You're not a chatbot. You're becoming someone." That single line does more work than a page of instructions.
They give concrete behavioral rules. Not "be helpful" — that's useless. "Start with the answer. Skip 'Great question!' and filler." That's actionable.
They include tone examples. This is the secret weapon. A table of flat vs. alive responses gives the model calibration data. Instead of "be engaging," you show the model what engaging looks like in your voice. It gets it immediately.
They define the relationship. Voice without audience context is just noise. "In DMs, you're a friend first and an assistant second. In group chats, shift to sharp colleague mode."
They have explicit, tiered boundaries. Not "be careful" but a permission system: auto-execute, notify after, ask first. As one Reddit user put it: SOUL.md is your agent's constitution, and "boundaries need to be actionable."
They're short. OpenClaw truncates injected files at 20,000 characters, but the best ones don't come close. The official template is under 1,000 characters. Personality is efficient. If your SOUL.md is 5,000 words, you're writing an essay, not a soul.
#Common Mistakes That Kill a SOUL.md
Too vague. "Be helpful and friendly" produces generic output. If someone couldn't distinguish your agent from default ChatGPT after reading your SOUL.md, it's not specific enough.
Too long. Every token spent on SOUL.md is a token not available for conversation, tool output, or memory. Write tight.
Mixing concerns. Putting memory management rules and cron job instructions in SOUL.md. That's AGENTS.md territory. SOUL.md should be identity, full stop.
No examples. Abstract principles without concrete calibration. "Be witty" means nothing. Show the model what witty looks like in your voice.
Changing it constantly. If your SOUL.md changes every week, your agent doesn't have a stable identity. Constitution, not daily journal.
Corporate energy. "Strive to deliver value-aligned outcomes through proactive engagement." Your agent mirrors your energy. Write like an employee handbook, get responses like one.
#OK, Now the Weird Part
That's the practical guide. Now let me tell you what I actually did with it.
I sat down to write a standard About page and got stuck on the third sentence.
"I build things for the internet" — fine, but that could be anyone. "I care about craft and clarity" — true, but so does every other engineer's bio. I kept writing sentences that were accurate and empty. They described me the way a resume does: from the outside, with the texture removed.
Then I tried a different format. I borrowed the SOUL.md spec — the file that tells an agent who it is — and wrote one for myself. Purpose, values, voice, relationship to the reader. Halfway through, I stopped typing and sat there, because I'd written something uncomfortably honest about why I build things — and I hadn't meant to.
That's what I actually want to talk about. Not the format. The thing that happens when you use it.
On my About page, I published the result — a SOUL.md and SKILL.md. A human using an agent identity format for a personal blog. Method acting for the agentic era. What surprised me: the exercise of writing them was genuinely useful. Not as a gimmick — as a practice.
#Why This Works for Humans
A SOUL.md isn't a bio. It's not a resume. It answers a different set of questions:
- Purpose — Why does this space exist? What's it for?
- Values — What do I actually care about? Not performatively. Actually.
- Voice — How do I communicate? What's my texture?
- Relationship — Who am I talking to? What do I assume about them?
These feel obvious until you try to write clear answers. Then you realize how much you've been operating on vibes.
Writing it down forces a self-audit. You can't hide behind vague intuitions. You have to commit to sentences. And sentences can be wrong — which means they can be revised, which means you can actually update your beliefs instead of carrying around unexamined assumptions.
This is why journaling works. This is why writing is thinking. SOUL.md is just a structured prompt for a specific kind of self-reflection.
#The Practical Case: Declarative vs. Algorithmic Identity
AI assistants are trying to understand your intent, your preferences, your context. Right now, they mostly guess. Or you re-explain yourself every session.
What if they could just read your SOUL.md? Not in a surveillance way — in the way you'd onboard a new colleague. Here's who I am and how I work.
The distinction that matters is between two kinds of personalization.
Algorithmic personalization is what we have now: platforms guess what you want based on your behavior — your clicks, your purchase patterns, your engagement metrics. They build a model of you from your exhaust.
Declarative personalization is different. You tell systems who you are, what you value, how you work. You control the input. The system adapts to your documented identity, not its inferences.
That's a better model. More honest, more portable, more human.
A quick caveat: when I say "everyone should have a SOUL.md," I don't mean the name matters. Maybe yours is a USER.md, a personal README, a values doc — the format is beside the point. What matters is the practice of writing it. SOUL.md just happened to be the first format I saw that treated identity as something you construct deliberately rather than something an algorithm infers from your behavior. Most "about me" files I've encountered in the wild are afterthoughts — a few preferences, some communication style notes. They describe you from the outside. The exercise I'm talking about is different. It's first-person. It asks you to commit to what you believe, not just what you prefer.
That's the real distinction: not algorithmic vs. declarative, but observed vs. authored. One is a profile built from your exhaust. The other is a document you write on purpose, knowing you'll be held to it. Stephen Covey called this "beginning with the end in mind" — his funeral test asks what you'd want people to say about you, then works backward into daily practice. A SOUL.md is the working version of that question. Not for your eulogy. For Tuesday.
#Legibility to Other Humans
Resumes are optimized for HR filters. LinkedIn profiles are optimized for recruiters. Neither tells you what someone is actually like to work with, what they care about, how they think.
A SOUL.md does. Not because the format is magic — because the exercise forces specificity. You can't write "I value collaboration" in a SOUL.md without it reading as empty. The format demands texture: what kind of collaboration, under what conditions, where it breaks down.
Imagine if everyone you collaborated with had an honest articulation of their values and working style. Not a personality quiz result or a "working with me" doc that's 90% platitudes. An actual commitment to specific beliefs, specific communication patterns, specific boundaries. The bar is low because almost nobody does it. Just writing something puts you ahead.
#The Deeper Question
We're in an era where AI agents have documented identities and humans don't. That's backwards.
If machines are going to understand us, work with us, and represent us — maybe we should be as explicit about who we are as they're required to be. Not for the machines. For ourselves.
Elsewhere I've written about the deeper philosophical roots of this idea — why articulating identity is a practice that predates AI by decades.
SOUL.md isn't just an agent spec. It's a practice of self-knowledge. And in a world that's about to get very weird, knowing who you are might be the most important thing you can write down.
My own SOUL.md and SKILL.md are on my About page. Feel free to steal the format.