System Prompt

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.

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.

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

File Reference

Language

Tools

Runtime

Prompts

Assembly order

Situations

Sections that carry runtime data

The separate LLM calls

See also

​Assembly order

​Situations

​Sections that carry runtime data

​The separate LLM calls

​See also

Assembly order

Situations

Sections that carry runtime data

The separate LLM calls

See also