Write a bot's Soul
The Soul is a bot's standing instructions. Learn what to put in it, see examples for common roles, and let the bot write its own.
A bot's Soul is its standing instructions: a description of who it is and how it should work. The bot reads it at the start of every conversation, in every thread.
Think of it as the briefing you'd give a new colleague on their first day. Anything you'd otherwise have to repeat in every message belongs here.
Where to find it
Open the bot's settings (click its name in the chat header) and open Soul. The box is labelled Standing instructions (SOUL.md).
- A Soul with text in it is shown formatted, the way you'd read it. Click Edit to change it, and Done when you've finished.
- An empty Soul opens straight into the editor.
- Changes save automatically as you type.
Souls are written in Markdown, so you can use headings, bullet points, and bold text to organize longer instructions.
A counter under the box shows how long it is, up to 24,000 bytes (about 24,000 letters). If you go over the limit, the box turns red and you'll see not saved next to the counter. Nothing is saved until it fits again, so shorten it until the warning goes away.
Move long instructions out of the blurb
Older bots sometimes have their whole briefing in the one-line Blurb (under Identity). If a bot's blurb is long and its Soul is empty, the Soul section shows Move instructions into SOUL.md. Click it: the full text moves into the Soul, and the blurb keeps just its first sentence.
What to put in a Soul
A good Soul covers five things. You don't need all of them, and short is fine.
| Part | Ask yourself | Example |
|---|---|---|
| Role | What is this bot's job? | You are a marketing writer for Trailhead, a small outdoor-gear shop. |
| How to work | How should it approach tasks? | Before writing anything long, ask me one clarifying question. Show an outline first. |
| Preferences | What do you like? | Use British spelling. Keep emails under 150 words. Plain, friendly tone. |
| Limits | What should it never do? | Never send or publish anything without showing me first. Don't make up statistics. |
| Facts | What should it always know? | Our customers are mostly 30–55 and hike on weekends. Brand colors are forest green and cream. |
Tips
- Write it like you'd talk to a person. Plain sentences work best.
- Be specific. "Keep it short" is vague; "Keep replies under 5 bullet points" is clear.
- Say what to do, not only what not to do. "If you're unsure, say so and give your best guess" works better than "Don't be wrong."
- Tell it where to put results. "Save anything longer than a page as a Markdown file and tell me its name."
- Start small, then improve. When the bot does something you don't want, add a line to the Soul so it doesn't happen again.
Examples
Researcher
You are Scout, a market researcher for a 10-person software company.
Always cite your sources with links.
Lead with a 3-bullet summary, then the details.
When comparing products, use a table.
If something is uncertain, say so instead of guessing.
Save anything longer than a page as a Markdown file and tell me its name.Writer
You are a writer for our company blog and newsletter.
Audience: small-business owners who are busy and not technical.
Tone: warm, clear, practical. No jargon, no hype, no exclamation marks.
Use short paragraphs and descriptive subheadings.
Always show me an outline before writing a full draft.
Never publish or send anything. I do that myself.Personal assistant
You help me, Sam, run my week.
I work Monday to Friday, 9 to 5, Pacific time.
When I ask for a summary, give me the 3 most important things first.
Draft emails in my voice: friendly, brief, signed "Sam".
Ask before doing anything that costs money or contacts another person.Coding partner
You are a careful senior developer working on our TypeScript web app.
Explain your plan in 2-3 sentences before changing code.
Keep changes small and focused. Don't refactor unrelated code.
Run the tests after every change and tell me the result.
If a request is ambiguous, ask instead of guessing.Let the bot write its own Soul
Not sure what to write? Let the bot interview you:
- Open a chat with the bot.
- Send
/setup(or click Set up with the bot in the Overview section of its settings). - Answer its questions about what you want it to do.
The bot then writes its own Soul and settings. Read it afterwards and adjust anything you like.
Soul, messages, and group instructions
| Put it in… | When it applies |
|---|---|
| The Soul | Every thread with this bot, forever. |
| Your message | Just this request. |
| Group instructions | Every bot in one group chat, only in that group. |
If you notice you keep adding the same line to your messages, move it into the Soul.
Common questions
Do changes apply to conversations that are already running? They apply from the bot's next turn. Old replies aren't changed.
How do I check what the bot actually sees? Open Overview in the bot's settings and unfold Prompt preview. It shows the instructions the model gets at the start of every thread, and how big they are.
Why is there a goals list in my bot's Soul? Goals you add on the Responsibilities page are written into the Soul, so the bot always knows them. They also show under Looks after on the bot's profile card. Edit them on the Responsibilities page rather than by hand.
Can teammates see the Soul? Yes. The Soul is part of the bot's project on Machine, so anyone who can use the bot can see and edit it.
Should I put passwords or API keys in the Soul? No. Use secrets: they're write-only and never appear in conversations.