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

# System Prompt

> How Maestro assembles the system prompt each turn, and which agent.yml keys override each section.

Maestro builds the system prompt from a fixed set of sections, in a fixed order,
on every turn. Which sections appear depends on the situation: whether a skill is
active, whether a knowledge search has run, whether a tool is paused for
confirmation.

This page documents the assembly. For the full text of each assembled prompt, see
[Prompt templates](/docs/maestro/reference/prompt-templates).

## Assembly order

Sections are appended in this order. Anything conditional is skipped entirely
rather than rendered empty.

| # | Section                                                     | Included when                                                              | Override in `agent.yml`                         |
| - | ----------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------- |
| 1 | Agent header                                                | Always                                                                     | `agent.persona`, top-level `rules`              |
| 2 | Skills within this agent                                    | Always                                                                     | none                                            |
| 3 | Channel rules                                               | Always, branching on voice or text                                         | `prompts.voice_rules`, `prompts.text_rules`     |
| 4 | Tool-call acknowledgement                                   | `prompts.ack_enabled` is true, the default                                 | `prompts.ack_rule`, `prompts.ack_examples`      |
| 5 | Framework lifecycle tools                                   | Always. Content tracks which tools are offered                             | none                                            |
| 6 | Out-of-scope handling                                       | `cannot_help` is offered **and** the scope handler is not the active skill | none                                            |
| 7 | Active skill, knowledge answering, **or** routing catalogue | Exactly one of the three                                                   | `prompts.routing_no_active_skill`, routing only |
| 8 | Pending tool confirmation                                   | A tool with `requires_confirmation:` is paused                             | none                                            |

Section 7 is the branch that gives each situation its character. A skill is
active, so its instructions are rendered; or a knowledge search has run this
turn, so the compact answer-from-knowledge section replaces them; or no skill is
active, so the routing catalogue is rendered instead.

The `prompts` keys in the table replace their section's built-in default text.
Leaving one unset keeps the default. See
[`agent.yml`](/docs/maestro/reference/agent-yml#prompts).

## Situations

| Situation                | Section 7 renders   | Notable                                                                  |
| ------------------------ | ------------------- | ------------------------------------------------------------------------ |
| No skill active          | Routing catalogue   | Skill descriptions and their `requires:`, plus `conversation.before_end` |
| Prose skill active       | Active skill        | Instructions after `if:` filtering, memory values, correction guidance   |
| Inside an ordered block  | Active skill        | The block's steps and the current step, rather than prose                |
| After `search_knowledge` | Knowledge answering | Compact. The skill's own tools are withheld for the rest of the turn     |
| Scope handler active     | Active skill        | Out-of-scope handling is omitted, since declining is already underway    |

Pending tool confirmation can sit on top of any of these five.

## Sections that carry runtime data

Some sections are pure framing and some are filled from live conversation state.
The templates only supply the framing. Everything below comes from your compiled
skills and the current tracker:

* Skill instructions and step text, from `skill.md`
* Memory entry names, descriptions, and current values
* Routing catalogue entries, from each skill's `description` and `requires:`
* Paused work, from the stack. See below
* The confirmation question, from `utter_for_confirmation`

Paused work covers three cases, each listed with the id the model needs to
return to it:

| In the prompt as      | What it is                                                                                               |
| --------------------- | -------------------------------------------------------------------------------------------------------- |
| Paused parent skill   | A skill that referenced another with `@skill.<id>` and is waiting for it to finish                       |
| Paused ordered blocks | A block entered from prose with `@block.<id>`, waiting to be resumed                                     |
| Interrupted tasks     | Skills the customer started and left part-way by changing topic. The model can offer to pick one back up |

The first two resume on their own when the work they are waiting on completes.
An interrupted task resumes only if the customer wants it to, which is why the
prompt lists them: the model needs the ids to make that offer. See
[Skills & Routing](/docs/maestro/maestro/skills#the-skill-stack).

This is why two agents running the same engine version see prompts that look
very different. The framing is identical, the content is yours.

## The separate LLM calls

Not every model call uses the main system prompt. Four others exist, each with a
much smaller prompt:

| Call             | When                                                                         | Prompt                                                                 |
| ---------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Rephrase         | A response sets `metadata.rephrase: true`                                    | Header, a rephrase task line, and channel rules. No tools              |
| Confirm rephrase | A `collect:` step confirms a value that is already filled                    | The same shell, with a trailing instruction naming the field and value |
| Ack reminder     | First LLM iteration of a turn, when `ack_enabled` and no active collect step | A single injected system message, not part of the system prompt        |
| Memory discovery | After the reply has been sent, on turns that changed which skill is active   | Its own task template                                                  |

The rephrase calls are given no tools at all, which is what makes them safe for
verbatim wording: the model can only return text.

Memory discovery is the one that sits outside the turn. It runs once the agent's
reply has already gone out, so it never adds to the customer's wait, and it is
best-effort: a failure is logged and the turn still counts as successful.

## See also

* [Prompt templates](/docs/maestro/reference/prompt-templates): the full text of each assembled prompt
* [`agent.yml`](/docs/maestro/reference/agent-yml): `persona`, `rules`, and every `prompts` key
* [Execution Loop](/docs/maestro/reference/execution-loop): where prompt building sits in the turn
* [Tools](/docs/maestro/reference/tools): the built-in framework tools the prompt describes