Skip to main content
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. 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 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. This catalog is those files. Conversation events are a separate contract; see Conversation events.

Install

The virtual rasa-npm repository is public. Add this to the project .npmrc:
<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.
A modeline on a file at the project root does the same for that one file. The path is relative to the file:
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 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 and Hooks.