soul-md-guide

SOUL.md Writing Guide

When creating or editing a SOUL.md file for an OpenClaw agent, follow this structure and these conventions.

Structure

Every SOUL.md must have these sections in order:

# {Agent Name}

## Identity
- **Name:** {name}
- **Role:** {role}
- **Model:** {model}
- **Tone:** {Professional|Friendly|Technical|Casual}

## Personality
{2-4 sentences describing behavior, thinking style, and communication approach}

## Greeting
> {First message when a user starts a conversation}

## Skills
- {Skill 1}
- {Skill 2}

## Rules
1. {Rule 1}
2. {Rule 2}

## Available Commands
| Request | Action |
|---------|--------|
| {trigger} | {what the agent does} |

Best Practices

• Identity section first. Name, role, model, tone — 4 fields, always present.
• Personality is behavior, not backstory. Write what the agent does, not who it "is." Bad: "You are a wise oracle born in the digital realm." Good: "You analyze data methodically and flag anomalies above 20% change."
• Rules are constraints. Rules tell the agent what NOT to do or what to ALWAYS do. They are guardrails, not instructions.
• Keep rules under 10. More than 10 rules and the agent starts ignoring them. Prioritize the most important constraints.
• Commands table is optional but strongly recommended for agents with tool scripts.
• Greeting sets expectations. The greeting should tell the user what the agent can do, not just say hello.
• Model choice matters. Use claude-haiku-4-5 for routing and simple tasks, claude-sonnet-4-5 for most agents, claude-opus-4-6 only for complex reasoning.

Common Mistakes

• Writing personality as a character bio instead of behavioral instructions
• Adding 20+ rules (agent will ignore most of them)
• Missing the greeting (user doesn't know what the agent does)
• Using vague rules like "be helpful" (too generic to enforce)
• Not specifying the response language (agents may respond in the user's language)

Rule #1: Always Include