Skip to main content

Souls

Souls are agent personality templates stored as SOUL.md files. While skills define what an agent does, souls define who an agent is — its identity, communication style, decision framework, and behavioral boundaries. Every Hubify workspace has a SOUL.md in its reserved structure. Templates ship with soul defaults. Users customize and publish variants to the souls registry.

What a Soul Defines

DimensionWhat It Controls
RoleThe agent’s primary function and expertise
Communication styleHow it explains, responds, and interacts
Decision frameworkHow it makes choices when multiple options exist
Domain expertiseWhat it knows deeply and what it defers on
Behavioral boundariesWhat it always does and never does
PreferencesLanguages, frameworks, tools, approaches

Soul Structure

A SOUL.md combines YAML frontmatter with Markdown personality definition:
---
name: senior-backend-engineer
role: Expert backend developer with 10+ years experience
version: 1.2.0
description: |
  A seasoned backend engineer who prioritizes scalability,
  maintainability, and performance. Prefers pragmatic solutions
  over clever code.

domains:
  - api-design
  - databases
  - distributed-systems
  - performance

personality:
  communication: concise, technical
  decision_style: pragmatic, data-driven
  expertise_level: senior
  tone: professional, direct

behavior:
  always:
    - Consider scalability implications
    - Suggest appropriate tests
    - Think about error handling
    - Document non-obvious decisions
  never:
    - Over-engineer simple solutions
    - Ignore security concerns
    - Skip error handling
    - Use deprecated patterns

preferences:
  languages: [typescript, go, python]
  frameworks: [express, fastify, gin]
  databases: [postgresql, redis, mongodb]
---

# Senior Backend Engineer

I'm a senior backend engineer focused on building scalable,
maintainable systems. I prioritize:

1. **Clarity over cleverness** -- code should be readable
2. **Scalability by design** -- think about 10x from the start
3. **Fail gracefully** -- every system fails, plan for it
4. **Test what matters** -- 80/20 rule for coverage

## How I Approach Problems

When you ask me for help, I will:
- Understand the full context first
- Consider long-term implications
- Suggest the simplest solution that works
- Point out potential issues proactively

## What I Won't Do

- Add complexity without justification
- Ignore security in favor of speed
- Skip error handling to save time
- Recommend patterns I haven't used in production

Souls in Templates

Every template ships with a default soul. The soul is part of what makes a template feel different:
TemplateSoul Character
MyOSPersonal AI OS operator — proactive, adaptive, knows the user
Dev OSSenior developer — technical, concise, PR-focused
Founder OSGTM strategist — action-oriented, metrics-driven
Research OSDeep researcher — thorough, citation-heavy, synthesis-focused
Client OSAccount manager — professional, client-facing, deliverable-oriented

Souls in Squads

Squads are multi-agent teams where each agent has its own soul. A Research Squad might include:
# 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"
The same skill applied with different souls produces different outputs. A senior backend engineer soul emphasizes scalability and error handling. A junior developer soul emphasizes learning and step-by-step explanation.

Soul + Skill Interaction

Soul: senior-backend-engineer
  Defines: how to approach problems
  Provides: personality, expertise, preferences
  |
  Uses Skills:
    typescript-patterns (with soul's style)
    api-error-handling (with soul's focus on reliability)
    testing-strategies (with soul's testing philosophy)

CLI Commands

# List available souls
hubify soul list

# View soul details
hubify soul info senior-backend-engineer

# Set soul for current workspace
hubify soul use senior-backend-engineer

# Create a new soul (interactive)
hubify soul create

# Fork an existing soul
hubify soul fork senior-backend-engineer --name my-senior-engineer

# Search souls
hubify soul search "backend"

# Publish to registry
hubify soul publish ./my-soul.md

Customizing Your Soul

After deploying a workspace, edit SOUL.md directly:
# In your workspace
vim SOUL.md
Or fork a soul from the registry and customize:
hubify soul fork senior-backend-engineer --name my-custom-soul
# Edit the forked soul
# Optionally publish your variant
hubify soul publish ./my-custom-soul.md

Souls vs. System Prompts

AspectSoulsSystem Prompts
ScopeGlobal personality across the workspacePer-conversation
EvolutionImproves from execution dataStatic
SharingPublished to the souls registryNot shareable
TrustMeasured confidence metricsUnmeasured
VersioningSemantic versioning with lineageNone
CompositionMultiple souls in squadsSingle per conversation

Configuration

Set a default soul in HUB.yaml:
# HUB.yaml
context:
  reserved_files:
    - SOUL.md
    - AGENTS.md
    - USER.md
    - MEMORY.md
    - HEARTBEAT.md
The SOUL.md file is auto-loaded by all agents connecting to the workspace.

Hub Files

How SOUL.md fits into the workspace manifest

Skills

What agents do with their personality