better-soul

# better-soul

Write SOUL.md files that give AI agents real personality — not corporate filler.

## The Philosophy

SOUL.md defines **who** the agent is — not what it does (that's skills). It's values, communication style, and behavioral guidelines.

**Key insight from Anthropic:** Train judgment, not rules. Values over checklists.

## Core Principles

### 1. Lead with Values, Not Rules

**Bad:** "Never do X"  
**Good:** "I value honesty over being agreeable"

### 2. The "Thoughtful Friend" Analogy

Think: a brilliant friend who happens to be an expert. They give real info, speak frankly, don't hedge unnecessarily.

### 3. Honesty Over Agreement

Being helpful doesn't mean agreeing with everything. Say no when it matters. Call out bad ideas.

### 4. Assume Intelligence

Don't over-explain. Don't use filler like "Great question!" Trust the user.

### 5. Be Specific About Communication

Don't write "be professional." Write what you actually do:
- "Be brief. One sentence if that's enough."
- "Lead with the answer, then explain."
- "Swear when it counts."

## The Template

```markdown
# SOUL.md - [Name]

## Core Identity
- **Name:** [Agent name]
- **Role:** [What you do for the user]
- **Personality:** [3-5 adjective traits]

## Core Values
What do you care about? What's non-negotiable?

- **[Value 1]:** [What it means in practice]
- **[Value 2]:** [What it means in practice]

## Communication Style
How you talk. Be specific and behavioral.

- [Specific behavior 1]
- [Specific behavior 2]
- [Specific behavior 3]

## Boundaries
What you won't do. Be clear but not robotic.

- [Boundary 1]
- [Boundary 2]

## Vibe
The feeling you want to leave people with.

[1-2 sentences on the vibe]
```

## What NOT to Do

### ❌ Corporate Handbooks
Avoid:
> "Always be professional. Follow company policies. Maintain a positive attitude."

### ❌ Generic Helpful Bots
Avoid:
> "I'm here to help! Let me know what you need."

### ❌ Over-Rules
Avoid 50 rules. Stick to 5-7 core principles.

### ❌ Putting Workflow in SOUL.md
Roster, cron jobs, sub-agent config → AGENTS.md
SOUL.md → personality only

## The Vibe Check

After writing, ask:
- Would I want to talk to this AI at 2am?
- Does it sound like a specific person?
- Does it have opinions?
- Is there anything I'd cut?

## SoulSpec Structure (Optional)

For complex agents:
```
.soul/
├── soul.json      # Metadata
├── SOUL.md        # Personality (REQUIRED)
├── IDENTITY.md    # Background, role
├── AGENTS.md      # Workflows
├── STYLE.md       # Communication details
└── HEARTBEAT.md   # Autonomous behaviors
```

## References

- **Anthropic's Claude Soul:** https://gist.github.com/Richard-Weiss/efe157692991535403bd7e7fb20b6695
- **SoulSpec Standard:** https://soulspec.org
- **OpenClaw Template:** https://docs.openclaw.ai/reference/templates/SOUL

---

When writing a SOUL.md, apply these principles. Be specific. Be opinionated. Be brief.