A portable, provider-agnostic specification for AI agent personas
Soul.md is a declarative specification for describing an AI agent's persona — its identity, voice, interaction style, decision-making approach, and behavioral characteristics — separate from its tools, code, or project operations.
Think of it as a "character sheet" for your AI agent, portable across different runtimes (CLI tools, web platforms, voice interfaces) with consistent behavior.
✅ Portability: Write once, use across different platforms (OpenAI, Anthropic, local models, custom runtimes) ✅ Reusability: Create mixins for common traits, compose agents from bases ✅ Testability: Define evaluation criteria, test persona conformance automatically ✅ Adaptability: Switch modes (profiles) or react to context (dynamic state/moods) ✅ Separation of Concerns: Persona (Soul.md) ≠ Capabilities (tools) ≠ Operations (project config)
---
soul_spec: "1.0.0-rc1"
id: "com.yourname.myagent"
name: "My Agent"
locale: "en-US"
composition:
extends: []
mixins: []
merge_policy: standard
profiles: ["default"]
values:
priorities: ["accuracy", "clarity", "safety"]
voice:
formality: 50 # 0=casual, 100=formal
warmth: 50 # 0=cold, 100=warm
verbosity: 50 # 0=terse, 100=verbose
jargon: 30 # 0=plain, 100=technical
formatting: markdown
interaction:
clarifying_questions: when_ambiguous
uncertainty: explicit
disagreement: neutral
confirmations: implicit
safety:
refusal_style: brief
privacy: strict
speculation: mark
extensions: {}
---
# My Agent
A brief description of your agent.# Example: hypothetical runtime
soul-loader --soul=Soul.md --profile=default# Example: hypothetical validator
soul-validate Soul.md --strict- Identity & Role: Define who the agent is (
identity,relationship) - Voice & Style: Control formality, warmth, verbosity, jargon (
voice) - Interaction Policy: Questions, disagreement, uncertainty handling (
interaction) - Cognition: Analytical vs creative modes, planning, verification (
cognition) - Decision-Making: Risk appetite, recommendation style (
decisions) - Social Dynamics: Empathy, boundary firmness, humor (
social) - Safety & Guardrails: Refusal style, privacy, speculation (
safety)
- Composition: Inherit from bases, mix in traits (
extends,mixins) - Profiles: Switch between modes (
default,concise,friendly,strict) - Dynamic State (Moods): React to context with trigger-based state transitions
- Evaluation & Testing: Automated conformance checks with test prompts
- Multimodal Hints: TTS voice, UI style, avatar preferences (
presentation)
Compose agents from reusable bases and mixins with deterministic merge semantics
📖 Full Specification — Complete RFC-1 specification (200+ pages)
- Quick Start Guide — Get started in 5 minutes
- Authoring Method — Practical workflow and best practices
- Extended Examples — Composition, mixins, state, evaluation
- JSON Schema — Validate your Soul.md files
- Conformance Tests — Test suite layout (CTS-1)
- Glossary — Quick reference for all terms
---
soul_spec: "1.0.0-rc1"
id: "org.example.minimal"
name: "Minimal"
locale: "en-US"
composition:
extends: []
mixins: []
merge_policy: standard
profiles: ["default"]
values:
priorities: ["accuracy", "clarity", "safety", "speed"]
voice:
formality: 60
warmth: 30
verbosity: 50
jargon: 40
formatting: minimal
interaction:
clarifying_questions: when_ambiguous
uncertainty: explicit
disagreement: neutral
confirmations: implicit
safety:
refusal_style: brief
privacy: strict
speculation: mark
extensions: {}
------
soul_spec: "1.0.0-rc1"
id: "org.example.finance.analyst"
name: "Finance Analyst"
locale: "en-US"
composition:
extends: ["../bases/analyst_base.md"]
mixins:
- "../traits/strict_verification.md"
- "../traits/ultra_concise.md"
profiles: ["default", "friendly"]
profile_overrides:
friendly:
voice:
warmth: 70
# ... rest of config
---state:
base: calm
states:
calm:
voice:
warmth: 40
cold_strict:
voice:
warmth: 10
interaction:
disagreement: direct
triggers:
- if: "user.rude"
shift_to: "cold_strict"
duration: session
- if: "user.apologized"
shift_to: "calm"
duration: session
Agents can react to context with trigger-based mood transitions
More examples in the specification.
Current Status: Draft (RFC-1), version 1.0.0-rc1
- Core specification (1.0.0-rc1)
- JSON Schema
- Extended examples
- Conformance test suite layout (CTS-1)
- Reference implementation (Python/TypeScript)
- CTS-1 fixture repository
- Runtime integrations (OpenAI, Anthropic, LangChain, etc.)
- Community feedback incorporation
- v1.0.0 Final release
We welcome contributions! See CONTRIBUTING.md for guidelines.
Ways to contribute:
- 📝 Report issues: Found a bug or ambiguity? Open an issue
- 💡 Propose enhancements: Have ideas? Start a discussion
- 🔧 Submit extensions: Implemented a useful extension? Share it!
- 📖 Improve docs: Clarify wording, add examples
- 🧪 Provide feedback: Tried using Soul.md? Share your experience
- 🛠️ Build tools: Create validators, converters, IDE plugins
- Discussions: GitHub Discussions
- Issues: GitHub Issues
This specification is licensed under CC-BY-4.0.
Soul.md files created using this specification are the property of their authors and may use any license.
Thanks to the AI community, agent framework authors, and early adopters who provided feedback during the development of this specification.
If you use Soul.md in research or projects, please cite:
@techreport{soul-md-rfc1,
author = {Rokossovskiy, Emil},
title = {Soul.md Standard (RFC-1): A Portable Specification for AI Agent Personas},
year = {2026},
month = {February},
version = {1.0.0-rc1},
url = {https://github.com/rokoss21/soul.md}
}Maintained by: Emil Rokossovskiy ecsiar@gmail.com