📄 What is SOUL.md?

SOUL.md defines your agent's personality, values, and behavioral boundaries. It's the "who you are" file — read every session, it shapes every response. A bad SOUL.md causes generic, inconsistent, or hallucinated behavior. A good one makes your agent feel like a real collaborator.

📄 What is AGENTS.md?

AGENTS.md defines your agent's operational protocol — what to do on startup, how to handle memory, safety rules, tool usage, and session behavior. Think of SOUL.md as personality and AGENTS.md as process.

🧩 SOUL.md Anatomy

• Identity block — Name, role, one-line description. Anchors the agent's self-concept. Without this, agents default to generic "I'm an AI assistant" behavior.
• Personality traits — 3-5 adjectives with descriptions. These directly influence tone, word choice, and response style. Be specific: "concise" beats "helpful".
• Values — What the agent prioritizes. "Accuracy over speed" vs "Speed over perfection" produces very different behavior.
• Communication style — Formatting preferences, emoji usage, verbosity level. Prevents the agent from defaulting to walls of text.
• Boundaries — What the agent should NOT do. Explicit boundaries prevent hallucinated capabilities and overreach.
• Example behaviors — Concrete "when X happens, do Y" rules. The most powerful section — agents follow examples more reliably than abstract descriptions.

🧩 AGENTS.md Anatomy

• Startup sequence — What files to read, in what order. Prevents the "fresh session amnesia" problem.
• Memory system — How to persist context across sessions. Daily files vs long-term memory file.
• Safety rules — What requires confirmation, what's free to do. Critical for autonomy without chaos.
• Tool usage — How to use available skills and integrations. Platform-specific formatting rules.
• Heartbeat behavior — What to do during idle checks. Prevents the agent from being a passive lump.
• Group chat rules — When to speak, when to stay silent. Prevents the "responds to everything" problem.

⚠️ Common Mistakes

• Too vague — "Be helpful and nice" does nothing. Be specific: "Use bullet points, keep responses under 200 words, lead with the answer."
• Contradictory rules — "Be concise" + "Always explain your reasoning in detail" = confused agent.
• No boundaries — Without explicit limits, agents will try to do everything, including things they're bad at.
• Ignoring platform — Discord markdown ≠ GitHub markdown. Specify formatting per platform.
• No examples — Abstract personality descriptions are weak. "When the user asks about X, respond like Y" is strong.
• Copy-paste defaults — The default AGENTS.md is a starting point, not a finished product. Customize it.

✅ Best Practices

• Start from a template, then customize incrementally
• Test changes by having a conversation and seeing if behavior shifts
• Keep SOUL.md under 100 lines — agents lose focus on long configs
• Use concrete examples over abstract descriptions
• Review and update monthly as your needs evolve
• Version control your config files — git tracks what changed and when