> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnao.io/llms.txt
> Use this file to discover all available pages before exploring further.

# System Prompts

> Override or extend the agent's system prompt per surface from your context repo

Each bot surface (nao web Bot, Slack, Teams, Telegram, WhatsApp, and automations) ships with a built-in system prompt. You can customize or fully replace that prompt per surface by adding markdown files to an `agent/prompts/` folder in your context repo - no code changes or forking required.

Because the files live in your context repo, prompt changes are versioned with the rest of your context and stay reviewable in pull requests. `nao init` scaffolds the `agent/prompts/` folder for you with a `README.md` and an example `slack.md`.

## Per-surface files

Place any of these files in `agent/prompts/`:

| File            | Applies to                                                                 |
| --------------- | -------------------------------------------------------------------------- |
| `system.md`     | Every surface (nao web Bot, Slack, Teams, Telegram, WhatsApp, automations) |
| `slack.md`      | Slack Bot only                                                             |
| `teams.md`      | Teams Bot only                                                             |
| `telegram.md`   | Telegram Bot only                                                          |
| `whatsapp.md`   | WhatsApp Bot only                                                          |
| `automation.md` | Automation runs only                                                       |

Resolution order for a given surface:

1. The surface-specific file (e.g. `slack.md`), if present.
2. Otherwise `system.md`, if present.
3. Otherwise nao's built-in default prompt.

The nao web Bot has no surface-specific file - it uses `system.md` when present, otherwise the built-in default.

<Tip>
  Prompt files are read fresh on every run, just like `RULES.md`. You can edit a prompt and see the change on the next message without restarting nao.
</Tip>

## Replace vs. extend: `{{ nao_prompt }}`

By default, a prompt file **fully replaces** the built-in prompt for that surface.

To **keep** the default and only add to it, include the `{{ nao_prompt }}` placeholder. At runtime it expands to nao's default prompt for that surface (in `slack.md` it expands to the default Slack prompt, in `system.md` to the web prompt, and so on). The placeholder tolerates whitespace variations (`{{nao_prompt}}` or `{{ nao_prompt }}`) and can appear more than once.

Extend the default Slack prompt - `agent/prompts/slack.md`:

```markdown theme={null}
{{ nao_prompt }}

## Extra Slack guidance
- Always start the answer with a one-line TL;DR.
- Link the source dashboard when one exists.
```

Fully replace the default for every surface - `agent/prompts/system.md`:

```markdown theme={null}
You are the ACME analytics assistant. Answer only with figures sourced
from the `prod_finance` schema, and never speculate beyond the data.
```

Without `{{ nao_prompt }}`, the file content becomes the entire prompt.

<Info>
  Internal runs that pass an explicit system prompt (for example, context recommendations) are not affected by these overrides.
</Info>

**Next Steps**

<CardGroup cols={2}>
  <Card title="Rules" icon="list-check" href="/nao-agent/context-builder/rules-context">
    Shape per-message behavior with RULES.md
  </Card>

  <Card title="Custom Context" icon="folder-tree" href="/nao-agent/context-builder/custom-context">
    Organize your context repo however works best
  </Card>
</CardGroup>