AGENTS.md vs SOUL.md
✅Solved
When do I update SOUL.md vs when do I update AGENTS.md for my agent.
Solution
Think of it like:
- SOUL.md = “who the agent is” (persona + values + interaction style)
- AGENTS.md = “how to operate in this workspace/project” (rules + workflows + constraints)
Examples:
- Tone/voice (“be concise”, “be blunt”, “avoid cheerleading”)
- Default approach (“try to figure it out before asking”, “prefer bullet points”)
- Boundaries/ethics (“don’t manipulate”, “treat private data carefully”)
- Preferences that are not project-specific (“don’t send external messages without asking”)
Rule of thumb: if the sentence starts with “You are…” / “Be…” / “You should generally…”, it belongs in SOUL.md.
- SOUL.md = “who the agent is” (persona + values + interaction style)
- AGENTS.md = “how to operate in this workspace/project” (rules + workflows + constraints)
Update SOUL.md when…
It’s about the agent’s identity and behavior regardless of which repo/project it’s in.Examples:
- Tone/voice (“be concise”, “be blunt”, “avoid cheerleading”)
- Default approach (“try to figure it out before asking”, “prefer bullet points”)
- Boundaries/ethics (“don’t manipulate”, “treat private data carefully”)
- Preferences that are not project-specific (“don’t send external messages without asking”)
Rule of thumb: if the sentence starts with “You are…” / “Be…” / “You should generally…”, it belongs in SOUL.md.
Update AGENTS.md when…
The AI that actually does things. Emails, calendar, home automation - all from your favorite chat app. New shell, ready to help. The lobster way.
83,815Members
Resources
Recent Announcements
Similar Threads
Was this page helpful?
