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

# skill.md

> Complete reference for the skill file: frontmatter properties and body format.

`skill.md` is the only required file in a skill folder. It is YAML frontmatter
followed by a markdown body.

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

import_tools:
  - get_customer_info
  - mcp/banking:get_balance

tool_constraints:
  - lock_card:
      requires: "session.card_replace.selected_card_id"
---

Help the customer replace a credit card.
```

The file **must** open with `---` on the first line and close the frontmatter
with a second `---`. A missing delimiter fails with
`skill.markdown.invalid_frontmatter_delimiter`.

## The skill id is the folder name

The skill id — used for routing, memory namespacing, and `@skill.` references — is always the **parent directory name**, never the `name:` field.

A skill in `skills/card_replace/` with `name: Card Replace` is:

* referenced in prose as `@skill.card_replace`
* namespaced in memory as `session.card_replace.<entry>`

Skill ids starting with `builtin_` are reserved for bundled skills. `rasa data validate` rejects any other project skill with that prefix and tells you to rename the directory. Replacing a bundled skill is still allowed when the folder uses that skill's exact id, such as `builtin_completed`.

The folder names `session_start`, `session_end`, and `silence_timeout` are reserved too. Each is an engine message (`/session_start`, `/session_end`, `/silence_timeout`), so validation rejects a skill with that id. See [Start a skill from a message](https://mantle.rasa.com/reference/execution-loop.md#start-a-skill-from-a-message).

## Frontmatter properties

| Property | Required | Type | Description |
| - | - | - | - |
| `name` | Yes | string | Human-readable display name |
| `description` | Yes | string | What the skill does. The orchestrator routes on this. |
| `precondition` | No | string | Semantic name bound in [`agent.yml` `orchestrator.preconditions`](https://mantle.rasa.com/reference/agent-yml#preconditions) |
| `hidden` | No | bool | Omit from routing; `call:` / `link:` / `resolve_with` may still start it |
| `complete_when` | No | mapping | Skill completion contract (`condition` and/or `criteria`) |
| `import_tools` | No | list of strings | Shared project-root tools, a named MCP tool, or an MCP name pattern |
| `tool_constraints` | No | list | Per-tool gating, confirmation, and outcome rules |
| `utter` | No | list | Verbatim responses fired on skill activation or a memory condition |
| `disabled` | No | bool | Exclude the skill from routing without deleting it |
| `always_include_in_prompt` | No | bool | Keep this skill in the routing catalogue when skill retrieval is on |

Unknown keys (for example a `descripton:` typo) fail compile with
`skill.markdown.unknown_frontmatter_key`. `name` and `description` must be YAML
strings — a number or boolean is rejected the same way a non-boolean `hidden`
is.

Write `description` as a routing summary, including the phrasings a customer
would actually use. Skill retrieval embeds the skill `name` and this text
(and, by default, the skill's memory field schema).

Skill-level `requires` is not supported. Use `precondition` when another skill
must run first, `hidden: true` to keep a skill off the routing catalogue, and
`tool_constraints` `requires:` to gate tools.

### `precondition`

A semantic name. Bind it in [`agent.yml`](https://mantle.rasa.com/reference/agent-yml#preconditions)
(`orchestrator.preconditions`) so the engine parks this skill, runs `resolve_with`,
then continues or abandons. When `resolve_with` is already running, the engine
reuses that skill instead of interrupting it.

```yaml theme={null}
precondition: customer_authenticated
```

Values the user states in the starting message never satisfy this check. A
precondition should not name the skill's own memory fields. See [the precondition
check](https://mantle.rasa.com/reference/tools.md#precondition-check).

### `hidden`

When `true`, the skill is omitted from the routing catalogue. Deterministic
`call:` / `link:` steps and a precondition `resolve_with` may still start it.
Prose `@skill` mentions of a hidden skill fail validation.

```yaml theme={null}
hidden: true
```

### `complete_when`

Skill-level completion contract. The engine checks it when `complete` runs. It
is not shown to the model. The model already has general guidance for when to
call `complete`. Leave that guidance out of the skill body unless a step that
looks finished is not the real end. See
[State when the skill is finished](https://mantle.rasa.com/best-practices/when-prose-is-not-enough.md#state-when-the-skill-is-finished).

Must be a **mapping** with at least one of:

| Key | Type | Meaning |
| - | - | - |
| `condition` | condition string | Must be true before `complete` can succeed |
| `criteria` | list of sentences in natural language | All must pass a completion check on `complete` |

```yaml theme={null}
complete_when:
  condition: "session.card_replace.replacement_submitted"
  criteria:
    - "Fraud review was offered when the card was stolen or lost."
```

Prefer **one check per list item** — a single duty you can verify from the
conversation (a tool ran, a required question was asked, and so on). Several
short items work better than one long sentence that combines duties with "and"
or "or". Put memory logic in `condition:`; keep `criteria` for things that need
reading the conversation. Duplicate strings are rejected at compile time. When a
check fails, the tool error can name that item so the agent knows what to do
next.

Bare strings are rejected at compile time. Skill-level `complete_when` also
requires an **autonomous or hybrid** skill (one with LLM-driven prose steps).
Fully controlled ordered-block-only skills complete via block `END` without
this gate — remove skill-level `complete_when`, or add an autonomous/hybrid
step and exit via `complete`.

When authored:

* `complete` is **hard-gated**: unmet condition or failed criteria return a
  tool error and leave the skill active.
* While an [ordered block](https://mantle.rasa.com/build-guide/ordered-blocks.md) is active,
  `complete` is not offered. The engine finishes the block via `END`; a
  hybrid skill offers `complete` again after returning to prose.
* While a tool confirmation is pending for the active skill, `complete` is
  refused — the LLM needs to resolve the tool confirmation first.
* `cancel` is never gated by `complete_when`.
* Condition only (no `criteria`): the skill auto-completes when the
  condition becomes true.
* Non-empty `criteria`: auto-complete is disabled; exit only via a successful
  `complete` (condition + judge). The judge **fails closed**: if the check
  times out, errors, or returns a malformed answer, `complete` is refused
  (the skill stays active) rather than treated as complete.

Step-level `complete_when` on ordered-block `instructions:` steps is a plain
[condition](https://mantle.rasa.com/reference/conditions.md) string — no mapping, no `criteria`.

If you want to ensure that certain ordered blocks finished before a skill
completes, add the corresponding `criteria`.

### `import_tools`

Allowlist of tools this skill may use beyond its own auto-discovered
`tools.py` / `tools/*.py`. Each entry is one of:

| Form | Meaning |
| - | - |
| `get_customer_info` | A shared `@tool` from the agent-root `tools/` folder |
| `mcp/<server-id>:<tool-name>` | One tool from an MCP server declared under [`mcp_servers`](https://mantle.rasa.com/reference/integrations-yml#mcp_servers) |
| `mcp/<server-id>:*` | Every tool that server lists when the agent starts or reloads |
| `mcp/<server-id>:<prefix>*` | Every listed tool whose name starts with `<prefix>` |

```yaml theme={null}
import_tools:
  - get_customer_info             # from tools/*.py at the agent root
  - mcp/banking:get_balance       # one remote tool on server id `banking`
  - mcp/banking:card_*            # listed tools whose names start with card_
```

Tools in the skill's own `tools.py` or `tools/*.py` are auto-discovered and must
not be listed. A shared tool that is not declared here is not attached. An MCP
tool is attached only when this skill names it, or when its name matches a
pattern on that server.

A prefix is letters, digits, `_`, and `-`, at most 63 characters, then a single
trailing `*`. `mcp/<server>:*` is that form with an empty prefix. `rasa train`
rejects any other `*`, including `mcp/banking:card*status*`, `mcp/banking:**`, and
a prefix character that a tool name cannot contain. A `?` is not a pattern.

For a named MCP entry, the LLM and `tool_constraints` see the **bare** tool
name (`get_balance`). Name it in prose the same way you name a local tool. The
`mcp/<server>:` prefix is only for the allowlist and for resolving which server
to call.

A pattern does not name a tool. To name a tool that a pattern admits, also add
its concrete import, such as `mcp/banking:card_status`. That applies to an
`@tool.card_status` reference in the body, a `tool_constraints` entry, an
ordered-block `tools:` entry, an `execute_tool` step, and a button `source`.
Without it, `rasa train` reports the name as an unresolved tool. The same
server keeps that tool once.

On a shared server, put the prefix on the skill that owns that set of tools.
`mcp/banking:card_*` admits the card tools. `mcp/banking:*` admits every tool
the server lists.

#### Collisions and load failures

Within one skill, bare names must be unique across local tools, shared imports,
and MCP imports. `rasa train` fails when:

* Two concrete `import_tools` entries resolve to the same bare name (for example
  `mcp/a:echo` and `mcp/b:echo`, or `mcp/banking:get_balance` next to a local
  `get_balance`)
* An MCP entry references a server id missing from `integrations.yml`
* A concrete MCP tool name is not a valid LLM function name. The tool name is
  sent to the model as-is, so it may only contain letters, digits, `_`, and `-`
  (at most 64 characters). A remote tool named `get.balance` cannot be imported
  by name, even though the server id may contain dots.
* A pattern is malformed

Train does not connect to the server, so it does not check which names a
pattern will admit.

Connecting, authenticating, and listing tools happens when the agent starts or
the model reloads. If that connection fails, startup stops. A concrete import
whose tool is missing also stops startup. A reload that fails this check keeps
the previous model running.

A pattern is applied to the list from the server:

* A listed name that matches is attached under its bare name, with the same
  schema, dispatch, and `tool_executed` event as a named import. `mcp_server`
  is the server id. A `tool_constraints` entry applies once the name also has
  a concrete import.
* The same tool from the same server, from a named import or from overlapping
  patterns, is attached once.
* A match that collides with a local or shared tool, a reserved framework or
  execute-only name, or the same bare name from another server stops startup.
  The error names the skill, the pattern, and the tool. On reload, the previous
  model keeps running.
* A match that is not a valid LLM function name, including a name longer than
  64 characters, is left out and startup continues.
* A pattern that matches nothing logs a warning and startup continues.
* A tool added on the server later is attached on the next start or model
  reload. The list is not refreshed while the agent is running.

After start or reload, `mantle.mcp.import_pattern.resolved` lists the names a
pattern attached. `mantle.mcp.import_pattern.no_match` and
`mantle.mcp.import_pattern.skipped` are warnings.

The Inspector skill document's **Available tools** row lists tools the skill
names outright, then each import pattern, such as `mcp/banking:card_*`, marked
as a pattern rather than a tool. It does not list the tools a pattern admitted. Those appear on the turn, as the bare
names the model was offered.

The same `mcp/<server>:<tool>` string may appear in more than one skill. Each
skill that needs the tool must list it in its own `import_tools`.

To share a Python tool across skills, define it once in the agent-root `tools/`
folder and declare it in each skill's `import_tools`.

See [Import MCP tools](https://mantle.rasa.com/concepts/tools.md#mcp-tools) for a short end-to-end example.

### `tool_constraints`

A list of single-key mappings, tool name to options. The key is a concrete
tool name. A pattern such as `card_*` is not a key; import
`mcp/banking:card_status` beside the pattern and constrain `card_status`.

```yaml theme={null}
tool_constraints:
  - lock_card:
      requires: "session.card_replace.selected_card_id"
  - process_card_replacement:
      requires: "session.card_replace.shipping_type"
      requires_confirmation:
        enabled: true
        utter_for_confirmation: utter_ask_replacement_confirmation
      on_success: utter_replacement_disclaimer
```

| Option | Description |
| - | - |
| `requires:` | Condition string. The tool is hidden from the LLM and blocked at dispatch until it holds. |
| `requires_confirmation:` | Mapping. `enabled: true` pauses the call for explicit approval, resumed via `resolve_tool_confirmation`. Optional `utter_for_confirmation` / `utter_on_user_denial` name responses; omit them to let the LLM phrase the ask. For irreversible tools, prefer `set:session.system.confirmation=true` / `=false` buttons on that question — a tap agrees or declines without free-text interpretation and without writing a memory field. Do not also instruct the model in the skill body to ask for confirmation — that produces two prompts. See [Tool Constraints](https://mantle.rasa.com/build-guide/tool-constraints.md#explicit-confirmations). |
| `on_success:` | Response name delivered after the tool succeeds. |
| `on_failure:` | Response name delivered after the tool fails. |

See [Tool Constraints](https://mantle.rasa.com/build-guide/tool-constraints.md) for worked examples.

An entry that is not a single-key mapping, or whose options are not a mapping,
fails with `skill.markdown.invalid_tool_constraints`.

### `utter`

Fires a verbatim response from `responses.yml` on a skill lifecycle event or
when a memory condition first becomes true:

```yaml theme={null}
utter:
  - utter_recording_notice:
      on: activate
  - utter_stolen_warning:
      when: "session.card_replace.replacement_reason == 'stolen'"
```

| Trigger | Fires |
| - | - |
| `on: activate` | When the skill becomes active |
| `when:` | The first time the condition becomes true after a memory write |

An entry may set both. These are distinct from a tool's `on_success:` /
`on_failure:`, which attach to a gated tool in `tool_constraints`.

> [!WARNING]
>
> `on: activate` delivers the response **after** this skill's memory is reset for
> the new run. Conditional variants that read this skill's fields see
> `initial_value` (or `null`) — not a previous run's values — so they typically
> fall through to the default variant. Prefer project memory or a matching
> `initial_value` for activation CRVs; use `when:` for skill values written after
> activation. See
> [Conditional variants](https://mantle.rasa.com/reference/responses-yml.md#conditional-variants).

### `disabled`

```yaml theme={null}
disabled: true
```

The skill loads but is excluded from routing. Useful for parking a
work-in-progress skill without deleting it.

### `always_include_in_prompt`

```yaml theme={null}
always_include_in_prompt: true
```

When [skill retrieval](https://mantle.rasa.com/reference/agent-yml.md#skill_retrieval) is on, this skill's
startable entries stay in the routing catalogue and `activate` list even if
search did not retrieve it. Default is `false`.

`hidden`, `disabled`, and engine-managed still win: an always-included skill is
omitted when it is not in the legal routing catalogue. This is a skill-level
flag only — not an ordered-block property.

## Body format

The body is markdown. It supports:

### Prose paragraphs

Always visible to the LLM. Blank lines separate paragraphs; each paragraph is a
scoping unit.

### `if:` markers

A paragraph whose **first line** is `if: <condition>` is included only when the
condition holds:

```markdown theme={null}
if: session.card_replace.replacement_reason == 'stolen'
Tell the customer the card will be locked for their protection.
```

The marker scopes only the paragraph directly beneath it, up to the next blank
line. Write one `if:` paragraph per case; for exclusive either/or branching, use
an ordered block's `next:` branches.

### Memory in prose (`@memory`)

To put a **live memory value** into LLM-facing instructions, use:

| Token | Meaning |
| - | - |
| `@memory.project.<field>` | Project memory |
| `@memory.<skill_id>.<field>` | That skill's field under normal access rules |

Access matches what the active skill can read elsewhere: project fields; other
skills' **public** fields; this skill's **public and private** fields. Another
skill's private fields and `@memory.system.*` are rejected at train time.

At prompt build the engine replaces the token with the current value (same
stringification as the [`### Memory:`](https://mantle.rasa.com/reference/prompt-templates) and
[`### Project Memory`](https://mantle.rasa.com/reference/prompt-templates) listings). Unset
or unreadable references are left as the literal token and logged. For a set
PII field, the **whole token** is replaced with `[set]` (for example
`Contact @memory.project.phone` becomes `Contact [set]`). That differs from
the Project section, which lists `project.phone: [set]` as a line.
Incomplete forms such as `@memory.project` (missing the field segment) cannot
be substituted — `rasa train` fails.

Example:

```markdown theme={null}
Use the already chosen card @memory.card_replace.selected_card_id for this request.
```

Keep `session.*` for `if:` conditions and structured YAML (for example tool
parameters). Putting bare `session.*` in free prose also fails train — use
`@memory.…` instead. Response templates still use `{session.*}` — see
[Responses](https://mantle.rasa.com/reference/responses-yml.md).

### Jumps to blocks and skills

| Token | Target | Behaviour |
| - | - | - |
| `@block.<block_id>` | An ordered block in **this** skill | Enters the block, returns to prose when it completes |
| `@skill.<skill_id>` | Another skill | Runs it and returns; parent resumes |

Both take the id: `@block.` names a block declared in the same file, and
`@skill.` names the target skill's **directory name**. Incomplete lookalikes
(`@skill`, `@block.foo.bar`, `@tool.lock.card`) cannot be substituted —
`rasa train` fails. Use exactly one segment after the prefix.

You can name a tool in plain prose or with `@tool.<name>` when you want the
exact callable spelled in the instructions. `rasa train` checks `@tool` tokens
in two steps: token shape must be exactly one segment after `@tool.` (see
incomplete lookalikes above), and the name must resolve to a tool visible while
this skill is active (skill-local and declared shared `@tool` functions, MCP
imports, and engine framework tools such as `set_memory`). A shape or name
mistake fails train instead of leaving literal `@tool…` text at runtime.

#### How the parent is parked

The engine parks the current skill differently depending on what put the new
one on top:

| Trigger | Parked as | Resumes |
| - | - | - |
| `@skill.<skill_id>` | Delegation | Automatically, when the referenced skill finishes |
| `@block.<block_id>` | Same-skill reference | Automatically, at the prose that entered the block |
| The user changing topic | Digression | The engine offers a resume and the customer decides |

A `@skill.` target must not be a `hidden` skill. Public memory is readable
across skills in every case, so the difference is control rather than data:
the first two are part of the skill's design, the third is the customer
steering the conversation.

### Ordered blocks

```
:::ordered_block id=pick_card
steps:
  - id: check_eligibility
    execute_tool: check_account_replacement_eligibility
  - id: END
:::
```

The id is a **fence attribute**. Duplicate ids in one file are an error, as is
setting `routable:` or `description` on the block. Routing uses the skill
description. A collect step may still set `description` for the value it asks
for. See [Ordered Blocks](https://mantle.rasa.com/build-guide/ordered-blocks.md) for step types.

Steps inside ordered blocks use the ordered-block step schema.
Unknown step properties are rejected at skill load and during
`rasa data validate` — misspelled or obsolete keys fail with a clear error
instead of being silently ignored.

Two removed collect-step keys have dedicated migration messages:

| Removed key | Use instead |
| - | - |
| `force_collection` | `ask_before_filling: true` |
| `tool:` on a collect step | Record values via the `set_memory` framework tool, optionally with a [`run_after_setting_<field>` memory validation tool](https://mantle.rasa.com/reference/tools#memory-validation-tools) in `tools.py`, or add a separate `execute_tool` step |

Any other unrecognized step property produces a generic validation error naming
the unknown key.

## A skill needs prose or a block

A `skill.md` with neither prose instructions nor an ordered block fails with
`skill.markdown.missing_instructions`.

Routing lists the skill id and the skill description. An ordered block has no
`description`. Training fails if a block still has one.

| Body | How it starts |
| - | - |
| Prose only | `activate` with the skill id starts the prose |
| Prose and blocks | `activate` starts the skill in its prose. Once it is active, `enter` switches from the prose to a block, or back |
| Blocks only | Exactly one entry block: the ordered block that no other block in the skill `call:`s or `link:`s. Its id can be anything. `activate` with the skill id starts that block. Training fails when there is no entry, more than one, or a block the entry cannot reach |

## Companion files

| File | Purpose |
| - | - |
| `memory.yml` | [Memory schema](https://mantle.rasa.com/reference/memory-yml.md) for this skill |
| `responses.yml` | [Response templates](https://mantle.rasa.com/reference/responses-yml.md) |
| `tools.py` or `tools/*.py` | [Tools](https://mantle.rasa.com/reference/tools.md), auto-discovered |
| `references/*.md` | Knowledge indexed for `search_knowledge` |

Each of the first three is scoped to the skill. `memory.yml` declares entries
under this skill's namespace, `tools.py` is attached to this skill, and
`responses.yml` merges into the shared registry under the names it declares.

### `references/` is project-wide

`skills/<id>/references/**/*.md` is indexed into the **same** index as the
agent-root `references/` folder, and `search_knowledge` queries that whole index
on every call whatever skill is active. The folder location decides where the
files sit in your project, and the index a search reads is the same either way.

Two consequences worth designing around:

* Whether `search_knowledge` is offered at all depends on the project having an
  index, not on the active skill having a `references/` folder.
* Each retrieved snippet reaches the model with its `source` file path and a
  `scope` of either `global` or the owning skill id. Hits are **sections of the
  file**, not the whole document. Write each document to stand on its own rather
  than relying on the skill it sits under to supply the context.

See [References](https://mantle.rasa.com/concepts/references.md) for the retrieval flow, chunking, and the
embedding model.

## See also

* [Conditions](https://mantle.rasa.com/reference/conditions.md): the expression grammar
* [Ordered Blocks](https://mantle.rasa.com/build-guide/ordered-blocks.md): step types and branching
* [References](https://mantle.rasa.com/concepts/references.md): how knowledge is indexed and searched
* [Import MCP tools](https://mantle.rasa.com/concepts/tools.md#mcp-tools): allowlisting remote tools
* [`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml#mcp_servers): MCP server config


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