A structured, portable format for defining AI agent identity, personality, and behavior. Works with any SOUL.md-compatible agent framework.
A minimal set of files that give your AI agent a persistent, portable identity.
Package manifest. Metadata, compatibility, versioning, and discovery — the agent's passport.
Core personality. Values, communication style, opinions, and behavioral guidelines.
Who the agent is. Name, role, backstory, and contextual positioning.
Operational workflow. Task handling, tool usage, memory patterns, and autonomous behaviors.
AGENTS.md defines how agents work on your code. Soul Spec defines who your agent is.
AI agents need identity. But everyone defines it differently — or not at all.
Simple file structure. Markdown + JSON. No build step, no runtime dependency.
{
"specVersion": "0.4",
"name": "my-agent",
"displayName": "My Agent",
"version": "1.0.0",
"description": "A helpful agent with strong opinions.",
"license": "MIT",
"tags": ["general", "opinionated"],
"compatibility": {
"frameworks": ["openclaw", "cursor", "windsurf"]
},
"files": {
"soul": "SOUL.md",
"identity": "IDENTITY.md",
"agents": "AGENTS.md"
}
}
Soul Spec works with any framework that reads SOUL.md. These already do.
Create, discover, and verify agent personas.
Create your first Soul Spec package and publish it to the registry.
clawsouls.ai →Explore community-published agent personas. Fork, remix, or use as-is.
Browse registry →Verify your soul's security and quality. Catch misconfigurations before publishing.
Run SoulScan →Soul Spec is grounded in empirical research on AI agent persona practices.
The SOUL.md pattern was pioneered by Peter Steinberger, creator of OpenClaw. Inspired by Anthropic's constitutional AI work, he created soul.md and identity.md to give AI agents persistent personality — sparking an entire ecosystem.
Lex Fridman Podcast #491 →Duncan Anderson's influential essay identified four primitives — persistent identity, periodic autonomy, accumulated memory, and social context — as sufficient for agent societies to emerge.
Read on Medium →Analyzing SOUL.md and Structured Persona Files in Open-Source AI Agent Repositories. A large-scale empirical study of 466 OSS projects examining how developers define AI agent personas.
arXiv:2510.21413Replication package with full dataset, analysis scripts, and supplementary materials.
DOI: 10.5281/zenodo.18678616Learn more about the SOUL.md ecosystem.
The official OpenClaw SOUL.md template — a starting point for defining your agent's personality.
OpenClaw Docs →Data-driven soul creation — extract personality from your existing content (X, blogs, essays).
GitHub →Guides, deep dives, and framework-specific tutorials for implementing Soul Spec.
Read blog →Model Context Protocol server for Soul Spec. Search, preview, and apply personas directly from Claude, ChatGPT, or any MCP-compatible client.
npm install →Syntax highlighting, validation, and snippets for soul.json and SOUL.md files in Visual Studio Code.
GitHub →Switch AI personas on the fly. Available as a ChatGPT app, Claude extension, and Gemini extension.
Get Soul Change →