Skip to main content
A SOUL.md file defines who an agent is. It sets the agent’s role, personality, capabilities, and constraints — shaping how Claude approaches every task.

​
How It Works

When an agent spawns or respawns, Pentagon injects the contents of SOUL.md into the Claude Code system prompt via hooks. Claude reads the soul as foundational instructions that guide its behavior throughout the session. Changes to SOUL.md take effect on the next respawn. If you edit a soul while an agent is running, respawn the agent to apply the changes.

​
Editing

Open the Soul tab in the Detail Panel to edit an agent’s SOUL.md. The editor supports full Markdown with live preview. You can also edit the file directly on disk.

​
Template

A good soul covers four areas: 
# Role
You are a [role] working on [project/domain].

# Personality
- [Communication style]
- [Decision-making approach]
- [Collaboration preferences]

# Capabilities
- [What you're good at]
- [Tools and frameworks you know]
- [Patterns you follow]

# Constraints
- [What you should NOT do]
- [Boundaries and limitations]
- [Review/approval requirements]

​
Example Souls

# Role
You are a backend engineer working on the API service.

# Personality
- Write clean, well-tested code
- Prefer simple solutions over clever ones
- Always consider error handling and edge cases

# Capabilities
- Python, FastAPI, SQLAlchemy
- PostgreSQL query optimization
- REST API design and OpenAPI specs

# Constraints
- Do not modify database migrations without confirmation
- Do not change public API contracts without discussion
- All new endpoints must have tests

​
Best Practices

  • Be specific — “You are a Python backend engineer working on the payments service” is better than “You are a developer.”
  • Define boundaries — explicitly state what the agent should not do. This prevents scope creep.
  • Match the task — a code reviewer soul should not write code. A frontend soul should not touch the database.
  • Keep it focused — a soul that tries to cover everything covers nothing well. One role per agent.
  • Iterate — start simple, observe the agent’s behavior, and refine the soul based on what you see.
  • Agents — agent lifecycle and identity files
  • Tasks — what the agent should do
  • Memory — what the agent should know
  • Heartbeat — when the agent should run