> ## Documentation Index
> Fetch the complete documentation index at: https://rasa-2f7eb63d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

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

A Maestro 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, rules, prompt tuning
├── integrations.yml       # LLM provider and channels
└── 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, rules, prompt tuning
├── integrations.yml       # Required. LLM provider and channels
├── 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
└── 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 Maestro project

The engine is chosen by layout rather than by a config key. A project is Maestro
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, rules, prompts, session settings](/reference/agent-yml)                                                                 |
| `integrations.yml` | **Yes**  | [LLM provider, channels, model groups](/reference/integrations-yml)                                                                         |
| `memory.yml`       | No       | [Project-wide memory](/reference/memory-yml#project-memory-memoryyml-at-the-agent-root). A flat map, resolving to `session.project.<entry>` |
| `responses.yml`    | No       | [Project-wide responses](/reference/responses-yml). 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`                                                                               |

## A skill folder

| Path                       | Required | Purpose                                                                          |
| -------------------------- | -------- | -------------------------------------------------------------------------------- |
| `skill.md`                 | **Yes**  | [Frontmatter and prose body](/reference/skill-md)                                |
| `memory.yml`               | No       | [This skill's schema](/reference/memory-yml), under `session.<skill_id>.<entry>` |
| `responses.yml`            | No       | [Verbatim wording](/reference/responses-yml)                                     |
| `tools.py` or `tools/*.py` | No       | [Tools](/reference/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.
* On a name collision, the skill-local tool wins. This is resolved once when the
  model loads.

## 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.
* `llm:` and `channels:` are read from your project directory at runtime, so a
  provider or channel change only needs a restart.

## Files the scaffold adds

`rasa init --engine maestro` also writes `AGENTS.md`, context for your coding
agent, and `.env`, holding your keys. Neither is read by the engine: `.env`
supplies the environment variables that `api_key_env` and `${VAR}` resolve
against, and `AGENTS.md` is for your IDE.

## See also

* [Getting Started](/getting-started): scaffold a project and build the first skill
* [skill.md](/reference/skill-md): the contract for the one required file