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

# Project structure

> Every file and folder a Mantle agent recognises, and which are required.

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

`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

| Path | Required | Purpose |
| - | - | - |
| `agent.yml` | **Yes** | [Identity, persona, orchestrator, rules, prompts, session settings](https://mantle.rasa.com/reference/agent-yml.md) |
| `integrations.yml` | **Yes** | [Model groups, channels, optional MCP servers, tracing, and metrics](https://mantle.rasa.com/reference/integrations-yml.md) |
| `memory.yml` | No | [Project-wide memory](https://mantle.rasa.com/reference/memory-yml.md#project-memory-memoryyml-at-the-agent-root). A flat map, resolving to `session.project.<entry>` |
| `responses.yml` | No | [Project-wide responses](https://mantle.rasa.com/reference/responses-yml.md). 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](https://mantle.rasa.com/reference/hooks.md) |
| `hooks/` | No | [Hook modules](https://mantle.rasa.com/reference/hooks.md), discovered recursively |

## A skill folder

| Path | Required | Purpose |
| - | - | - |
| `skill.md` | **Yes** | [Frontmatter and prose body](https://mantle.rasa.com/reference/skill-md.md) |
| `memory.yml` | No | [This skill's schema](https://mantle.rasa.com/reference/memory-yml.md), under `session.<skill_id>.<entry>` |
| `responses.yml` | No | [Verbatim wording](https://mantle.rasa.com/reference/responses-yml.md) |
| `tools.py` or `tools/*.py` | No | [Tools](https://mantle.rasa.com/reference/tools.md), 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. Ids starting with `builtin_` are
reserved for [bundled skills](https://mantle.rasa.com/reference/builtin-skills.md). 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](https://mantle.rasa.com/concepts/tools.md#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

* [Getting Started](https://mantle.rasa.com/getting-started.md): scaffold a project and build the first skill
* [skill.md](https://mantle.rasa.com/reference/skill-md.md): the contract for the one required file
* [Authoring files](https://mantle.rasa.com/reference/schemas/index.md): JSON Schema for the authoring files


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