Thanks to visit codestin.com
Credit goes to docs.clawsouls.ai

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​