Custom skills and instructions on module level

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

@@ -53,6 +53,7 @@ Guidance:
 * **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/).
 * **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/).
 * **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/).
+* **Maia Agent Instructions** – allows you to define project- or module-level instructions (AGENTS.md) that steer agent behavior. You can use them to set common context for your prompts, such as company conventions or environment restrictions. For more information, see [Maia Agent Instructions](/refguide/maia-instructions/).
 
 Recommenders:
 

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

@@ -53,6 +53,8 @@ The following table lists Maia Make Standalone Capabilities and the Studio Pro v
 | [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 | |
 | [Maia Web Fetch](/refguide/maia-web-fetch/) | Fetches and reads content from public websites and APIs. | Studio Pro 11.10 | |
 | [Maia Agent Skills](/refguide/maia-agent-skills/) | Extends Maia with reusable knowledge. | Studio Pro 11.11 | |
+| [Maia Agent Instructions](/refguide/maia-instructions/) | Extends Maia with instructions to be followed with every prompt | Studio Pro 11.12 | |
+
 
 ### Maia Make General Capabilities
 

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

@@ -21,15 +21,19 @@ Instead of typing the same context into every chat, you define agent skills once
 
 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.
 
+Starting from Studio Pro 11.12, Maia supports not only project-level skills, but also skills for all application (non-protected) modules. These skills are exportable together with the module in which they are kept
+and can help you split your skills better.
+
 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/).
 
 ## Creating an Agent Skill {#creating-a-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.
+1. In the **App Explorer**, find either the **Maia** node under **App** for project-level skills, or **Maia** node under a module if you wish to add skills for a module.
+1. Expand this node to **Maia** > **skills**.
+1. Right-click **skills** and click **Add** > **Skill**.
+1. Enter a name for the skill.
 
 Studio Pro creates the `SKILL.md` file. You can continue adding the skill content.
 
@@ -58,7 +62,10 @@ The `name` field must match the skill's parent directory name exactly. A mismatc
 
 ### Directory Structure {#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: <kbd>F4</kbd>) to make the changes visible in Studio Pro.
+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. 
+You can also sync the changes by pressing the **Sync** button in the **Maia skills** overview pane.
+
+Project-level skills are stored directly under `skillssource` directory:
 
 ```
 skillssource/
@@ -69,13 +76,26 @@ skillssource/
       NOTES.md
 ```
 
+Skills for particular modules are stored under `_modules` subdirectory:
+
+```
+skillssource/
+  _modules/
+    <module_name>/
+      your-skill/
+        SKILL.md
+        references/
+          GLOSSARY.md
+          NOTES.md
+```
+
 ## Adding Reference Files {#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.
+1. In the **App Explorer**, under **Maia** > **skills** (either under **App** or for a particular module), right-click the skill you want to add a reference to.
 2. Click **Add** > **Reference**.
 3. Enter a name for the reference file.
 
@@ -85,8 +105,22 @@ For more information on how skills and reference files load, and when they apply
 
 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.
 
+Make sure to provide informative description of a skill as this is the leading information Maia uses to decide whether to read your skill.
+
 If you add or edit a skill while a session is active, those changes take effect the next time you start a chat.
 
+## Skill Overview {#skill-overview}
+
+Since Studio Pro 11.12, Maia lets you list all registered agent skills. Click the **Skills** button next to
+**Add** in the Maia input area to open the **Skills** pane. The pane shows whether each skill has loaded
+successfully, including any error message, references found, and the module the skill belongs to.
+
+{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-agent-skills/skills-pane.png" width="400px">}}
+
+
+Updates to skills, whether you add a new skill or change an existing one, appear only after you start a new session.
+To apply the updated skills immediately, click the **Sync** button in the **Skills**  pane.
+
 ## Limitations {#limitations}
 
 * Only Markdown files are supported as reference files. Files in other formats are ignored.

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

@@ -0,0 +1,60 @@
+---
+title: "Maia Agent Instructions (AGENTS.md)"
+linktitle: "Maia Instructions"
+url: /refguide/maia-instructions/
+weight: 95
+description: "Describes how to create and manage Maia Instructions (AGENTS.md) to steer agent behavior at the project or module level."
+#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.
+---
+
+## Introduction
+
+{{% alert color="info" %}}
+This feature was released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.12.
+
+To use Maia Agent Instructions, an internet connection and signing in to Studio Pro are required.
+{{% /alert %}}
+
+Maia Instructions are agent 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 the given module.
+
+Maia Instructions follow the [AGENTS.md standard](https://agents.md) for agent instructions.
+
+## Maia Instructions vs. Agent Skills {#instructions-vs-skills}
+
+Maia supports both [agent skills](/refguide/maia-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 Maia Instruction {#creating-instructions}
+
+To create a new Maia Instruction, follow these steps:
+
+1. In the **App Explorer**, find either the **Maia** node under **App** for project-level instructions, or the **Maia** node under a module if you wish to add a module-level instruction.
+2. Right-click this node and click **Add** > **Agent instructions**.
+
+Studio Pro creates the `AGENTS.md` file. You can continue adding the instruction content.
+
+{{% alert color="info" %}}Newly added instructions or changes to existing instructions are discovered only when new session is started.{{% /alert %}}
+
+### Instructions Content {#instructions-content}
+
+Maia Instructions are arbitrary Markdown files that follow the AGENTS.md standard. You can structure them any way you like.
+
+However, it is recommended to include only instructions that are applicable to every prompt in the given project or module. For example, you can add naming conventions, limitations of your environment, or language preferences to the agent instructions. If the instructions are applicable only when working with a single module in the project, you should add instructions at the module level.
+
+### Directory Structure {#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.
+
+## Read More
+
+- [Agent Skills](/refguide/maia-agent-skills/)
+- [Mendix AI Assistance (Maia)](/refguide/mendix-ai-assistance/)
+- [Maia Chat](/refguide/maia-chat/)