Skip to main content
A Mantle project is two config files and a 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.py and tools/*.py in that folder. Nothing to declare. Within one skill, a tools/*.py definition shadows a same-named one in tools.py.
  • Shared tools in the agent-root tools/ folder must be named in the skill’s import_tools. A shared tool that is not declared is not attached to the skill.
  • MCP tools use mcp/<server-id>:<tool-name> in import_tools, or a pattern mcp/<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 any references/ 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, plus channels: and mcp_servers:, are read at runtime from the integrations file selected for this project. Omitting --integrations uses <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 group orchestrator.model_group names needs a retrain.
  • rasa run, rasa shell, and rasa inspect read channels, the secrets manager, and runtime endpoints from that same integrations file. A Mantle --model archive already holds the skills, so those commands do not need a skills/ folder beside the project file. rasa train and rasa data validate still require skills/*/skill.md on disk. Endpoint blocks left only in endpoints.yml are ignored.
  • --integrations does 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: mount integrations.yml at 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