Project structure

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
`integrations.yml`	Yes	LLM provider, channels, model groups
`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`

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

File Reference

Language

Tools

Runtime

Prompts

Project structure

The minimum

Everything a project can hold

What makes it a Maestro 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 Maestro 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 Maestro project

Agent root

A skill folder

Declared or discovered

What ships in the trained model

Files the scaffold adds

See also