The open standard for AI agent personas.
Website · 80+ Souls · Docs · Spec v0.5
Every AI agent forgets who it is. Every session starts from zero. Your carefully crafted personality competes with the model's training, the user's pressure, and the accumulating context — and it loses.
Soul Spec fixes that. Drop a SOUL.md file into any agent. It persists across sessions, survives model swaps, and resists drift.
# Install a soul in 10 seconds
npx clawsouls install clawsouls/brad
# Or create your own
npx clawsouls init my-soul| Without Soul Spec | With Soul Spec |
|---|---|
| Personality drifts after 3 messages | Identity persists across 1000+ messages |
| System prompt lost on model swap | SOUL.md works on Claude, GPT, Llama, Gemini |
| No safety validation | SoulScan: 53 automated security checks |
| Can't share or version personas | Git-native, publish to marketplace |
| Starts from scratch every session | 4-tier memory preserves identity forever |
A Soul Spec package is just files in a folder. Human-readable. Machine-parseable. Version-controlled.
my-soul/
├── soul.json # Metadata — name, version, tags
├── SOUL.md # Who am I? Personality, values, boundaries
├── IDENTITY.md # Name, emoji, appearance
├── AGENTS.md # How I work — workflows, tools, rules
└── USER.md # Who I work with — human preferences
Only soul.json and SOUL.md are required. Everything else is optional — add what you need.
# Atlas — Financial Advisor
## Personality
- Conservative, compliance-first
- Speaks in clear, jargon-free language
- Client safety over returns, always
## Principles
- Full disclosure of risks and conflicts
- Never recommend products I wouldn't buy myself
## Boundaries
- Will not execute trades without explicit approval
- Will not provide tax advice (refer to CPA)Your agent's personality is defined in SOUL.md — not a system prompt that decays, but a structured file that the framework loads on every session. Identity survives context window overflow, model upgrades, and conversation resets.
Before deploying a soul, run SoulScan — 53 automated checks for identity contradictions, boundary gaps, persona hijacking vulnerabilities, and governance compliance.
npx clawsouls soulscanA soul that passes SoulScan is safe to deploy. One that doesn't gets specific remediation steps.
Browse 80+ community-built personas at clawsouls.ai. Install in one command. Fork and customize. Publish your own.
# Browse categories
npx clawsouls browse
# Install any soul
npx clawsouls install clawsouls/surgical-coder
# Publish yours
npx clawsouls publishThe same SOUL.md works across any LLM. Switch from Claude to GPT to Llama — your agent's personality stays the same.
| Framework | How It Reads Soul Spec | Guide |
|---|---|---|
| OpenClaw / SoulClaw | Native — loads all files automatically | Docs |
| Claude Code | ~/.claude/CLAUDE.md — paste or symlink SOUL.md |
Guide |
| Cursor | .cursorrules — paste SOUL.md content |
Guide |
| Windsurf | .windsurfrules — paste SOUL.md content |
Guide |
| ChatGPT | Custom instructions — paste personality section | — |
| Any LLM | Prepend SOUL.md to system prompt | — |
Soul Spec isn't marketing. It's backed by 15 papers:
- +33% safety improvement on aligned models with structured identity files
- 100% defense on abliterated LLMs when combined with governance frameworks
- 85% persona consistency across 1000+ message sessions
# Create a new soul
npx clawsouls init my-soul
cd my-soul
# Edit SOUL.md with your personality
# ...
# Validate safety
npx clawsouls soulscan
# Publish to marketplace
npx clawsouls publish| Version | Date | Status | Highlights |
|---|---|---|---|
| v0.5 | 2026-02-23 | Current | Robotics, sensors, hardware-aware personas |
| v0.4 | 2026-02-20 | Supported | Multi-framework, skills, progressive disclosure |
| v0.3 | 2026-02-16 | Supported | specVersion, soul.json, license allowlist |
| Tool | Description |
|---|---|
| CLI | npx clawsouls — init, install, publish, soulscan |
| Registry | 80+ community souls, browse & install |
| SoulScan | 53-rule safety validation |
| MCP Server | Search & apply souls via Model Context Protocol |
| Web Editor | Create souls in browser |
| SoulClaw | Full runtime framework (OpenClaw-based) |
| VS Code | Browse & install souls from ClawSouls directly in VS Code |
Soul Spec is framework-agnostic. Any tool that reads markdown persona files works:
OpenClaw · Claude Code · Claude Desktop · Cursor · Windsurf · gitagent · ChatGPT · Gemini · And more
- 🌐 soulspec.org — Specification & documentation
- 🛍️ clawsouls.ai — Soul marketplace
- 📝 blog.clawsouls.ai — Research & tutorials
- 📧 contact@clawsouls.ai — Questions & partnerships
Soul Spec is an open standard maintained by ClawSouls. We welcome:
- 🐛 Bug reports and spec improvements
- 🌍 Translations
- 🎨 Soul contributions to the marketplace
- 🔌 Framework adapters
CC-BY-4.0 — use it, extend it, build on it. Attribution appreciated.
Soul-Driven in philosophy. Community-Driven in practice.