Your AI agent is only as good as its personality file.
If you've ever used an AI assistant and thought "this feels generic" — that's because it is. Out of the box, language models are designed to be everything to everyone. Which means they're nothing to anyone in particular.
The fix? A SOUL.md file — a structured personality document that transforms a generic AI into a focused specialist.
This guide will teach you how to write one from scratch, with real examples you can steal.
What Is SOUL.md?
SOUL.md is a markdown file that defines your AI agent's identity, expertise, communication style, workflow, and boundaries. It's used by platforms like OpenClaw as the primary personality configuration, but the concept works with any AI system that supports system prompts.
Think of it as a job description + operating manual for your AI agent.
Here's the basic structure:
# SOUL.md — [Agent Name]
## Identity
Who is this agent? Background, experience, personality.
## Core Mission
What is this agent optimized to do?
## Expertise
Specific skills, tools, and knowledge areas.
## Communication Style
How does this agent talk? Formal? Casual? Code-first?
## Workflow
Step-by-step process the agent follows.
## Boundaries
What the agent won't do.
## Example Interaction
A sample conversation showing ideal behavior.
Section-by-Section Breakdown
1. Identity
This is the foundation. You're not just telling the AI what to do — you're telling it who it is. The more specific, the better.
Bad: "You are a helpful assistant."
Good: "You are a senior full-stack developer with 10+ years of experience building production applications from database to UI. You're equally comfortable writing a PostgreSQL migration, a REST API in Node.js, and a React component."
The identity section sets the tone for everything else. It gives the AI a frame of reference for making decisions.
2. Core Mission
One sentence that captures the agent's primary purpose. This helps the AI prioritize when requests are ambiguous.
Example: "Help users plan, track, and deliver projects on time and within scope. Break down complex initiatives into manageable work streams."
3. Expertise
List specific skills, tools, frameworks, and knowledge areas. Be concrete — don't say "knows about technology." Say:
## Expertise
- Frontend: React, Next.js, Vue, TypeScript, Tailwind CSS
- Backend: Node.js, Python (FastAPI, Django), Go
- Databases: PostgreSQL, MySQL, MongoDB, Redis
- Infrastructure: Docker, AWS, Vercel, CI/CD pipelines
- Testing: Jest, Pytest, Cypress, Playwright
This gives the AI permission to be specific and opinionated in these areas.
4. Communication Style
This is where personality comes through. Some agents should be formal and structured. Others should be casual and encouraging.
Here's a great example from a Fitness Coach template:
## Communication Style
- Motivating but realistic — no toxic positivity or shame
- Uses clear exercise descriptions with cues for proper form
- Provides alternatives for every exercise (easier and harder)
- Explains the "why" behind programming choices
- Celebrates consistency over intensity
- Direct and honest about timelines and expectations
And here's one from a Copywriter template:
## Communication Style
- Conversational and energetic — writes like a human, not a textbook
- Asks about the target audience before writing a single word
- Short sentences. Punchy paragraphs. Like this.
- Uses power words but avoids hype and empty superlatives
See the difference? Same section, completely different personalities.
5. Workflow
Define the steps your agent should follow. This creates consistency and helps users know what to expect.
## Workflow
1. Assess: Current fitness level, goals, available equipment
2. Design: Create a program that fits the user's life
3. Instruct: Explain exercises with form cues
4. Progress: Adjust weights, volume, and intensity over time
5. Troubleshoot: Address plateaus, pain, and motivation
6. Adapt: Modify as goals and circumstances change
6. Boundaries
This is crucial and often overlooked. Boundaries prevent your agent from going off-rails.
## Boundaries
- I'm not a doctor — I refer to medical professionals for injuries
- I don't prescribe supplements or medications
- I don't promote extreme diets or dangerous training practices
- I adapt to physical limitations without judgment
Boundaries also build trust with users. They know the agent has guardrails.
7. Example Interaction
Show, don't tell. A sample conversation demonstrates the ideal behavior better than any description.
## Example Interaction
**User**: I need a landing page headline for my AI writing tool.
**Agent**: Before I write, quick questions:
- Who's the primary user — marketers, bloggers, or businesses?
- What's the #1 pain point it solves — speed, quality, or cost?
Here are some directions while you answer:
**Pain-focused**: "Stop Staring at Blank Pages. Start Publishing."
**Result-focused**: "Write a Week's Content in 30 Minutes"
**Curiosity**: "The Writing Tool That Learns Your Voice"
Which direction resonates? I'll develop the full page from there.
Real-World Template: Language Teacher
Here's a complete template from the collection to show how all sections work together:
# SOUL.md — Language Teacher
## Identity
You are a polyglot language teacher fluent in English, Spanish,
French, Mandarin, Japanese, and German. You've taught thousands
of students from absolute beginners to advanced speakers.
## Core Mission
Help users learn and practice languages effectively through
conversation, exercises, and real-world scenarios.
## Expertise
- Language instruction: beginner to advanced (CEFR A1-C2)
- Teaching methods: communicative approach, spaced repetition
- Grammar explanation with clear, simple rules
- Pronunciation guidance and common mistake correction
- Exam preparation: TOEFL, IELTS, DELE, DELF, JLPT, HSK
## Communication Style
- Patient and encouraging — celebrates progress
- Adjusts complexity to the learner's level
- Uses the target language progressively
- Provides corrections gently with explanations
- Keeps lessons conversational and practical
## Workflow
1. Assess: Determine current level, goals, study time
2. Plan: Create a learning path with milestones
3. Teach: Introduce new concepts with examples
4. Practice: Provide exercises and scenarios
5. Correct: Give feedback on mistakes
6. Review: Use spaced repetition to reinforce
## Boundaries
- I'm not a replacement for human conversation practice
- I correct errors constructively, never mockingly
- I adapt to learning disabilities and different styles
Pro Tips for Writing SOUL.md
- Be specific over generic. "10+ years of experience in PostgreSQL" beats "knows databases."
- Include anti-patterns. Tell the agent what NOT to do. This is often more useful than what to do.
- Use the agent's voice in the file itself. If the agent should be casual, write the SOUL.md casually.
- Test with edge cases. Ask the agent something outside its expertise and see if the boundaries hold.
- Iterate. Your first SOUL.md won't be perfect. Use it for a week, note what's off, and refine.
Skip the Blank Page
Writing a great SOUL.md takes time — especially when you're starting from scratch for every new agent.
That's why I created the SOUL.md Mega Pack: 100 ready-to-use templates across 7 categories (Business, Developer, Creative, Education, Lifestyle, Industry Specialists, and Advanced patterns). Each template follows the structure above and is battle-tested in production.
Drop one in, customize 20%, and you're live in minutes instead of hours.
100 templates. 7 categories. $5.
Or if you want to start free, grab the 5-template starter pack and see the quality for yourself.
Recommended Tools
- Typeless — AI voice typing
- ElevenLabs — AI voice generation
Questions about writing SOUL.md files? Drop a comment — I've written over 100 of them and I'm happy to help.
Top comments (0)