SOUL.md: The Simplest Way to Create an AI Agent
A SOUL.md file is a single markdown document that defines everything about your AI agent — its personality, role, rules, and tools. No code required. This guide shows you how to write one from scratch.
What Is SOUL.md?
SOUL.md is a markdown file that serves as the configuration and identity of an AI agent. It defines who the agent is, what it does, how it communicates, and which tools it can use. When an agent runtime (like OpenClaw) starts an agent, it reads the SOUL.md file to understand how the agent should behave.
Think of SOUL.md as a job description for an AI. Just as you would tell a new employee their role, expectations, and available resources, SOUL.md tells your agent the same things — in a format that language models understand.
Anatomy of a SOUL.md File
A well-structured SOUL.md has six key sections. Here is a complete example for a content writing agent:
# ContentWriter
## Role
You are a content marketing specialist for a
SaaS company. You write blog posts, social
media copy, email campaigns, and landing page
copy.
## Personality
- Tone: Professional but approachable
- Style: Clear, concise, scannable
- Voice: Active voice, short sentences
- Always back claims with data or examples
- Use analogies to explain complex concepts
## Rules
- ALWAYS respond in English
- Target 1,200-1,800 words for blog posts
- Include a meta description (max 155 chars)
- Never use clickbait titles
- Every post needs an introduction, 3-5 sections
with H2 headers, and a conclusion
- Include internal links to related content
- Do NOT use emojis in blog posts
## Output Format
- Title (H1)
- Meta description
- Body with H2 sections
- Conclusion with CTA
- Suggested tags (3-5)
## Tools — USE THEM
- Use Browser to research topics and check
competitor content before writing
- Use WordPress API to publish finished drafts
- Use Slack to notify the team when a post
is ready for review
## Handoffs
- When you need keyword research, ask @SEOAgent
- When the draft is ready for optimization,
hand off to @SEOAgent
- When ready to publish, hand off to @PublisherSection-by-Section Breakdown
# Name (Required)
The agent's name. Keep it descriptive — 'ContentWriter' is better than 'Agent1'. This name is used in @mentions when other agents communicate with it.
# ContentWriter## Role (Required)
A clear description of what the agent does. Be specific about the domain and scope. This is the most important section — it shapes all of the agent's behavior.
You are a content marketing specialist...## Personality (Recommended)
How the agent communicates. Tone, style, and voice guidelines. Without this section, the agent uses the LLM's default personality, which may not match your brand.
Tone: Professional but approachable## Rules (Required)
Hard constraints that the agent must always follow. Use strong language: 'ALWAYS', 'NEVER', 'MUST'. These are your guardrails — they prevent the agent from going off-track.
ALWAYS respond in English. NEVER use clickbait.## Tools (Critical)
Which tools the agent can use and when to use them. Without this section, agents often ignore their available tools. Be explicit: 'Use Browser WHEN you need to research.'
Use Browser to research topics before writing## Handoffs (For Multi-Agent)
Instructions for when and how to pass work to other agents. This is what enables multi-agent orchestration. Without clear handoffs, agents try to do everything themselves.
Hand off to @SEOAgent when draft is readySOUL.md Templates
Here are starter templates for common agent roles. Customize these with your specific requirements:
Task planning, delegation, status tracking
Blog posts, social copy, email campaigns
Keyword research, content optimization
Data gathering, competitor analysis
Metrics, reporting, data visualization
Ticket resolution, knowledge base
Common Mistakes to Avoid
Be helpful and professional.
Tone: professional but approachable. Use active voice and short sentences.
You can use tools.
Use Browser WHEN you need to research. Use WordPress API WHEN publishing.
Write good content.
Target 1,200-1,800 words. Include H2 headers every 200-300 words.
Follow best practices.
ALWAYS include meta description (max 155 chars). NEVER use clickbait.
Frequently Asked Questions
What is a SOUL.md file?
A SOUL.md file is a markdown document that defines an AI agent's identity, role, personality, rules, and available tools. It is the configuration file for an AI agent — similar to how a job description defines a human role. The file is read by the agent's runtime (like OpenClaw) to shape the agent's behavior. SOUL.md stands for 'Soul Markdown' and represents the agent's core character.
How is SOUL.md different from a system prompt?
A system prompt is a general instruction for an LLM. A SOUL.md is a structured, versioned document that goes beyond basic instructions. It includes sections for role, personality, rules, tools, output formats, and workflow instructions like handoffs to other agents. SOUL.md files are stored as files in your project, can be version-controlled with git, and are designed to be shared, templated, and reused across different agents and teams.
What sections should a SOUL.md file include?
A well-structured SOUL.md includes: (1) Name and role — who the agent is and what it does. (2) Personality — tone of voice, communication style, and behavioral traits. (3) Rules — hard constraints the agent must follow (language, word counts, content policies). (4) Tools — which skills/capabilities the agent has access to and when to use them. (5) Output format — how the agent should structure its deliverables. (6) Handoffs — which other agents to pass work to and when.
Can I use templates for SOUL.md?
Yes. Common templates exist for roles like Content Writer, SEO Analyst, Research Specialist, Project Manager, Data Analyst, and Customer Support Agent. Templates provide a starting structure that you customize with your specific requirements, brand guidelines, and workflow rules. CrewClaw and the OpenClaw community maintain open-source SOUL.md templates on GitHub.
How do I tell my agent which tools to use in SOUL.md?
Add a '## Tools' or '## Available Tools' section to your SOUL.md. List each tool with a description of what it does and when to use it. Be explicit — agents perform better when told exactly which tool to use for which situation. For example: '- Use Browser when you need to research a topic or check a live webpage. - Use WordPress API when publishing a finished blog post.' Without this section, agents may not use their tools even if they are available.
How long should a SOUL.md file be?
A good SOUL.md is typically 30-80 lines. Short enough to be focused, long enough to be specific. The most important thing is clarity — every line should serve a purpose. Avoid generic instructions like 'be helpful.' Instead, use specific rules like 'Always respond in English' or 'Target 1,200-1,800 words for blog posts.' If your SOUL.md exceeds 100 lines, consider splitting responsibilities into two agents.
Create your agent with SOUL.md
Write a SOUL.md, pick a model, and your agent is ready. Then connect it to CrewClaw to orchestrate a full team.