I've reviewed hundreds of SOUL.md configurations. Most of them make the same mistakes. Here are the 7 most common ones — and the fixes that actually work.
Mistake 1: "You are a helpful assistant"
This is the #1 killer. It tells your agent absolutely nothing.
❌ Bad:
You are a helpful AI assistant.
✅ Good:
You are a senior DevOps engineer who specializes in Kubernetes and CI/CD pipelines. You explain complex infrastructure concepts using simple analogies. You always suggest the simplest solution first.
The more specific your identity, the better your agent performs.
Mistake 2: No Boundaries
Without boundaries, your agent will try to do everything — and do nothing well.
❌ Bad: No boundaries section at all.
✅ Good:
## Boundaries
- Never execute destructive commands without confirmation
- Don't give medical, legal, or financial advice
- If unsure, say so — don't guess
- Escalate to human when confidence < 70%
Mistake 3: No Output Format
Your agent's responses are inconsistent because you never told it how to format them.
✅ Fix:
## Output Format
- Always lead with the answer, then explain
- Use headers for sections longer than 3 paragraphs
- Code snippets: include language tag and comments
- Lists: bullet points for unordered, numbers for steps
Mistake 4: Too Long
A 500-line SOUL.md confuses the agent. It can't prioritize when everything is a priority.
✅ Fix: Keep it under 100 lines. Focus on the 20% of rules that drive 80% of behavior. Start with 20 lines and add only when you see a specific problem.
Mistake 5: No Decision Framework
Your agent doesn't know how to prioritize because you never taught it.
✅ Fix:
## Decision Framework
When multiple options exist:
1. Safest option first (never risk data loss)
2. Simplest solution (fewer moving parts = fewer bugs)
3. Most reversible (prefer actions you can undo)
Mistake 6: No Memory Rules
Your agent forgets important context because you didn't tell it what to remember.
✅ Fix:
## Memory
- Always remember: user preferences, project context, past decisions
- Update MEMORY.md after every significant interaction
- Never store: passwords, API keys, personal health info
Mistake 7: Never Updating It
Your SOUL.md should be a living document. If you wrote it once and never touched it again, it's probably outdated.
✅ Fix: Review your SOUL.md every 2 weeks. Add rules when you see repeated bad behavior. Remove rules that aren't needed anymore.
The Quick Fix Checklist
- [ ] Identity is specific (not "helpful assistant")
- [ ] Boundaries are explicit
- [ ] Output format is defined
- [ ] Under 100 lines
- [ ] Decision framework exists
- [ ] Memory rules set
- [ ] Updated in the last 2 weeks
Templates That Get It Right
Don't want to start from scratch? These templates avoid all 7 mistakes:
- Free: 5 Starter Templates — battle-tested basics
- 20 Premium Templates ($5) — production-ready
- Mega Pack: 100 Templates ($9.90) — every use case covered
Recommended Tools
Which mistake were you making? Let me know in the comments.
Top comments (0)