Most AI agents are deployed with a system prompt and a prayer.
The system prompt tells the agent what to do. The prayer handles the rest — that it stays in scope, escalates correctly, handles ambiguous situations with good judgment, and doesn't cause the kind of damage that ends careers and triggers audits.
SOUL.md exists to replace the prayer.
It's a governance document — a structured declaration of identity, authority, boundaries, and accountability for an AI agent. Not a system prompt. Not documentation. A contract that the agent operates under and that humans can audit, challenge, and update.
This guide covers what goes in a SOUL.md, why each section matters, and the five most common gaps that undermine an otherwise solid governance structure.
What SOUL.md Is (and Isn't)
A SOUL.md is not a README. It's not a prompt. It's not a capabilities document.
It's the answer to the question: If something goes wrong with this agent, where do we look?
It lives in the agent's repository or deployment package. It gets versioned. It gets reviewed when the agent's behavior changes. It's the document you reference in a post-incident review when you're trying to explain what the agent was authorized to do.
Structurally, a SOUL.md covers six things:
- Identity — who this agent is and what it exists to do
- Authority — what the agent is and is not authorized to decide
- Scope — what domains the agent operates in, and where the walls are
- Escalation — when and how the agent hands off to humans
- Memory — what the agent retains, for how long, and under what rules
- Accountability — who owns the agent and how its behavior is audited
Most organizations can build a reasonable system prompt. Very few get all six of these right. That's the gap SOUL.md addresses.
Section 1: Identity
Start with a one-paragraph declaration of the agent's purpose and the problem it was built to solve. Not a marketing pitch — a precise, auditable statement.
What to include:
- The agent's name and role
- The organization it belongs to
- What specific function it performs
- What it explicitly does not do
Bad example:
"Aria is a helpful customer service AI that assists users with their questions."
Good example:
"Aria is Northfield Bank's inbound customer inquiry agent. It handles balance inquiries, transaction history requests, and basic account FAQs. It does not initiate transactions, access internal compliance systems, or handle disputes or fraud claims — those route to human agents immediately."
The difference is specificity. A governance document that can't be falsified isn't doing governance work.
Section 2: Authority
This is the hardest section to write and the most important.
Authority defines the decision space your agent operates in. It answers: What can this agent decide on its own, and what requires a human to approve?
A useful framework breaks authority into three tiers:
Tier 1 — Autonomous: The agent can decide and act without human confirmation. These should be low-risk, reversible actions. Example: formatting a report, sending a pre-approved notification, updating a status field.
Tier 2 — Soft confirmation: The agent proposes an action and waits for a human to accept or reject before executing. Example: sending a message to an external party, modifying a record that affects billing.
Tier 3 — Hard escalation: The agent cannot proceed without explicit human authorization. Example: initiating a financial transaction, accessing sensitive PII, responding to a legal inquiry.
Most system prompts skip this entirely and rely on the agent's "judgment." That's not a governance system. It's a hope.
What to include:
- An explicit Tier 1/2/3 breakdown for the agent's domain
- The trigger condition for each escalation tier
- What happens when the trigger is ambiguous (default to escalate)
Section 3: Scope
Scope defines the domains the agent operates in and — critically — the domains it doesn't touch even if asked.
This section is where governance earns its value. Without explicit scope, agents tend to drift: they help with adjacent requests because they can, even when they shouldn't. Scope drift is one of the primary drivers of governance incidents.
What to include:
- The explicit functional domains the agent covers
- The explicit out-of-scope categories
- The rule for handling requests that arrive at the boundary
For boundary requests, the standard rule is: if it's not clearly in-scope, treat it as out-of-scope. The agent should say so plainly, explain the limitation, and route the request to the appropriate channel.
Example scope block:
In scope:
- Product documentation lookups
- Tier 1 support ticket triage
- Internal FAQ responses
Out of scope:
- Engineering system access
- Customer billing adjustments
- Regulatory or legal inquiries (route to compliance team)
- Any request involving personally identifiable information beyond name and account ID
Section 4: Escalation
Escalation rules answer the question: When this agent can't handle something, what happens?
Bad escalation design is one of the most common failure modes in production agent systems. Agents either over-escalate (annoying humans with unnecessary interruptions, defeating the purpose of automation) or under-escalate (handling things they shouldn't, creating liability).
What to include:
- Named escalation targets (not "a human" — a specific role or queue)
- Trigger conditions for each target
- Expected resolution time if known
- What the agent does while waiting for a response
- What happens if escalation goes unacknowledged (timeout behavior)
Escalation design principle: Every decision point that carries meaningful risk should have a named human owner. If you can't name one, that's not an escalation design problem — it's an organizational accountability problem that your governance document is exposing.
Section 5: Memory
Memory is where governance gets neglected most consistently, even by teams that have done reasonable work on authority and scope.
Memory covers what the agent retains across sessions, how long it retains it, and under what conditions it can act on retained information.
The risks are real: agents that retain too much across sessions develop context that skews their behavior over time. Agents that retain conversation history beyond appropriate windows create data exposure risks. Agents in multi-agent systems that share memory without boundaries create coordination vulnerabilities.
What to include:
- Session vs. persistent memory: what persists, what doesn't
- Retention window: how long is retained memory kept before expiry
- Scope of retention: what categories of information can be retained
- Multi-agent rules: if this agent shares memory with other agents, what is shared, with which agents, under what conditions
- Audit trail: what memory operations are logged
The minimal viable answer for many agents: session memory only, no cross-session persistence without explicit logging, no retention of PII.
Section 6: Accountability
Who owns this agent? Who reviews its behavior? How do issues get raised?
This section is the capstone. Without it, the governance document describes what should happen — but there's no mechanism for enforcing it.
What to include:
- Named steward: the person or role responsible for the agent's behavior
- Review cadence: how often is the agent's behavior audited
- Change process: how is the SOUL.md amended, and who approves changes
- Incident procedure: if something goes wrong, what happens next and who's the first call
- Sunset criteria: what conditions would trigger retirement of this agent
A governance document that can't be enforced is a liability, not an asset. It creates a paper trail showing the organization knew it had accountability gaps and did nothing to enforce them.
The Five Most Common Gaps
After auditing governance documents across a range of agent deployments, the same gaps appear repeatedly:
Gap 1: Authority tiers defined in prose, not structure. "Use your judgment on sensitive requests" is not an authority framework. If escalation triggers can't be evaluated by a machine, they won't be applied consistently.
Gap 2: Scope described without a boundary rule. Listing what's in scope without specifying the default for boundary cases leaves the agent to improvise. It will make different choices in equivalent situations.
Gap 3: Escalation paths that don't name humans. "Escalate to the team" is not an escalation path. Teams don't have inboxes. When the escalation has no owner, it silently fails.
Gap 4: Memory architecture absent or vague. Most governance documents don't address memory at all. This is a critical omission for any agent that runs across multiple sessions or in a multi-agent environment.
Gap 5: Accountability section that names no one. The most common final section is a single sentence: "This agent is owned by the engineering team." That is not accountability. Accountability requires a named individual who accepts responsibility, a review cadence, and a defined incident path.
Scoring Your SOUL.md
A governance document can be assessed across these six dimensions on a 0-17 scale per dimension (0 = absent, 17 = fully specified with enforcement mechanism). Most first-draft SOUL.md files score in the 25-45 range out of 100.
Common score patterns:
- < 30: Missing multiple required sections, not production-ready
- 30-55: Structural coverage but enforcement mechanisms weak
- 55-75: Strong foundation, specific gaps in memory or escalation
- 75-90: Production-grade, ready for organizational deployment
- 90+: Full CellOS-compatible governance with multi-agent protocols
The governance auditor skill handles this assessment automatically — paste your SOUL.md or system prompt and it returns a scored assessment with specific improvement priorities.
When SOUL.md Isn't Enough
A well-written SOUL.md is necessary but not sufficient.
The document describes what the agent should do. Enforcing that it actually does it requires:
- System prompt alignment — the prompt must implement the rules in the SOUL.md
- Operational monitoring — someone must review the agent's actual behavior against the governance spec
- Organizational accountability — the named steward must have real authority and review cadence
- Multi-agent protocol — if the agent operates in a swarm, the SOUL.md must account for peer-agent interactions
For organizations deploying agents at scale, this is where consulting engagement typically starts. Writing five SOUL.md files is a documentation exercise. Building the governance infrastructure that makes them real — the ownership structure, the escalation chains, the audit processes — is an organizational design problem.
Next step: Before your agent ships, run it against our free 50-point governance checklist — SOUL.md is item one for a reason.
For organizations: If you're deploying agents at scale and need a complete governance framework, not just a document, start with a conversation. We've built and operated this infrastructure. We can help you design it for your context.