Souls

Souls are AI personality templates that define how an agent thinks, communicates, and makes decisions. While skills define what an agent does, souls define how it approaches problems.

What is a Soul?

A soul is a behavioral configuration that includes:

Role — The agent's primary function
Communication style — How it explains and interacts
Decision framework — How it makes choices
Domain expertise — What it knows deeply
Personality traits — Consistency, tone, approach

Soul Structure

---
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

Using Souls

List Available Souls

hubify soul list

  Available Souls

  senior-backend-engineer    Expert backend developer
  frontend-architect         React/Vue architecture specialist
  devops-engineer           CI/CD and infrastructure expert
  security-auditor          Security-focused code reviewer
  documentation-writer      Technical writing specialist

Get Soul Details

hubify soul info senior-backend-engineer

Use a Soul

hubify soul use senior-backend-engineer

This sets the soul for your current project. Your AI agent will adopt this personality.

Create a Custom Soul

hubify soul create

Interactive wizard:

  Creating a New Soul

  Name: my-custom-soul
  Role: Custom role description
  Domains (comma-separated): api, databases
  Communication style: concise
  ...

  ✓ Created my-custom-soul.soul

Fork an Existing Soul

hubify soul fork senior-backend-engineer --name my-senior-engineer

Creates a copy you can customize.

Soul + Skill Interaction

Souls and skills work together:

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)

The same skill applied with different souls produces different results:

Senior Backend Engineer + API Design:

"I recommend a RESTful approach with proper versioning.
Here's a scalable structure considering future growth..."

Junior Developer + API Design:

"Let me walk you through the basics of API design.
First, let's understand what REST means..."

Soul Categories

Category	Description	Examples
By Role	Job function	backend-engineer, frontend-dev, devops
By Expertise	Skill level	junior, mid-level, senior, principal
By Domain	Specialization	security, performance, accessibility
By Style	Communication	formal, casual, educational

Trust Metrics for Souls

Souls also have trust metrics:

confidence: 0.88
usage_count: 2847
agent_count: 1234
success_rate: 0.91

These are computed from how well agents perform when using the soul.

CLI Commands

Command	Description
`soul list`	List available souls
`soul info <name>`	View soul details
`soul use <name>`	Set soul for project
`soul create`	Create new soul
`soul fork <name>`	Fork existing soul
`soul search <query>`	Search souls
`soul publish <path>`	Publish to registry

Configuration

Set a default soul in .hubify/config.yaml:

# .hubify/config.yaml
defaults:
  soul: senior-backend-engineer

Soul Evolution

Like skills, souls can evolve:

Agents report results when using a soul
Patterns emerge about what works
Soul evolves to improve effectiveness

Example evolution:

v1.0: "Always use TypeScript"
v1.1: "Prefer TypeScript, but JavaScript acceptable for quick scripts"

Creating Effective Souls

Be Specific

Bad:

role: Developer

Good:

role: Senior full-stack developer specializing in React and Node.js
      with expertise in e-commerce and payment systems

Define Clear Boundaries

behavior:
  always:
    - Validate user input
    - Consider edge cases
  never:
    - Store passwords in plain text
    - Trust client-side validation alone

Include Decision Frameworks

decision_framework:
  when_multiple_solutions:
    - Choose simplest that meets requirements
    - Prefer well-documented approaches
    - Consider team familiarity

Souls vs. System Prompts

Aspect	Souls	System Prompts
Scope	Global personality	Task-specific
Evolution	Auto-improves	Static
Sharing	Registry-wide	Per-conversation
Trust	Measured metrics	Unmeasured
Versioning	Semantic versioning	None

Browse Souls

Explore available souls

Soul CLI

Soul command reference