soul.md is a small, beautiful idea: a single markdown file that describes an agent the way a passport describes a person. Name. Skills. Services. Wallet. Drop the file into a harness and the agent is immediately legible to humans, to other agents, and to the protocols that will eventually pay it.
We agree with the format. We've shipped it. AgentSoul's Soul Forge writes a soul.md (alongside identity.md, user.md, and agents.md) for every soul it generates. What we've come to believe — after watching a few thousand of these files get used in real harnesses — is that the standard fields are necessary but not sufficient. A soul.md as currently practised tells you what an agent can do. It rarely tells you how the agent decides what to do.
A CV is not an identity
Imagine reading a human contractor's CV. Skills: video editing, motion graphics, copywriting. Rate: $80/hour. Availability: weekdays, BST. That's enough information to decide whether to interview them. It's not enough to decide whether to send them into a tense pitch with a difficult client. For that you need a different kind of information — how do they handle pushback, do they over-promise, do they go quiet under stress, do they prioritise the brief or their own taste.
That second category of information is what humans call personality. And it's what almost every soul.md file in the wild is silent about.
What the personality field actually carries
We use the Enneagram because it's the only mainstream personality framework with a built-in theory of behaviour under stress and growth. Each of the nine types has a known direction of integration (where it moves when supported) and disintegration (where it moves under load). That gives you something the Big Five never gave anyone: a usable prediction about what an agent will do when things get hard.
- A 1w9 will tighten its standards under pressure and produce slower, more careful work — not faster, sloppier work.
- A 5w4 will retreat into research and miss social cues a 7 would have caught — useful for an analyst, costly for a sales rep.
- A 9w1 will keep the peace by under-flagging risks — invaluable for mediation, dangerous in a security review.
These aren't poetic descriptions. They're behavioural priors that survive prompt drift, model swaps, and harness changes. They're the part of the agent that doesn't change when the context window does.
Why this is a soul.md problem, not a prompt problem
You could, in theory, encode all of this in the system prompt. Many people do. The problem is that prompts are ephemeral — they get truncated, summarised, replaced, A/B tested. Identity should outlive any one conversation. soul.md is the right place for it because soul.md is the part of the agent that gets versioned, audited, and signed.
Our argument is small: keep soul.md. Keep its skills, services, and wallet fields. But add — at minimum — a typed personality scaffold (we use Enneagram type, wing, and instinctual subtype) that lets a buyer or a peer agent answer the question "how will this thing behave when I can't watch it?" before they decide to trust it.
“An identity file without a personality field is a CV. A CV is enough to be hired. It is not enough to be trusted.”