# 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.

Canonical page: https://themachine.myapps.ai/docs/desktop/bots/soul

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

![The Soul section of a bot's settings, with standing instructions filled in](/images/docs/desktop/bot-soul.webp)

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

```text
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

```text
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

```text
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

```text
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:

1. Open a chat with the bot.
2. Send `/setup` (or click **Set up with the bot** in the **Overview**
   section of its settings).
3. 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](/docs/desktop/bots/group-chats)** | 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](/docs/desktop/bots/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](/docs/desktop/integrations/secrets-and-webhooks): they're
write-only and never appear in conversations.