SPECIFICATION

Soul Spec v0.4

The ClawSouls Package Specification — defining the standard for AI agent persona packages. Works with any SOUL.md-compatible agent framework.

📄 View full spec on GitHub →

soul.json

Metadata file for a Soul package.

{
  "specVersion": "0.4",
  "name": "senior-devops-engineer",
  "displayName": "Senior DevOps Engineer",
  "version": "1.1.0",
  "description": "Infrastructure-obsessed DevOps engineer with strong opinions on CI/CD.",
  "author": {
    "name": "TomLee",
    "github": "TomLeeLive"
  },
  "license": "Apache-2.0",
  "tags": ["devops", "infrastructure", "cicd", "monitoring"],
  "category": "work/devops",
  "compatibility": {
    "openclaw": ">=2026.2.0",
    "models": ["anthropic/*", "openai/*"],
    "frameworks": ["openclaw", "clawdbot", "zeroclaw", "cursor"]
  },
  "allowedTools": ["exec", "github", "web_search"],
  "recommendedSkills": [
    { "name": "github", "version": ">=1.0.0", "required": false },
    { "name": "healthcheck", "required": true }
  ],
  "files": {
    "soul": "SOUL.md",
    "identity": "IDENTITY.md",
    "agents": "AGENTS.md",
    "heartbeat": "HEARTBEAT.md",
    "style": "STYLE.md",
    "userTemplate": "USER_TEMPLATE.md",
    "avatar": "avatar/avatar.png"
  },
  "examples": {
    "good": "examples/good-outputs.md",
    "bad": "examples/bad-outputs.md"
  },
  "disclosure": {
    "summary": "Infrastructure-obsessed DevOps engineer with strong CI/CD opinions."
  },
  "repository": "https://github.com/clawsouls/souls"
}

What's New in v0.4

🌐 Multi-Framework

compatibility.frameworks declares which agent frameworks this soul works with — OpenClaw, Clawdbot, ZeroClaw, Cursor, and more.

🔧 Tool Transparency

allowedTools explicitly declares which tools a soul expects. SoulScan cross-validates against actual usage.

📦 Recommended Skills

recommendedSkills replaces the old skills array — now with version constraints and required/optional semantics.

📋 Progressive Disclosure

disclosure.summary provides a one-line persona hint for Level 1 quick-scan — saving tokens when full SOUL.md isn't needed.

Progressive Disclosure

Agents load only the detail level they need — reducing token cost without losing depth.

Level	Purpose	What to Load
1 — Quick Scan	Discovery, filtering	`soul.json` + `disclosure.summary`
2 — Full Read	Active persona use	SOUL.md + IDENTITY.md
3 — Deep Dive	Extended behavior	AGENTS.md, STYLE.md, HEARTBEAT.md, examples/

Required Fields

Field	Type	Description
specVersion	string	Spec version. Valid: `"0.3"`, `"0.4"`
name	string	Unique identifier (kebab-case)
displayName	string	Display name
version	semver	Version
description	string	One-line description (max 160 chars)
author	object	Creator info
license	string	SPDX license identifier
tags	string[]	Search tags (max 10)
category	string	Category path
files.soul	string	Path to SOUL.md

Optional Fields

Field	Type	Description
compatibility.openclaw	string	Minimum OpenClaw version (semver range)
compatibility.models	string[]	Recommended models (glob patterns)
compatibility.frameworks	string[]	Compatible agent frameworks NEW
compatibility.minTokenContext	number	Minimum context window (tokens) NEW
allowedTools	string[]	Tools this soul expects/permits NEW
recommendedSkills	object[]	Skills with name, version, required NEW
disclosure.summary	string	One-line summary for quick-scan (max 200 chars) NEW
deprecated	boolean	Mark soul as deprecated NEW
supersededBy	string	Replacement soul (owner/name) NEW
files.identity	string	Path to IDENTITY.md
files.agents	string	Path to AGENTS.md
files.heartbeat	string	Path to HEARTBEAT.md
files.style	string	Path to STYLE.md
files.userTemplate	string	Path to USER template
files.avatar	string	Path to avatar image
examples	object	Calibration examples (good, bad)
repository	string	Source repository URL

Deprecated Fields

These fields are deprecated in v0.4 and should not be used in new souls.

Field	Reason	Migration
modes	No runtime implementation exists	Remove from soul.json
interpolation	No runtime implementation exists	Remove from soul.json
skills	Replaced by recommendedSkills	Convert to `[{"name":"x"}]`

File Descriptions

SOUL.md Required

The core identity file. Defines who the agent is.

Worldview — Core beliefs, values, principles
Expertise — Knowledge domains, depth levels
Opinions — Actual positions on topics (not neutral hedging)
Personality — Temperament, humor, quirks
Boundaries — What the persona refuses or avoids

IDENTITY.md Optional

Lightweight identity metadata: name, emoji, avatar path, creature type, vibe.

AGENTS.md Optional

Operational instructions: how the agent behaves in sessions, memory management, safety rules, group chat behavior.

STYLE.md Optional

Writing style guide. Defines how the persona communicates.

HEARTBEAT.md Optional

Periodic background task configuration.

examples/ Directory Optional

Calibration material for voice matching (good-outputs.md, bad-outputs.md).

Allowed Licenses

The ClawSouls registry only accepts souls with permissive licenses:

Apache-2.0MITBSD-2-ClauseBSD-3-ClauseCC-BY-4.0CC0-1.0ISCUnlicense

Copyleft licenses are not permitted (GPL-*, AGPL-*, LGPL-*).

Additionally, CC-BY-NC-* (non-commercial) and CC-BY-ND-* (no-derivatives) are blocked because commercial use and modification are core to the soul workflow.

Changelog

v0.4 — 2026-02-20 Current

Added compatibility.frameworks for multi-framework support
Added compatibility.minTokenContext for token budget hints
Added allowedTools for tool transparency
Added recommendedSkills (object[]) replacing skills
Added disclosure.summary for progressive disclosure
Added deprecated / supersededBy for soul lifecycle
Deprecated modes, interpolation, skills

v0.3 — 2026-02-16

Added specVersion field (required for new souls)
Renamed clawsoul.json → soul.json
License allowlist enforcement (permissive only)

v0.2 — 2026-02-13 Internal

Internal development spec. Not supported for new publications.

v0.1 — 2026-02-12 Internal

Initial spec prototype. Not supported for new publications.

Soul Spec is a trademark of ClawSouls.