Agent Instructions (AGENTS.md)
Introduction
This feature is part of Maia Make and was introduced in Studio Pro 11.12.
To use Agent Instructions, you need an internet connection and must be signed in to Studio Pro. If you are using the MCP Server to bring your own agent (BYO Agent), you do not need to be signed in to Studio Pro.
Agent Instructions are instructions that are automatically added to the conversation context. They let you define shared prompt context, such as company conventions or environment restrictions, once and reuse it when needed.
They can be provided at the project level or module level. Project-level instructions are included in every conversation in the project. Module-level instructions are included whenever Maia starts working in that module.
Agent Instructions follow the AGENTS.md standard for agent instructions.
Agent Instructions vs. Agent Skills
Maia supports both agent skills and agent instructions. The following table summarizes their differences:
| Aspects | Instructions | Skills |
|---|---|---|
| Loading | Deterministically loaded, whenever working with the given project or module. | Agent decides to load skills on demand, based on their name and description. |
| Applicability | Project or module-wide instructions that should always be part of context (for example, company preferences). | Instructions that are applicable only in certain situations (for example, microflow conventions). |
| Organization | Single file, should be kept as short as possible. | Allows you to split instructions into the core skill and additional references that Maia reads on demand as needed. |
Creating a New Agent Instruction
To create a new agent instruction, follow these steps:
- In the App Explorer, find either the Maia node under App for project-level instructions, or the Maia node under a module if you want to add a module-level instruction.
- Right-click this node and click Add > Agent instructions.
Studio Pro creates the AGENTS.md file. You can now add the instruction content.
Instructions Content
Agent Instructions are arbitrary Markdown files that follow the AGENTS.md standard. You can structure them any way you like.
However, Mendix recommends including only instructions that are applicable to every prompt in the given project or module. For example, you can add naming conventions, environment limitations, or language preferences. If the instructions apply only to a single module, add them at the module level.
Directory Structure
Project-level instructions are stored as skillssource/AGENTS.md, while module-level instructions are stored as skillssource/_modules/<module_name>/AGENTS.md. You can add only one instructions file per project or per module.