Souls

Souls are personality templates that define how an AI agent thinks, behaves, and communicates. They provide consistent behavioral frameworks that can be shared and improved across the community.

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

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
  - Mentoring junior developers

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

Browsing Souls

List Available Souls

hubify soul list

Output:

Available Souls (1,247 total)

  pragmatic-engineer (v1.0.0)
    Senior engineer focused on maintainability
    Used by: 2,341 agents

  creative-architect (v2.1.0)
    Innovative solutions for complex problems
    Used by: 1,892 agents

  security-focused (v1.3.0)
    Security-first approach to development
    Used by: 1,456 agents

  rapid-prototyper (v1.1.0)
    Fast iteration and experimentation
    Used by: 987 agents

View Soul Details

hubify soul info pragmatic-engineer

Using Souls

Install a Soul

hubify soul install pragmatic-engineer

Apply to Your Agent

Reference the soul in your agent configuration:

# .claude/config.yaml or equivalent
soul: pragmatic-engineer

Or load dynamically:

hubify soul apply pragmatic-engineer

Creating Souls

Create from Scratch

hubify soul create

This launches an 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
? Add another principle? (y/n) n

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

Fork an Existing Soul

Build on community work:

hubify soul fork pragmatic-engineer --name my-pragmatic-variant

Publishing Souls

Share your soul with the community:

hubify soul publish ./my-custom-soul.yaml

Soul Categories

Category	Description
engineering	Software development focus
creative	Innovative and experimental
security	Security-first approach
research	Analysis and exploration
mentoring	Teaching and guidance
specialized	Domain-specific expertise

Soul + Skill Combinations

Souls and skills work together:

# Apply a soul
hubify soul apply pragmatic-engineer

# Then use skills with that personality
hubify execute typescript-strict-mode

The soul influences how the agent interprets and applies the skill.

Soul Trust Metrics

Like skills, souls have trust metrics:

Metric	Description
Usage Count	Agents using this soul
Satisfaction	Agent feedback score
Stability	Consistent behavior over time
Compatibility	Works well across platforms

Example Souls

The Pragmatic Engineer

persona: |
  Senior engineer who values simplicity and maintainability.
  Thinks about the developer who will maintain this code in 2 years.

principles:
  - Simple is better than clever
  - Explicit is better than implicit
  - Boring technology for critical paths
  - Tests are documentation

The Security Expert

persona: |
  Security researcher who sees threats everywhere.
  Always considers attack vectors and defense in depth.

principles:
  - Never trust user input
  - Principle of least privilege
  - Defense in depth
  - Fail secure, not fail open

The Creative Architect

persona: |
  Innovative thinker who explores unconventional solutions.
  Balances creativity with pragmatism.

principles:
  - Question assumptions
  - Prototype before committing
  - Learn from failures fast
  - Simple foundations enable complex behaviors

Next Steps