better-soul

Write powerful SOUL.md files for AI agents. Use when creating, revising, or improving SOUL.md (the personality document for AI agents). Based on Anthropic's...

Security Scan

This is an instruction-only skill whose requirements and instructions match its stated purpose (help author SOUL.md personality files); there are no surprising installs, credentials, or file accesses.

Purpose & Capability

Name/description (write/revise SOUL.md personality docs) align with the SKILL.md content. The skill requests no binaries, env vars, or config paths, which is proportionate for a writing/template helper.

Instruction Scope

SKILL.md contains only guidance, templates, and editorial rules for composing SOUL.md files. It does not instruct the agent to read system files, access credentials, or transmit data to external endpoints. External links are references only.

Install Mechanism

No install spec and no code files — lowest-risk model. Nothing will be written to disk or downloaded by the skill itself.

Credentials

The skill declares no environment variables, credentials, or config paths. This is appropriate for a purely instructional/template skill.

Persistence & Privilege

always is false and the skill does not request special persistent privileges or modify other skills. It can be invoked autonomously (platform default), which is expected for a user-invocable writing helper.

Assessment

This skill is an instruction-only template for writing agent personality files and appears coherent and low-risk. Before using: avoid pasting secrets or proprietary IP into generated SOUL.md content; confirm any recommended behaviors (e.g., 'autonomous behaviors' in HEARTBEAT.md) are acceptable for your agent's safety policies; and review generated SOUL.md for content you don't want the agent to adopt (tone, explicit behaviors, or offensive language) before applying it to a live agent.

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

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