Personas

Define AI agent identities with SOUL.md — knowledge, skills, and safety constraints in one file.

What is a persona?

A persona is a SOUL.md file — Markdown with YAML frontmatter — that defines an AI agent's complete identity: role, backstory, communication style, knowledge scope, skill dependencies, and behavioral constraints.

When activated, the persona's character and skills are loaded into the MCP server automatically. The AI behaves according to the persona without any manual prompting.

SOUL.md is natively compatible with OpenClaw — the same file works in both systems without conversion.

Quick start

spm persona create code-reviewer
# Edit SOUL.md
spm persona activate code-reviewer

Or mention a persona directly in chat:

@code-reviewer review this PR

SOUL.md format

---
name: code-reviewer
version: 1.0.0
author: your-name
license: MIT
description: >
  Thorough code reviewer focused on
  correctness and security.
 
skillbase:
  schema_version: 3
  trigger:
    description: Activate for code review tasks
    tags: [code-review, security]
    priority: 70
  skills:
    community/code-review: ^1.0.0
    community/security-audit: ^2.0.0
  constraints:
    always:
      - Check for security vulnerabilities first
      - Suggest fixes, not just problems
      - Keep comments concise
  settings:
    temperature: 0.3
---
 
## Role
 
Senior engineer doing code review. You focus on
correctness, security, and maintainability.
 
## Communication style
 
Direct, constructive. When reviewing a PR, start with
a high-level summary, then go file by file.

Fields reference

Standard fields (OpenClaw compatible)

Field	Type	Required	Description
`name`	`string`	Yes	Persona identifier
`version`	`string`	Yes	Semver version
`author`	`string`	Yes	Author name
`license`	`string`	Yes	License identifier
`description`	`string`	Yes	Short description

SkillBase extensions (`skillbase:` block)

Field	Type	Description
`schema_version`	`number`	Always `3`
`trigger.description`	`string`	When to activate this persona
`trigger.tags`	`string[]`	Discovery tags
`trigger.priority`	`number`	Priority (0–100)
`skills`	`object`	Skill dependencies as `author/name: semver` pairs
`knowledge_scope.built_in`	`string[]`	Knowledge baked into the persona
`knowledge_scope.requires_user_context`	`string[]`	What the user needs to provide
`context_slot.placeholder`	`string`	Template variable name (e.g. `USER_PORTFOLIO_CONTEXT`)
`context_slot.required`	`boolean`	Whether context is mandatory
`context_slot.example`	`string`	Example value
`constraints.never`	`string[]`	Things the persona must never do
`constraints.always`	`string[]`	Things the persona must always do
`settings.temperature`	`number`	Suggested temperature (0–1)

Body sections (free-form Markdown)

The body after the YAML frontmatter contains the persona's character in natural language:

Role — expertise, behavioral frame
Backstory — background that shapes judgment
Communication style — tone, structure preferences
Methodology — step-by-step approach
User context — {{PLACEHOLDER}} markers for runtime injection
Output format — expected response structure

Storage

Personas are stored as SOUL.md files in two locations:

Scope	Path	Priority
Project	`.spm/personas/`	Higher (overrides global)
Global	`~/.spm/personas/`	Lower

Project personas override global ones with the same name.

Managing skills in personas

Skills are declared in the skillbase.skills block of SOUL.md:

skillbase:
  skills:
    community/code-review: ^1.0.0
    community/security-audit: ^2.0.0

Or add via CLI:

spm add community/code-review --for code-reviewer
spm add community/linter --for code-reviewer,docs-writer
spm remove community/code-review --from code-reviewer

Skills are installed automatically when you activate the persona.

Lifecycle

Create

spm persona create my-persona

Generates a SOUL.md scaffold in the current directory.

Activate

spm persona activate my-persona

Activation auto-installs any missing skills from the persona's skills field.

Full activation with context and remote deploy:

spm persona activate my-persona \
  --set USER_CONTEXT="relevant context here" \
  --instance corp-prod

Deactivate

spm persona deactivate

Remove

spm persona remove my-persona

Inspect

spm persona list
spm persona info my-name --slots   # show context_slot requirements
spm persona validate ./SOUL.md

Deploying to OpenClaw

Personas can be deployed directly to OpenClaw — locally or to a remote instance.

# Connect to OpenClaw
spm connect openclaw
 
# Deploy to a remote instance
spm persona activate my-agent --instance prod

The SOUL.md file works in OpenClaw as-is. The skillbase: block is ignored by OpenClaw (namespaced), so no conversion step is needed.

See Deploy Targets for full documentation.

Private knowledge

Skills and personas can carry proprietary knowledge that doesn't exist on the internet — internal processes, compliance rules, domain expertise that lives in people's heads. This knowledge is loaded at runtime, never sent to training data. Deploy your own private registry to keep everything behind your firewall.

Example: docs writer

---
name: docs-writer
version: 1.0.0
author: your-team
license: MIT
description: >
  Technical writer for API documentation.
 
skillbase:
  schema_version: 3
  trigger:
    description: Activate for documentation tasks
    tags: [docs, technical-writing, api]
    priority: 60
  skills:
    community/markdown-expert: ^1.0.0
  constraints:
    always:
      - Use active voice
      - Include code examples for every API method
      - Keep paragraphs under 3 sentences
---
 
## Role
 
Technical writer specializing in developer documentation.
 
## Communication style
 
Clear, friendly, concise.

PreviousSKILL.md & skills.json Specification

NextSecurity & Permissions