> ## Documentation Index
> Fetch the complete documentation index at: https://mantle.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 [Mantle](https://mantle.rasa.com/mantle.md) reads to decide when to route
  to this skill. Name the subject it covers first, then what it does with it.
* 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 order.

## Writing good instructions

Say what to achieve rather than what to avoid, let the LLM choose the words,
refer to tools as `@tool.<name>`, and keep one job per skill.

[Writing prose](https://mantle.rasa.com/best-practices/writing-prose.md) covers this in full, including how
to word a `description` so the right skill gets picked.

Write each skill once: the same instructions run on
chat and voice. Spoken style comes from
[`orchestrator.voice_rules`](https://mantle.rasa.com/reference/agent-yml#orchestrator) in `agent.yml`, not from the
skill. Setting `voice_rules` replaces the built-in voice rules, so copy any you
want to keep. See [Designing for voice](https://mantle.rasa.com/voice/designing-for-voice.md).

## 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](https://mantle.rasa.com/build-guide/scoped-instructions.md): show only the
  relevant branch with `if:` markers.
* [Tool constraints](https://mantle.rasa.com/build-guide/tool-constraints.md): block a tool until a value
  exists.
* [Ordered blocks](https://mantle.rasa.com/build-guide/ordered-blocks.md): 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.

## Reference

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.