1"use strict";(globalThis.webpackChunksoulspec_docs=globalThis.webpackChunksoulspec_docs||[]).push([[3976],{2053(e,s,n){n.r(s),n.d(s,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>o,metadata:()=>r,toc:()=>c});const r=JSON.parse('{"id":"intro","title":"What is Soul Spec?","description":"Soul Spec is an open standard for defining AI agent personas. It gives your AI a persistent identity \u2014 personality, tone, behavioral rules, and workflow preferences \u2014 in a structured, portable format.","source":"@site/docs/intro.md","sourceDirName":".","slug":"/intro","permalink":"/docs/intro","draft":false,"unlisted":false,"editUrl":"https://github.com/clawsouls/soulspec/tree/main/docs/intro.md","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"sidebar_position":1,"slug":"/intro","title":"What is Soul Spec?"},"sidebar":"docsSidebar","next":{"title":"Quick Start","permalink":"/docs/getting-started/quick-start"}}');var i=n(4848),t=n(8453);const o={sidebar_position:1,slug:"/intro",title:"What is Soul Spec?"},l="What is Soul Spec?",a={},c=[{value:"The Problem",id:"the-problem",level:2},{value:"The Solution",id:"the-solution",level:2},{value:"Key Features",id:"key-features",level:2},{value:"Quick Example",id:"quick-example",level:2},{value:"Latest Version",id:"latest-version",level:2},{value:"Next Steps",id:"next-steps",level:2}];function d(e){const s={a:"a",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(s.header,{children:(0,i.jsx)(s.h1,{id:"what-is-soul-spec",children:"What is Soul Spec?"})}),"\n",(0,i.jsxs)(s.p,{children:[(0,i.jsx)(s.strong,{children:"Soul Spec"})," is an open standard for defining AI agent personas. It gives your AI a persistent identity \u2014 personality, tone, behavioral rules, and workflow preferences \u2014 in a structured, portable format."]}),"\n",(0,i.jsx)(s.h2,{id:"the-problem",children:"The Problem"}),"\n",(0,i.jsx)(s.p,{children:"Every AI agent framework has its own way of handling custom instructions:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:["Claude Code reads ",(0,i.jsx)(s.code,{children:"CLAUDE.md"})]}),"\n",(0,i.jsxs)(s.li,{children:["Cursor uses ",(0,i.jsx)(s.code,{children:".cursorrules"})," or ",(0,i.jsx)(s.code,{children:".cursor/rules/"})]}),"\n",(0,i.jsxs)(s.li,{children:["Windsurf uses ",(0,i.jsx)(s.code,{children:".windsurfrules"})]}),"\n",(0,i.jsxs)(s.li,{children:["OpenClaw reads ",(0,i.jsx)(s.code,{children:"SOUL.md"})," from the workspace"]}),"\n"]}),"\n",(0,i.jsx)(s.p,{children:"Your agent's personality is locked to one tool. Switch frameworks, and you start over."}),"\n",(0,i.jsx)(s.h2,{id:"the-solution",children:"The Solution"}),"\n",(0,i.jsx)(s.p,{children:"Soul Spec standardizes persona definition into a portable package:"}),"\n",(0,i.jsx)(s.pre,{children:(0,i.jsx)(s.code,{children:"my-soul/\n\u251c\u2500\u2500 soul.json # Metadata (name, version, author, tags)\n\u251c\u2500\u2500 SOUL.md # Core personality & behavior\n\u251c\u2500\u2500 IDENTITY.md # Name, appearance, background\n\u251c\u2500\u2500 AGENTS.md # Workflow rules & tool usage\n\u251c\u2500\u2500 STYLE.md # Communication style\n\u2514\u2500\u2500 HEARTBEAT.md # Periodic check-in behavior\n"})}),"\n",(0,i.jsx)(s.p,{children:"One persona definition, multiple frameworks. Install a soul, export it to your tool's format, and your AI becomes the same agent everywhere."}),"\n",(0,i.jsx)(s.h2,{id:"key-features",children:"Key Features"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Portable"})," \u2014 Works with OpenClaw, Claude Code, Claude Desktop, Cursor, Windsurf, and any SOUL.md-compatible framework"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Structured"})," \u2014 Each file has a clear purpose, not one giant prompt"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Versioned"})," \u2014 Spec versions (v0.3, v0.4, v0.5) with clear migration paths"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Secure"})," \u2014 SoulScan checks for prompt injection, secret leaks, and 50+ patterns"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Shareable"})," \u2014 Publish to ",(0,i.jsx)(s.a,{href:"https://clawsouls.ai",children:"clawsouls.ai"})," registry, install with one command"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Git-friendly"})," \u2014 Plain markdown files, clean diffs, full version history"]}),"\n"]}
1),"\n",(0,i.jsx)(s.h2,{id:"quick-example",children:"Quick Example"}),"\n",(0,i.jsx)(s.pre,{children:(0,i.jsx)(s.code,{className:"language-bash",children:"# Install and activate in one command (works without OpenClaw)\nnpx clawsouls install clawsouls/surgical-coder --use claude-code\n"})}),"\n",(0,i.jsx)(s.p,{children:"Or create your own:"}),"\n",(0,i.jsx)(s.pre,{children:(0,i.jsx)(s.code,{className:"language-bash",children:"npx clawsouls init my-agent\n# Edit the generated files, then publish\nnpx clawsouls publish ./my-agent\n"})}),"\n",(0,i.jsx)(s.h2,{id:"latest-version",children:"Latest Version"}),"\n",(0,i.jsxs)(s.p,{children:["The current spec version is ",(0,i.jsx)(s.strong,{children:"v0.5.2"}),", which introduces the ",(0,i.jsx)(s.strong,{children:"Dual Declaration Requirement"})," \u2014 safety laws must be declared in both ",(0,i.jsx)(s.code,{children:"soul.json"})," (machine-readable) and ",(0,i.jsx)(s.code,{children:"SOUL.md"})," (LLM-readable) for embodied agents."]}),"\n",(0,i.jsx)(s.p,{children:"v0.5 supports three environment types:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Virtual"})," \u2014 Text/chat-based agents (default)"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Embodied"})," \u2014 Physical robots, kiosks, IoT devices"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Hybrid"})," \u2014 Agents operating in both virtual and physical contexts"]}),"\n"]}),"\n",(0,i.jsxs)(s.p,{children:["See the ",(0,i.jsx)(s.a,{href:"/docs/spec/overview",children:"Spec Overview"})," for details."]}),"\n",(0,i.jsx)(s.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.a,{href:"/docs/getting-started/quick-start",children:"Quick Start"})," \u2014 Get up and running in 5 minutes"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.a,{href:"/docs/spec/overview",children:"Spec Overview"})," \u2014 Understand the spec structure"]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.a,{href:"/docs/guides/openclaw",children:"Framework Guides"})," \u2014 Set up Soul Spec with your tool"]}),"\n"]})]})}function h(e={}){const{wrapper:s}={...(0,t.R)(),...e.components};return s?(0,i.jsx)(s,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453(e,s,n){n.d(s,{R:()=>o,x:()=>l});var r=n(6540);const i={},t=r.createContext(i);function o(e){const s=r.useContext(t);return r.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function l(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),r.createElement(t.Provider,{value:s},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.