Maia Agent Skills

Introduction

Maia Agent Skills are modular, reusable instructions that extend Maia's capabilities with domain-specific knowledge, giving it the context, workflows, and guidance it needs to work the way your team works.

Instead of typing the same context into every chat, you define agent skills once, and Maia applies them automatically whenever relevant. This eliminates the need to repeat the same guidance across conversations.

Use agent skills to equip Maia with the domain knowledge and conventions it needs, whether those are company-wide standards or team-specific workflows. For example, a skill capturing your company's Mendix naming conventions means Maia applies them consistently whenever it generates entities, attributes, or microflows without you having to mention them each time.

For guidance on writing effective skills, see Best Practices for Skill Creators and Optimizing Skill Descriptions in the Agent Skills documentation.

Creating an Agent Skill

To create a new agent skill in Studio Pro, follow these steps:

1. In the App Explorer, expand Maia > skills.
2. Right-click skills and click Add > Skill.
3. Enter a name for the skill.

Studio Pro creates the SKILL.md file. You can continue adding the skill content.

SKILL.md Format

Each SKILL.md file must include YAML frontmatter at the top, followed by the skill content in Markdown:

---
name: your-skill
description: Applies company-wide naming conventions for entities, attributes, and microflows.
---

Write your skill instructions here in plain Markdown. Use the `references/` subdirectory
to add supplementary content and refer to it from here as needed.

See [my-reference](references/my-reference.md) for details.

The name field must match the skill's parent directory name exactly. A mismatch prevents the skill from loading. For example, if the skill directory is skillssource/your-skill/, the name field must be your-skill.

Directory Structure

Skills are stored in the skillssource/ directory at the root of your application directory. You can also manage skills directly in the file system, for example, to copy in skills from another project. After making changes in the file system, go to App > Synchronize App Directory (keyboard shortcut: F4) to make the changes visible in Studio Pro.

skillssource/
  your-skill/
    SKILL.md
    references/
      GLOSSARY.md
      NOTES.md

Adding Reference Files

Reference files let you keep your skill focused by moving supplementary content into separate documents, such as a glossary of domain terms, a data dictionary, or detailed architecture notes. Maia accesses reference file content on demand, only when relevant to your request.

To add a reference file to a skill, follow these steps:

1. In the App Explorer, under Maia > skills, right-click the skill you want to add a reference to.
2. Click Add > Reference.
3. Enter a name for the reference file.

For more information on how skills and reference files load, and when they apply, see Agent Skills Specification.

How Agent Skills Work

At the start of each chat session, Maia becomes aware of all agent skills in your project. As you work, Maia picks up the relevant skill content automatically. You do not need to reference or invoke skills explicitly.

If you add or edit a skill while a session is active, those changes take effect the next time you start a chat.

Limitations

• Only Markdown files are supported as reference files. Files in other formats are ignored.
• Changes you make to skills take effect the next time you start a chat.

Read More

• Maia Make Capabilities
• Mendix AI Assistance (Maia)
• Maia Chat
• Best Practices for Skill Creators – guidance on writing effective skill content
• Agent Skills Specification – the full specification for the agent skills format