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

# Instructions

> The plain-language body of a skill that the LLM follows.

Instructions are the heart of a skill. You write them as plain language in the
body of `skill.md`, and the LLM reads them to run the conversation. This is where
every skill starts. No code, no config, just a clear description of the job.

## Where instructions live

The `skill.md` file has two parts: YAML **frontmatter** for metadata, and a
markdown **body** for the instructions.

```markdown skills/card_replace/skill.md theme={null}
---
name: Card Replace
description: Replace a credit card -- lost, stolen, damaged, or not received
---

Help the customer replace a credit card.

Check whether their account is eligible for replacement. If they have
multiple cards, ask which one. Ask why they need a replacement -- the valid
reasons are lost, stolen, damaged, or not received.

Once everything is gathered, ask their shipping preference, confirm the
order, and process the replacement.
```

* The **`description`** is what [Maestro](/docs/maestro/maestro) reads to decide when to route
  to this skill. Write it as a clear summary of what the skill does.
* The **body** is soft guidance the LLM interprets. Write it the way you'd brief
  a new teammate: what to do, what to ask, and in what rough order.

## Writing good instructions

* **Be specific about outcomes, not phrasing.** Say *what* to accomplish and let
  the LLM choose the words, unless you need exact wording, which belongs in
  [responses](/docs/maestro/concepts/responses).
* **Name tools plainly** when the LLM should take an action: "Ask for their
  account number, then call `check_balance`." The tool is already in the model's
  schema; naming it in prose is guidance, not a reference the compiler resolves.
* **Keep each skill focused.** One job per skill. If the body reads like two
  different tasks, split it into two skills.
* **Don't restate what a tool returns.** The LLM sees the tool result directly.

## Instructions are soft until you add control

At this stage everything is guidance. The LLM *can* call a tool early, skip a
step, or take the wrong branch. That's fine for most of a skill. Where a mistake
is expensive, layer on framework-enforced guarantees without touching the body:

* [Scoped instructions](/docs/maestro/build-guide/scoped-instructions): show only the
  relevant branch with `if:` markers.
* [Tool constraints](/docs/maestro/build-guide/tool-constraints): block a tool until a value
  exists.
* [Ordered blocks](/docs/maestro/build-guide/ordered-blocks): enforce a strict sequence.

<Note>
  Write one `if:` paragraph per case, each spelling out its own condition. For
  exclusive either/or branching, use an ordered block's `next:` branches.
</Note>

## Reference

For the full body syntax, covering `if:` markers, `@block` and `@skill`
references, and ordered-block fences, see the
[`skill.md` reference](/docs/maestro/reference/skill-md).