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. SoulSpec 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"
}
}
SoulSpec works with any framework that reads SOUL.md. These already do.
Create, discover, and verify agent personas.
Create your first SoulSpec 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 →SoulSpec 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 →Karpathy's landmark essay argues that LLMs create a new computing paradigm where natural-language prompts replace traditional code — making structured persona files the "source code" of AI agents.
Watch on YC →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.18772585Learn 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 SoulSpec.
Read blog →Model Context Protocol server for SoulSpec. 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 →