Skip to content

Commit bd8f770

Browse files
Yiyun333Yiyun333
authored
Merge pull request #11203 from KONRADS098/maia-skills-support
Add Maia Agent Skills documentation
2 parents cbb9b42 + 0f927e3 commit bd8f770

8 files changed

Lines changed: 160 additions & 49 deletions

File tree

‎content/en/docs/refguide/mendix-ai-assistance/_index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,14 @@ Starting point for app creation:
4545
* **Start with Maia** - a starting point in Studio Pro that helps you to start the app development process. Based on a required text description and an optional image or PDF, it generates an app that includes a domain model, data management overview pages, test data, and a tailored homepage. For more information, see [Start with Maia](/refguide/start-with-maia/).
4646
* **Maia Make** - a unified conversational interface in Studio Pro that groups all AI-assisted development capabilities into a single chat experience. With this interface, everything happens in one place. Start a conversation, describe what you need, and Maia generates the necessary app artifacts, such as a new domain model, pages, and microflows. You can also ask it to explain documents for you, including your app logic and pages.
4747

48-
This unified conversational interface is released in Studio Pro 11.8. For more information, see [Maia Make](/refguide/maia-make/).
48+
This unified conversational interface was released in Studio Pro 11.8. For more information, see [Maia Make](/refguide/maia-make/).
4949

5050
Guidance:
5151

5252
* **Maia Chat** – a built-in chat interface powered by Generative AI in Studio Pro. It answers questions about app development in Mendix, including how to apply concepts, best practices, and development patterns. For more information, see [Maia Chat](/refguide/maia-chat/).
5353
* **Maia Learn** – helps you to quickly learn Mendix core concepts and get started with Studio Pro. For more information, see [Maia Learn](/refguide/maia-learn/).
5454
* **Maia Explain** – helps you easily understand a microflow or a nanoflow. It explains the general purpose of the logic and highlights specific technical details to help you understand the logic further. For more information, see [Maia Explain](/refguide/maia-explain/).
55+
* **Maia Agent Skills** – lets you define modular, reusable instructions that extend Maia with domain-specific knowledge. Maia applies them automatically whenever relevant, eliminating the need to repeat the same context across conversations. For more information, see [Maia Agent Skills](/refguide/maia-agent-skills/).
5556

5657
Recommenders:
5758

‎content/en/docs/refguide/mendix-ai-assistance/maia-make/_index.md‎

Lines changed: 50 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -10,33 +10,63 @@ description_list: true
1010
## Introduction
1111

1212
{{% alert color="info" %}}
13-
Maia Make capabilities are grouped into a conversational interface, which is available in Studio Pro 11.8 and above.
13+
Maia Make capabilities are available in Studio Pro 11.8 and above.
1414

15-
To use this interface and Maia Make capabilities, an internet connection and signing in to Studio Pro are required.
15+
To use Maia Make capabilities, an internet connection and signing in to Studio Pro are required.
1616
{{% /alert %}}
1717

1818
Maia Make is a set of AI-assisted development capabilities in Studio Pro that are available through a unified conversational interface. Describe your requirements in natural language, and Maia generates development artifacts such as data structures, pages, and microflows.
1919

2020
You can also ask Maia to provide explanations of your existing documents, such as microflows, workflows, and pages. Moreover, this interface allows you to integrate with external tools, such as Playwright and Figma, via MCP Servers, and it supports story-based development by generating app artifacts based on existing user stories.
2121

22-
The key Maia Make capabilities are as follows:
23-
24-
* Conversational assistance for general Mendix development queries
25-
* Explanations of documents to clarify existing implementation details
26-
* Generation of documents from natural language descriptions, such as domain model, pages, and microflows
27-
* Integration with external tools, such as Playwright and Figma, via compatible MCP Servers
28-
* Story-based development to help realize existing user stories
29-
* Support for PDF and image inputs to help Maia better understand your requirements
30-
* Adding relevant documents, such as microflows and pages, to the interface to give Maia a more desired context
31-
* Editing existing documents, including renaming elements inside of documents such as entities, attributes, and microflow parameters
32-
* Removing elements from documents, enabling more advanced refactoring (in Studio Pro 11.9 and above)
33-
* Undoing changes generated on a per-document basis (in Studio Pro 11.9 and above)
34-
35-
{{% alert color="info" %}}
36-
Support for workflows, view entities, enumerations, constants, modules, Java actions, and JavaScript actions was introduced in Studio Pro 11.9. In this version, Java actions are read-only; they can be used in microflows and explained. JavaScript actions can only be explained.
37-
38-
Starting with Studio Pro 11.10, Maia can generate JavaScript actions, add parameters to existing ones, and create or update the JavaScript file associated with a JavaScript action.
39-
{{% /alert %}}
22+
## Maia Make Capabilities Overview
23+
24+
### Supported Document Types
25+
26+
Maia Make can generate new documents, modify existing documents, and explain app documents and structures through a unified conversational interface. The following table lists all document types that Maia Make can work with and the Studio Pro version in which support for each document type was introduced:
27+
28+
| Document Type | Available in Maia Make from | Remarks |
29+
| --- | --- | --- |
30+
| [Domain model](/refguide/maia-for-domain-model/) | Studio Pro 11.8 | |
31+
| [Pages](/refguide/maia-for-pages/) | Studio Pro 11.8 | |
32+
| [Microflows](/refguide/maia-for-microflows/) | Studio Pro 11.8 | |
33+
| [Workflows](/refguide/maia-for-workflows/) | Studio Pro 11.9 | |
34+
| [OQL](/refguide/maia-for-oql/) | Studio Pro 11.9 | |
35+
| View entities | Studio Pro 11.9 | |
36+
| Enumerations | Studio Pro 11.9 | |
37+
| Constants | Studio Pro 11.9 | |
38+
| Modules | Studio Pro 11.9 | |
39+
| Java actions | Studio Pro 11.9 | Read-only; Java actions cannot be generated. |
40+
| JavaScript actions | Studio Pro 11.9 | Explain-only in Studio Pro 11.9. Generation, adding parameters, and updating the associated JavaScript file available from Studio Pro 11.10. |
41+
| Navigation | Studio Pro 11.11 | |
42+
| Menu | Studio Pro 11.11 | |
43+
44+
### Maia Make Standalone Capabilities
45+
46+
The following table lists Maia Make Standalone Capabilities and the Studio Pro version in which each capability was introduced:
47+
48+
| Capability | Description | Available in Maia Make from | Remarks |
49+
| --- | --- | --- | --- |
50+
| [Maia Chat](/refguide/maia-chat/) | Answers questions about all aspects of Mendix development. | Studio Pro 11.8 | |
51+
| [Maia Explain](/refguide/maia-explain/) | Explains the purpose and logic of existing documents. | Studio Pro 11.8 | |
52+
| [Maia MCP Client](/refguide/maia-mcp/) | Connects Maia to external MCP servers, giving it access to third-party tools. | Studio Pro 11.8 | |
53+
| [Studio Pro MCP Server](/refguide/studio-pro-mcp-server/) | Exposes Studio Pro as an MCP server for use by external AI tools. | Studio Pro 11.10 | |
54+
| [Maia Web Fetch](/refguide/maia-web-fetch/) | Fetches and reads content from public websites and APIs. | Studio Pro 11.10 | |
55+
| [Maia Agent Skills](/refguide/maia-agent-skills/) | Extends Maia with reusable knowledge. | Studio Pro 11.11 | |
56+
57+
### Maia Make General Capabilities
58+
59+
The following table lists the general capabilities of Maia Make and the Studio Pro version in which support for each capability was introduced:
60+
61+
| Capability | Description | Available in Maia Make from | Remarks |
62+
| --- | --- | --- | --- |
63+
| Story-based development | Generates app artifacts based on existing user stories to support story-driven development workflows. | Studio Pro 11.8 | |
64+
| PDF/image support | Allows you to provide PDFs and images as input to help Maia better understand your requirements. | Studio Pro 11.8 | |
65+
| Adding documents as context | Lets you add relevant documents, to provide Maia with additional context. | Studio Pro 11.8 | |
66+
| Editing existing documents | Enables Maia to modify existing documents, including renaming elements. | Studio Pro 11.8 | |
67+
| Removing elements | Allows Maia to remove elements from documents to support more advanced refactoring tasks. | Studio Pro 11.9 | |
68+
| Undo support | Allows you to undo Maia-generated changes on a per-document basis. | Studio Pro 11.9 | |
69+
| Folder structure support | Organizes new documents into existing folders and follows your established folder hierarchy when generating content. | Studio Pro 11.10 | Not supported for pages. |
4070

4171
## Using Maia Make Capabilities
4272

@@ -67,29 +97,6 @@ The conversational interface includes the following options:
6797
* **{{% icon name="paperclip" %}} Add** (Image, Story, PDF) - With this option, you can attach images, PDFs, or user stories to help Maia understand your requirements better.
6898
* **Add file to Maia Chat** (@ icon) - It allows you to add certain logic or pages to Maia as context. You can also access this option by right-clicking the documents (microflows or pages) in the **App Explorer** and it appears in the context menu.
6999

70-
#### Support for Folder Structure
71-
72-
In Studio Pro 11.10 and above, Maia understands and leverages the existing folder structure within your Mendix applications for all documents except for pages. This enables Maia to:
73-
74-
* Organize documents into folders: When creating new documents, Maia can place them directly into relevant folders, respecting your project's organization.
75-
* Follow existing folder structures: Maia works within your established folder hierarchy, making it easier to maintain consistency.
76-
* Adhere to Mendix best practices: Maia can help organize documents according to the standard Mendix best practices for folder structure. For detailed guidance on optimal organization of folders, refer to the [Folder Structure](/refguide/naming-convention-best-practices/#folder-structure) section in *Naming Convention Best Practices*.
77-
78-
For more information on how each Maia Make capability work, refer to the following documents:
79-
80-
* [Maia Chat](/refguide/maia-chat/)
81-
* [Maia Explain](/refguide/maia-explain/)
82-
* [Maia for Domain Model](/refguide/maia-for-domain-model/)
83-
* [Maia for Pages](/refguide/maia-for-pages/)
84-
* [Maia for Microflows](/refguide/maia-for-microflows/)
85-
* [Maia for Workflows](/refguide/maia-for-workflows/) (in Studio Pro 11.9 and above)
86-
* [Maia for OQL](/refguide/maia-for-oql/) (in Studio Pro 11.9 and above)
87-
* [Maia MCP Client](/refguide/maia-mcp/)
88-
* [Studio Pro MCP Server](/refguide/studio-pro-mcp-server/)
89-
* [Maia Web Fetch](/refguide/maia-web-fetch/)
90-
91-
In Studio Pro 11.8 and above, most of the features described in the documents above are available only through the chat interface. There are no separate entry points to these features in their respective editors. [Maia Explain](/refguide/maia-explain/) is an exception. You can still access this feature by right-clicking the documents (for example, microflows or pages) in the **App Explorer** and the **Maia Explain** option is in the context menu.
92-
93100
## Read More
94101

95102
* [Mendix AI Assistance (Maia)](/refguide/mendix-ai-assistance/)

‎content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-agent-skills.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: "Maia Agent Skills"
3+
linktitle: "Agent Skills"
4+
url: /refguide/maia-agent-skills/
5+
weight: 95
6+
description: "Describes how to create and manage agent skills that equip Maia with domain-specific knowledge, applied automatically whenever relevant."
7+
#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
8+
---
9+
10+
## Introduction
11+
12+
{{% alert color="info" %}}
13+
This feature was released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.11.
14+
15+
To use Maia Agent Skills, an internet connection and signing in to Studio Pro are required.
16+
{{% /alert %}}
17+
18+
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.
19+
20+
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.
21+
22+
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.
23+
24+
For guidance on writing effective skills, see [Best Practices for Skill Creators](https://agentskills.io/skill-creation/best-practices) and [Optimizing Skill Descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) in the [Agent Skills documentation](https://agentskills.io/).
25+
26+
## Creating an Agent Skill {#creating-a-skill}
27+
28+
To create a new agent skill in Studio Pro, follow these steps:
29+
30+
1. In the **App Explorer**, expand **Maia** > **skills**.
31+
2. Right-click **skills** and click **Add** > **Skill**.
32+
3. Enter a name for the skill.
33+
34+
Studio Pro creates the `SKILL.md` file. You can continue adding the skill content.
35+
36+
### SKILL.md Format {#skill-md-format}
37+
38+
Each `SKILL.md` file must include YAML frontmatter at the top, followed by the skill content in Markdown:
39+
40+
```yaml
41+
---
42+
name: your-skill
43+
description: Applies company-wide naming conventions for entities, attributes, and microflows.
44+
---
45+
46+
Write your skill instructions here in plain Markdown. Use the `references/` subdirectory
47+
to add supplementary content and refer to it from here as needed.
48+
49+
See [my-reference](references/my-reference.md) for details.
50+
```
51+
52+
| Field | Required | Description |
53+
| --- | --- | --- |
54+
| `name` | Yes | Must match the skill's parent directory name exactly. For full naming rules, see [Agent Skills Specification](https://agentskills.io/specification#name-field). |
55+
| `description` | Yes | See [Agent Skills Specification](https://agentskills.io/specification#description-field). |
56+
57+
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`.
58+
59+
### Directory Structure {#directory-structure}
60+
61+
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: <kbd>F4</kbd>) to make the changes visible in Studio Pro.
62+
63+
```
64+
skillssource/
65+
your-skill/
66+
SKILL.md
67+
references/
68+
GLOSSARY.md
69+
NOTES.md
70+
```
71+
72+
## Adding Reference Files {#reference-files}
73+
74+
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.
75+
76+
To add a reference file to a skill, follow these steps:
77+
78+
1. In the **App Explorer**, under **Maia** > **skills**, right-click the skill you want to add a reference to.
79+
2. Click **Add** > **Reference**.
80+
3. Enter a name for the reference file.
81+
82+
For more information on how skills and reference files load, and when they apply, see [Agent Skills Specification](https://agentskills.io/specification#progressive-disclosure).
83+
84+
## How Agent Skills Work
85+
86+
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.
87+
88+
If you add or edit a skill while a session is active, those changes take effect the next time you start a chat.
89+
90+
## Limitations {#limitations}
91+
92+
* Only Markdown files are supported as reference files. Files in other formats are ignored.
93+
* Changes you make to skills take effect the next time you start a chat.
94+
95+
## Read More
96+
97+
* [Maia Make Capabilities](/refguide/maia-make/)
98+
* [Mendix AI Assistance (Maia)](/refguide/mendix-ai-assistance/)
99+
* [Maia Chat](/refguide/maia-chat/)
100+
* [Best Practices for Skill Creators](https://agentskills.io/skill-creation/best-practices) – guidance on writing effective skill content
101+
* [Agent Skills Specification](https://agentskills.io/specification) – the full specification for the agent skills format

‎content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-for-microflows.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ description: "Describes the features in Maia for Microflows."
77
## Introduction
88

99
{{% alert color="info" %}}
10-
This feature is released as part of [Make Make](/refguide/maia-make/) capabilities in Studio Pro 11.8.
10+
This feature was released as part of [Make Make](/refguide/maia-make/) capabilities in Studio Pro 11.8.
11+
12+
To use Maia for Microflows, an internet connection and signing in to Studio Pro are required.
1113
{{% /alert %}}
1214

1315
Maia for Microflows is an AI-powered capability that is available when using [Maia Make](/refguide/maia-make/) in Studio Pro. Maia Make is a unified conversational interface within Studio Pro that consolidates all AI-assisted development capabilities into a single chat experience.

‎content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-for-oql.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ description: "Describes the features in Maia for OQL Generation."
88
## Introduction
99

1010
{{% alert color="info" %}}
11-
An internet connection and signing in to Studio Pro are required to use Maia for OQL.
11+
To use Maia for OQL, an internet connection and signing in to Studio Pro are required.
1212
{{% /alert %}}
1313

1414
Maia for OQL is a powerful feature that enables you to generate and manage OQL (Object Query Language) queries through an intuitive interface. It is designed to simplify query creation and reduce manual effort. Currently it has some limitations. For more details, see the [Limitations](#limitations) section below.

‎content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-mcp.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ description: "Describes the features in Maia MCP Client."
1010
## Introduction
1111

1212
{{% alert color="info" %}}
13-
This feature is released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.8.
13+
This feature was released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.8.
1414

1515
To use Maia MCP Client, an internet connection and signing in to Studio Pro are required.
1616
{{% /alert %}}

‎content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-web-fetch.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ description: "Describes Maia's web fetch capability for retrieving content from
1010
## Introduction
1111

1212
{{% alert color="info" %}}
13-
This feature is available in Studio Pro 11.10 and above.
13+
This feature was released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.10.
1414

1515
To use Maia Web Fetch, an internet connection and signing in to Studio Pro are required.
1616
{{% /alert %}}

‎content/en/docs/refguide/mendix-ai-assistance/maia-make/studio-pro-mcp-server.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ description: "Describes the features in Studio Pro MCP Server."
1010
## Introduction
1111

1212
{{% alert color="info" %}}
13-
This feature is available in Studio Pro 11.10 and above.
13+
This feature was released in Studio Pro 11.10.
1414

1515
To use Studio Pro MCP Server, an internet connection and signing in to Studio Pro are required.
1616
{{% /alert %}}

0 commit comments

Comments
 (0)