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

# responses.yml

> Named response templates, memory interpolation, and how they are delivered.

`responses.yml` holds named text templates the framework delivers verbatim. Use
it for wording that must be exact: legal disclosures, compliance notices,
regulated confirmations. Everything else should stay prose so the agent sounds
natural.

```yaml skills/card_replace/responses.yml theme={null}
responses:
  utter_ask_shipping:
    - text: >-
        How would you like the new card shipped: rush delivery in 1 to 2
        business days, or standard in 5 to 7?

  utter_card_replace_completed:
    - text: >-
        All set. Your replacement card has been ordered and will ship via
        {session.card_replace.order_shipping_summary} delivery.
```

The top-level key is `responses:`. Each name maps to a **list**, and the first
entry in that list is the response delivered. An entry is either a mapping with
a `text` key, or a plain string:

```yaml theme={null}
responses:
  utter_goodbye:
    - "Thanks for calling. Goodbye!"
```

## Where the file lives

| Location                          | Scope                  |
| --------------------------------- | ---------------------- |
| `skills/<id>/responses.yml`       | Declared by that skill |
| `responses.yml` at the agent root | Declared project-wide  |

At load, every file is merged into **one flat registry**, later sources
overriding earlier ones on duplicate names:

1. Packaged system defaults
2. Each bundled default skill's `responses.yml`
3. Each project skill's `responses.yml`, in directory order
4. The project-root `responses.yml`

This is how you override a built-in message: declare the same response name in
your own file. Redefining `utter_greet`, for example, replaces the greeting the
bundled `default_session_start` skill delivers.

Because the registry is flat, response names are global rather than scoped to
the skill that declares them. Prefix names with the skill (`utter_card_replace_completed`)
so two skills keep their wording distinct.

## Interpolation

A placeholder in braces is replaced with a memory value at delivery time. Two
forms work, and they resolve differently:

| Placeholder                     | Resolves against                                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `{session.<namespace>.<entry>}` | Everything the active skill can read: its own fields, other skills' `public` fields, and project memory |
| `{entry}`                       | The active skill's own schema first, then project memory                                                |

```yaml theme={null}
utter_confirm_order:
  - text: |
      Card: {session.project.selected_card_label}
      Reason: {session.card_replace.replacement_reason}
      Shall I place the order?
```

Use the namespaced form to read another skill's `public` field. The bare form is
convenient for a skill's own entries and follows the same resolution order a
tool's `context.memory.get()` uses.

A placeholder whose value is unset at delivery time is left in the text as
written, so interpolate only values you know are set by the time the response is
sent, typically ones written earlier in the same ordered block.

Interpolation applies to responses. Prose in `skill.md` is not interpolated;
refer to a value in words there, since the LLM can already see memory.

### `metadata.rephrase`

A response may opt into being reworded by the LLM instead of delivered verbatim:

```yaml theme={null}
responses:
  utter_ask_shipping:
    - text: "Rush or standard shipping?"
      metadata:
        rephrase: true
```

With `rephrase: true` the orchestrator makes a tool-free LLM call to reword the
text in context, and falls back to the literal text if that call fails or comes
back empty. Leave it off (the default) for anything compliance-sensitive: that
is the entire point of declaring the response.

## How a response is delivered

Four things reference a response by name:

| Reference                                         | Where it is declared               | Delivered when                                                                  |
| ------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
| `utter:` trigger                                  | `skill.md` frontmatter             | The skill activates (`on: activate`), or a `when:` condition first becomes true |
| `on_success:` / `on_failure:`                     | A `tool_constraints` entry         | After that tool succeeds or fails                                               |
| `utter_for_confirmation` / `utter_on_user_denial` | A `requires_confirmation:` mapping | When the engine asks for approval, and when the customer declines               |
| `action:` / `utterance:`                          | An ordered-block step              | The step runs                                                                   |

The two step fields differ:

```yaml theme={null}
:::ordered_block id=main
steps:
  - id: present_cards
    action: utter_present_card_list      # deliver the response, then advance
    next: collect_card

  - id: collect_card
    collect: selected_card_label
    utterance: utter_ask_which_card      # the question for a collect step
:::
```

| Step field                | Use                                                     |
| ------------------------- | ------------------------------------------------------- |
| `action: utter_<name>`    | Deliver the response, then advance                      |
| `utterance: utter_<name>` | On a `collect:` step, the question asked for that value |

`utter:` is accepted as a step-level alias for `action:` and is normalised at
load. Prefer `action:`.

`rasa train` validates every response name referenced from any of the four
places above, so a name that is not in the registry is caught before the agent
runs.

## See also

* [Responses concept](/docs/maestro/concepts/responses): when to declare wording
* [skill.md](/docs/maestro/reference/skill-md): the `utter:` trigger and `tool_constraints` shapes
* [Ordered block steps](/docs/maestro/reference/ordered-block-steps): the step fields that deliver responses
* [Conditions](/docs/maestro/reference/conditions): the namespaced reference form