skills/ folder. Everything else is
optional and added when a skill needs it.
The minimum
This is a complete, trainable agent:Everything a project can hold
Each optional file is added only when a skill needs it:What makes it a Mantle project
rasa train and rasa data validate choose the engine from the project layout,
not from a config key. A project is Mantle when it has an integrations.yml
and at least one skills/*/skill.md.
That glob is one level deep, so a skill folder sits directly under skills/.
Run Mantle CLI commands from this directory: the agent project root, the folder
that holds agent.yml and integrations.yml. rasa train and
rasa data validate read that layout from the working directory and require
skills/*/skill.md on disk.
Agent root
A skill folder
The folder name is the skill id. A skill in
skills/card_replace/ is
@skill.card_replace in prose and session.card_replace.<entry> in memory,
whatever its frontmatter name: says. Ids starting with builtin_ are
reserved for bundled skills. Any other project
skill with that prefix fails validation. Replacing a bundled skill uses that
skill’s exact id. The names session_start, session_end, and
silence_timeout are reserved for engine messages and fail validation too.
Declared or discovered
The difference decides whether a tool is usable without any config:- A skill’s own tools are auto-discovered from
tools.pyandtools/*.pyin that folder. Nothing to declare. Within one skill, atools/*.pydefinition shadows a same-named one intools.py. - Shared tools in the agent-root
tools/folder must be named in the skill’simport_tools. A shared tool that is not declared is not attached to the skill. - MCP tools use
mcp/<server-id>:<tool-name>inimport_tools, or a patternmcp/<server-id>:*/mcp/<server-id>:<prefix>*. A named import attaches that tool. A pattern attaches the names that match when the agent starts or reloads. See Import MCP tools. - On a name collision between skill-local and shared tools, the skill-local tool
wins. A concrete MCP import whose bare name collides with either fails
rasa train. A pattern that later matches that name fails when the agent starts.
What ships in the trained model
rasa train copies agent.yml, integrations.yml, memory.yml,
responses.yml, and the skills/, tools/, and references/ directories into
the model archive. With --integrations <path>, the copy of integrations.yml
is that file. A relative path is relative to the working directory. Omitting
the flag copies <project_root>/integrations.yml. A missing explicit path is
an error. rasa train writes that archive as an agent package under models/.
Consequences worth knowing:
- The reference index is built at train time from the packaged
integrations.yml, so adding or editing a file under anyreferences/folder needs a retrain before the agent can answer from it. Query embeddings at runtime use that same packaged copy. - The model group named by
orchestrator.model_group, pluschannels:andmcp_servers:, are read at runtime from the integrations file selected for this project. Omitting--integrationsuses<project_root>/integrations.yml. Passing it uses that path, not the copy inside the model. Changing the models inside that group, a channel, or an MCP connection only needs a restart. Changing which grouporchestrator.model_groupnames needs a retrain. rasa run,rasa shell, andrasa inspectread channels, the secrets manager, and runtime endpoints from that same integrations file. A Mantle--modelarchive already holds the skills, so those commands do not need askills/folder beside the project file.rasa trainandrasa data validatestill requireskills/*/skill.mdon disk. Endpoint blocks left only inendpoints.ymlare ignored.--integrationsdoes not change which directory is the project. Layout detection still looks for<project_root>/integrations.yml. The override applies only to the project it was resolved for. Helm does not need the flag: mountintegrations.ymlat the project root and leave it omitted.
Files the scaffold adds
rasa init --engine mantle also writes AGENTS.md, context for your coding
agent, and .env, holding your keys. Neither is read by the engine: .env
supplies environment variables referenced with ${VAR}, and AGENTS.md is
for your IDE.
When you pick a coding agent during rasa init, it also writes
.rasa/docs/mantle/, a local copy of this documentation for your coding agent to
search. The engine never reads it, and deleting it only means
your agent has to fetch the reference over the network instead. Restore it with
rasa tools init docs mantle.
See also
- Getting Started: scaffold a project and build the first skill
- skill.md: the contract for the one required file
- Authoring files: JSON Schema for the authoring files