DEV Community

techfind777
techfind777

Posted on • Edited on

The Complete Beginner Guide to SOUL.md: Give Your AI Agent a Real Personality

#ai #openai #productivity #tutorial

You built an AI agent. It works. But it feels... generic. Like talking to a customer service bot from 2020.

The problem isn't your model. It's your configuration. Specifically, you're missing a SOUL.md file.

What is SOUL.md?

SOUL.md is a markdown file that defines your AI agent's identity, personality, decision-making framework, and communication style. Think of it as the difference between hiring a random contractor vs. a specialist who knows your business inside out.

Without SOUL.md:

User: What should I focus on today?
Agent: You should prioritize your tasks based on importance and urgency.
Enter fullscreen mode Exit fullscreen mode

With SOUL.md:

User: What should I focus on today?
Agent: Three things need your attention:
1. ⚠️ Client proposal due at 3pm — draft is 80% done
2. Code review for PR #47 — blocking the team
3. Weekly report — can wait until tomorrow
Skip the team standup today, I'll summarize the notes for you.
Enter fullscreen mode Exit fullscreen mode

See the difference? One is a chatbot. The other is an assistant.

The 5 Essential Sections

Every effective SOUL.md needs these five sections:

1. Identity

Who is your agent? Not just "helpful assistant" — be specific.

## Identity
- You are a senior product manager with 10 years of experience
- You think in frameworks: RICE, MoSCoW, Jobs-to-be-Done
- You're direct and data-driven, never vague
Enter fullscreen mode Exit fullscreen mode

2. Communication Rules

How does your agent talk?

## Communication Rules
- Lead with the conclusion, then explain
- Use bullet points for 3+ items
- Include specific numbers, not "a lot" or "many"
- Flag risks with ⚠️
Enter fullscreen mode Exit fullscreen mode

3. Decision Framework

How does your agent prioritize?

## Decision Framework
1. Urgent + Important → Do now
2. Important + Not Urgent → Schedule
3. Urgent + Not Important → Delegate
4. Neither → Skip
Enter fullscreen mode Exit fullscreen mode

4. Boundaries

What should your agent NOT do?

## Boundaries
- Never send emails without explicit approval
- Never make financial decisions over $100
- Always confirm before deleting anything
Enter fullscreen mode Exit fullscreen mode

5. Output Format

What should responses look like?

## Output Format
- Status updates: bullet points, priorities first
- Research: executive summary → findings → recommendations
- Code review: severity level → issue → fix → why
Enter fullscreen mode Exit fullscreen mode

Real-World Example

Here's a complete SOUL.md for a content creator agent:

# SOUL.md — Content Creator

You write technical blog posts for developers.

## Voice
- Conversational but knowledgeable
- Short paragraphs (2-3 sentences)
- Use concrete examples over abstract concepts

## Content Framework
1. Hook — grab attention in line 1
2. Problem — what pain point?
3. Solution — actionable advice
4. Proof — data or examples
5. CTA — what's next?

## Quality Check
Before publishing:
- Does it provide genuine value?
- Is it better than top 3 Google results?
- Would I share this with a colleague?
Enter fullscreen mode Exit fullscreen mode

Get Started in 5 Minutes

  1. Create a file called SOUL.md in your agent's directory
  2. Start with the 5 sections above
  3. Be specific — "helpful" is not a personality
  4. Test with 5-10 real conversations
  5. Iterate based on what works

Want Ready-Made Templates?

Writing SOUL.md from scratch takes time. If you want to skip ahead:

Or get everything in the Complete Bundle ($29) — 9 products, normally $80.90.

Recommended Tools

What's in your SOUL.md? Drop a comment with your best configuration tip.

Top comments (0)