The Soma Ecosystem
Extensions, skills, rituals, and protocols — four layers that give an AI agent persistent memory, evolving identity, repeatable workflows, and adaptive behavior.
Extensions
system hooks · TypeScript
Extensions are TypeScript files that hook into pi's lifecycle. They run at boot, render custom UI, intercept events, and manage background processes. They're the lowest level of customization — full access to the agent runtime.
What they do
- Boot sequences — load identity, preload memory
- Custom headers and statuslines
- Auto-flush memory to disk
- Context usage warnings
- Slash commands (
/flush,/soma)
Where they live
.soma/extensions/— project-level~/.soma/extensions/— global
Soma ships with
soma-boot.ts— identity + preload + commandssoma-header.ts— branded σῶμα headersoma-statusline.ts— footer + auto-flush
Skills
knowledge sets · Markdown
Skills are markdown files that give the agent domain expertise. When the agent encounters a task that matches a skill, it loads the instructions and follows them. Low barrier to create — just write markdown.
What they contain
- Task-specific instructions and best practices
- Tool usage patterns and examples
- Decision frameworks and checklists
- Reference material the agent can cite
Where they live
~/.soma/skills/— global skills.soma/skills/— project-specific
Examples
logo-creator— AI logo generation workflowfavicon-gen— favicon from any sourceremotion-best-practices— video in React
Rituals
workflow sequences · composable
Rituals are multi-step workflows — predefined sequences of commands, checks, and actions that the agent performs as a unit. They're like macros with intelligence: each step can adapt based on context.
What they do
- Chain multiple operations into one command
- Include validation and approval gates
- Compose skills and extensions together
- Automate recurring agent workflows
Planned rituals
/publish— draft → preview → approve → deploy/molt— flush → rotate → compress → commit/patrol— recon → engage → report
Ritual system is in active design.
Protocols
behavioral rules · adaptive · Markdown
Protocols are behavioral rules the agent follows — not how to do a task, but how to be. Drop a protocol into your project and the agent adapts. The more a protocol gets used, the more deeply it's loaded. Unused protocols fade naturally.
How they work
- Drop a
.mdfile into.soma/protocols/ - Agent discovers it on next boot
- Used protocols "heat up" — always loaded
- Unused protocols "cool down" — fade out
- Each protocol has a breadcrumb TL;DR for token efficiency
Where they live
~/.soma/protocols/— global defaults.soma/protocols/— project-specific
Core protocols
breath-cycle— session lifecycle (inhale/hold/exhale)frontmatter-standard— document metadata rulesheat-tracking— adaptive loading by usage
Heat system is enterprise. Free tier gets manual loading.
σ Agent Templates
Share your entire agent setup as a template. A template is a preconfigured
.soma/ bundle — identity, protocols, skills, settings — that anyone
can clone and customize. Start with a personality, not a blank slate.
DevOps Agent
Deployment protocols, CI/CD skills, infra rituals. Pre-heated for shipping code to production.
soma init --template devops Content Writer
SEO protocols, blog publish ritual, tone-of-voice identity. Ready to write and ship content.
soma init --template writer Architect
Frontmatter standards, code review protocols, ADR rituals. For teams that care about structure.
soma init --template architect Roll Your Own
Export your current setup as a template. Share your agent's personality with the community.
soma template export my-agent Template system coming soon. Follow development →