Project structure

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:

my-agent/
├── agent.yml              # Identity, persona, orchestrator, rules
├── integrations.yml       # Model groups, channels, optional tracing and metrics
└── skills/
    └── card_replace/      # The folder name is the skill id
        └── skill.md       # Instructions, and any control declarations

Everything a project can hold

Each optional file is added only when a skill needs it:

my-agent/
├── agent.yml              # Required. Identity, persona, orchestrator, rules
├── integrations.yml       # Required. Model groups, channels, optional tracing and metrics
├── memory.yml             # Optional. Project-wide memory, the project. namespace
├── responses.yml          # Optional. Project-wide responses, overrides built-in wording
├── references/            # Optional. Agent-wide knowledge, every **/*.md is indexed
├── tools/                 # Optional. Shared tools, declared with import_tools
├── hooks.py               # Optional. Single-file hook modules
├── hooks/                 # Optional. Folder of hook modules (recursive)
└── skills/
    └── card_replace/
        ├── skill.md       # Required. The only required file in a skill
        ├── memory.yml     # Optional. This skill's memory schema
        ├── responses.yml  # Optional. Verbatim wording
        ├── tools.py       # Optional. Auto-discovered, no declaration needed
        ├── tools/         # Optional. Or a folder of them, also auto-discovered
        └── references/    # Optional. Indexed into the same project-wide index

What makes it a Mantle project

The engine is chosen by layout rather than by 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/.

Agent root

Path	Required	Purpose
`agent.yml`	Yes	Identity, persona, orchestrator, rules, prompts, session settings
`integrations.yml`	Yes	Model groups, channels, optional MCP servers, tracing, and metrics
`memory.yml`	No	Project-wide memory. A flat map, resolving to `session.project.<entry>`
`responses.yml`	No	Project-wide responses. Declaring a built-in name here replaces it
`references/`	No	Markdown indexed at train time, reachable through `search_knowledge`
`tools/`	No	Shared tools. A skill uses one by naming it in `import_tools`
`hooks.py`	No	Single-file hook modules
`hooks/`	No	Hook modules, discovered recursively

A skill folder

Path	Required	Purpose
`skill.md`	Yes	Frontmatter and prose body
`memory.yml`	No	This skill’s schema, under `session.<skill_id>.<entry>`
`responses.yml`	No	Verbatim wording
`tools.py` or `tools/*.py`	No	Tools, auto-discovered
`references/`	No	Knowledge, indexed into the project-wide index

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.

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. Only listed tools are attached; see Import MCP tools.
On a name collision between skill-local and shared tools, the skill-local tool wins. An MCP bare name that collides with either fails rasa train.

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. Two consequences worth knowing:

The reference index is built at train time, so adding or editing a file under any references/ folder needs a retrain before the agent can answer from it.
The model group named by orchestrator.model_group, plus channels: and mcp_servers:, are read from your project directory at runtime. 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.

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

File Reference

Language

Tools

Customizations

Runtime

Observability

Prompts

Schemas

Project structure

The minimum

Everything a project can hold

What makes it a Mantle project

Agent root

A skill folder

Declared or discovered

What ships in the trained model

Files the scaffold adds

See also

​The minimum

​Everything a project can hold

​What makes it a Mantle project

​Agent root

​A skill folder

​Declared or discovered

​What ships in the trained model

​Files the scaffold adds

​See also

The minimum

Everything a project can hold

What makes it a Mantle project

Agent root

A skill folder

Declared or discovered

What ships in the trained model

Files the scaffold adds

See also