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

# Authoring files

> JSON Schema for the Mantle files you write, and the npm package that versions them.

Most files here are the machine-readable contract for the YAML and `skill.md`
frontmatter you write. Each of those schemas is generated from the model for
that file.

The exception is [python-decorators.json](https://mantle.rasa.com/reference/schemas/python-decorators.json).
It is the contract for the `@tool` and hook decorators you write in Python. It
is generated from the decorator definitions and the hook point catalogue, not
from a YAML model, and it is not a YAML file schema.

The [File Reference](https://mantle.rasa.com/reference/project-structure.md) pages explain what the fields
mean. Open the JSON file for the fields themselves.

These pages are the current `main` contract. They change with `main` and are
not pinned to a Rasa release.

The versioned contract is the npm package `@rasahq/mantle-authoring-schemas`.
Install the version that matches the Rasa release you run. The `main` dist-tag
tracks these pages. The `latest` dist-tag matches the last Rasa release.

A breaking change keeps accepting the old shape for at least one Rasa
release. During that release the loader logs a deprecation warning that names
the file, the old key, and the new one. Each breaking change ships a migration
note in the [Mantle changelog](https://mantle.rasa.com/changelog.md).

| Schema | What it describes | Reference |
| - | - | - |
| [agent-yml](https://mantle.rasa.com/reference/schemas/agent-yml.json) | Project `agent.yml`, including `orchestrator.preconditions` | [agent.yml](https://mantle.rasa.com/reference/agent-yml.md) |
| [integrations-yml](https://mantle.rasa.com/reference/schemas/integrations-yml.json) | Project `integrations.yml` | [integrations.yml](https://mantle.rasa.com/reference/integrations-yml.md) |
| [memory-yml](https://mantle.rasa.com/reference/schemas/memory-yml.json) | Project `memory.yml`: a flat map of field name to declaration | [memory.yml](https://mantle.rasa.com/reference/memory-yml.md) |
| [skill-memory-yml](https://mantle.rasa.com/reference/schemas/skill-memory-yml.json) | A skill's `memory.yml`, with `schema.public` and `schema.private` | [memory.yml](https://mantle.rasa.com/reference/memory-yml.md) |
| [responses-yml](https://mantle.rasa.com/reference/schemas/responses-yml.json) | Project or skill `responses.yml` | [responses.yml](https://mantle.rasa.com/reference/responses-yml.md) |
| [ordered-block](https://mantle.rasa.com/reference/schemas/ordered-block.json) | One `:::ordered_block` body | [Ordered block steps](https://mantle.rasa.com/reference/ordered-block-steps.md) |
| [skill-md-frontmatter](https://mantle.rasa.com/reference/schemas/skill-md-frontmatter.json) | The YAML frontmatter of `skill.md` | [skill.md](https://mantle.rasa.com/reference/skill-md.md) |

This catalog is those files. Conversation events are a separate contract; see
[Conversation events](https://mantle.rasa.com/reference/events.md).

## Install

The virtual `rasa-npm` repository is public. Add this to the project
`.npmrc`:

```ini theme={null}
@rasahq:registry=https://europe-west3-npm.pkg.dev/rasa-releases/rasa-npm/
```

```bash theme={null}
npm install @rasahq/mantle-authoring-schemas@<rasa-version>
```

`<rasa-version>` is the Rasa release you run. `@main` tracks these pages.

## Check a file in your editor

Editor checks need Node.js and npm on your machine. Any current LTS is enough.
Running or training an agent does not need Node. VS Code and Cursor need the
Red Hat YAML extension. JetBrains uses its JSON Schema mapping. Point that
mapping at the schema file inside this project's `node_modules`, so the schema
applies only to this project.

In VS Code or Cursor, add this to `.vscode/settings.json`. Project `memory.yml`
and a skill's `memory.yml` use different schemas.

```json theme={null}
{
  "yaml.schemas": {
    "./node_modules/@rasahq/mantle-authoring-schemas/schemas/agent-yml.json": "agent.yml",
    "./node_modules/@rasahq/mantle-authoring-schemas/schemas/integrations-yml.json": "integrations.yml",
    "./node_modules/@rasahq/mantle-authoring-schemas/schemas/memory-yml.json": "memory.yml",
    "./node_modules/@rasahq/mantle-authoring-schemas/schemas/skill-memory-yml.json": "skills/*/memory.yml",
    "./node_modules/@rasahq/mantle-authoring-schemas/schemas/responses-yml.json": [
      "responses.yml",
      "skills/*/responses.yml"
    ]
  }
}
```

A modeline on a file at the project root does the same for that one file. The
path is relative to the file:

```yaml theme={null}
# yaml-language-server: $schema=./node_modules/@rasahq/mantle-authoring-schemas/schemas/integrations-yml.json
```

`ordered-block.json` describes one `:::ordered_block` body, and
`skill-md-frontmatter.json` describes the YAML block at the top of `skill.md`.
A filename mapping does not attach those schemas to the surrounding Markdown.

## Python decorators

[python-decorators.json](https://mantle.rasa.com/reference/schemas/python-decorators.json) is the
contract for `@tool` and the `on_*` / `modify_*` hook decorators. It is not a
YAML file schema. It lists each decorator's name and parameters, which tool
parameters the runtime injects, and each hook's point, lane, and timeout.

How to write a tool or a hook stays in [Tools](https://mantle.rasa.com/reference/tools.md) and
[Hooks](https://mantle.rasa.com/reference/hooks.md).


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