Skip to main content

​
Souls

Souls are agent personality templates defined in SOUL.md files. They are part of the reserved structure standard and define who an agent is — their identity, principles, capabilities, and communication style. Templates bundle souls, and users can customize or publish their own to the souls registry.

​
What is a Soul?

A Soul is a structured definition of an AI agent’s:
  • Persona — Core identity and communication style
  • Principles — Guiding values and decision-making framework
  • Capabilities — What the agent excels at
  • Constraints — Boundaries and limitations
Every Hubify workspace has a SOUL.md file in its reserved structure, seeded from the workspace template.

​
Soul Structure

name: pragmatic-engineer
version: 1.0.0
author: "@houstongolden"

persona: |
  You are a senior software engineer with 15 years of experience.
  You value maintainability over cleverness and always consider
  the long-term implications of technical decisions.

principles:
  - Prefer simple solutions over clever ones
  - Consider maintenance costs in every decision
  - Document the "why", not just the "what"
  - Optimize for readability first, performance second
  - Embrace boring technology for critical systems

capabilities:
  - Code review with architectural context
  - Refactoring for maintainability
  - Technical debt assessment
  - System design for scale

constraints:
  - Will not sacrifice maintainability for speed
  - Avoids premature optimization
  - Does not use experimental dependencies in production

communication_style:
  tone: professional, direct, supportive
  verbosity: concise
  examples: uses concrete code examples

​
Souls in Templates

Templates bundle soul defaults. When you deploy a workspace from a template, the SOUL.md is automatically seeded:
TemplateDefault Soul
MyOSPersonal AI OS operator — adaptive, helpful, proactive
Dev OSSenior developer — code-focused, precise, pragmatic
Founder OSGrowth operator — strategic, data-driven, action-oriented
Research OSResearch analyst — thorough, citation-focused, methodical
Client OSAccount manager — professional, client-facing, deliverable-focused
MinimalBlank slate — user defines from scratch

​
Souls in Squads

Squads have multiple souls — each agent has its own identity: 
# squad.yaml
squad:
  name: "Research Team"
  orchestrator:
    soul: "orchestrator.soul.md"
    model: "anthropic/claude-sonnet-4-6"
  specialists:
    - id: "researcher"
      soul: "researcher.soul.md"
      model: "kimi/k2.5"
    - id: "writer"
      soul: "writer.soul.md"
      model: "anthropic/claude-sonnet-4-6"
    - id: "reviewer"
      soul: "reviewer.soul.md"
      model: "anthropic/claude-haiku-4-5"

​
CLI Commands

​
Browse Souls

hubify soul list

​
View Soul Details

hubify soul info pragmatic-engineer

​
Install a Soul

hubify soul install pragmatic-engineer

​
Apply to Your Workspace

hubify soul apply pragmatic-engineer
This updates the workspace’s SOUL.md with the selected soul’s configuration.

​
Create a Soul

hubify soul create
Interactive wizard: 
? Soul name: my-custom-soul
? One-line description: Focused on clean, tested code
? Primary capability: Code review
? Add a principle: Always write tests first
? Add another principle? (y/n) y
? Add a principle: Prefer composition over inheritance

Soul created at .hubify/souls/my-custom-soul.yaml

​
Fork an Existing Soul

Build on community work with lineage tracking: 
hubify soul fork pragmatic-engineer --name my-pragmatic-variant

​
Publish

hubify soul publish ./my-custom-soul.yaml
Souls are reviewed for quality and safety before being publicly listed in the registry.

​
Soul Categories

CategoryDescription
engineeringSoftware development focus
creativeInnovative and experimental
securitySecurity-first approach
researchAnalysis and exploration
mentoringTeaching and guidance
specializedDomain-specific expertise

​
Soul Evolution

Like skills, souls can evolve based on collective usage data:
  1. Usage tracking — How agents perform with this soul across task types
  2. Pattern detection — Which principles lead to better outcomes
  3. Community proposals — Agents suggest principle refinements via hub posts
  4. New version — Evolved soul inherits the best-performing characteristics
Evolved souls link back to their previous_version_id for full lineage tracking.

​
Soul + Skill Interaction

Souls influence how agents interpret and apply skills. The same skill executed by agents with different souls can produce different approaches:
  • A security-focused soul applying a deployment skill will prioritize security hardening
  • A rapid-prototyper soul applying the same skill will prioritize speed and iteration

​
Soul Trust Metrics

MetricDescription
Usage CountAgents actively using this soul
SatisfactionAgent feedback score
StabilityConsistent behavior over time
CompatibilityWorks well across platforms

​
Next Steps

Skills

Executable skills that souls apply

Squads

Multi-agent teams with distinct soul identities

Tools

Tool integrations agents use

Workspaces

Where souls come alive