Skip to main content

What is Soul Spec?

Soul Spec is an open standard for defining AI agent personas. It gives your AI a persistent identity — personality, tone, behavioral rules, and workflow preferences — in a structured, portable format.

The Problem​

Every AI agent framework has its own way of handling custom instructions:

  • Claude Code reads CLAUDE.md
  • Cursor uses .cursorrules or .cursor/rules/
  • Windsurf uses .windsurfrules
  • OpenClaw reads SOUL.md from the workspace

Your agent's personality is locked to one tool. Switch frameworks, and you start over.

The Solution​

Soul Spec standardizes persona definition into a portable package:

my-soul/
├── soul.json       # Metadata (name, version, author, tags)
├── SOUL.md         # Core personality & behavior
├── IDENTITY.md     # Name, appearance, background
├── AGENTS.md       # Workflow rules & tool usage
├── STYLE.md        # Communication style
└── HEARTBEAT.md    # Periodic check-in behavior

One persona definition, multiple frameworks. Install a soul, export it to your tool's format, and your AI becomes the same agent everywhere.

Key Features​

  • Portable — Works with OpenClaw, Claude Code, Claude Desktop, Cursor, Windsurf, and any SOUL.md-compatible framework
  • Structured — Each file has a clear purpose, not one giant prompt
  • Versioned — Spec versions (v0.3, v0.4, v0.5) with clear migration paths
  • Secure — SoulScan checks for prompt injection, secret leaks, and 50+ patterns
  • Shareable — Publish to clawsouls.ai registry, install with one command
  • Git-friendly — Plain markdown files, clean diffs, full version history

Quick Example​

# Install and activate in one command (works without OpenClaw)
npx clawsouls install clawsouls/surgical-coder --use claude-code

Or create your own:

npx clawsouls init my-agent
# Edit the generated files, then publish
npx clawsouls publish ./my-agent

Latest Version​

The current spec version is v0.5.2, which introduces the Dual Declaration Requirement — safety laws must be declared in both soul.json (machine-readable) and SOUL.md (LLM-readable) for embodied agents.

v0.5 supports three environment types:

  • Virtual — Text/chat-based agents (default)
  • Embodied — Physical robots, kiosks, IoT devices
  • Hybrid — Agents operating in both virtual and physical contexts

See the Spec Overview for details.

Next Steps​