Maia skill writing + improve docs consistency and terminology

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

@@ -58,8 +58,8 @@ Guidance:
 * **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/). 
 * **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/).
+* **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 (SKILLS.md)](/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 (AGENTS.md)](/refguide/maia-agent-instructions/).
 
 Recommenders:
 

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

@@ -57,8 +57,8 @@ The following table lists Maia Make Standalone Capabilities and the Studio Pro v
 | [Maia MCP Client](/refguide/maia-mcp/) | Connects Maia to external MCP servers, giving it access to third-party tools. | Studio Pro 11.8 | |
 | [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 Agent Skills (SKILLS.md)](/refguide/maia-agent-skills/) | Extends Maia with reusable knowledge. | Studio Pro 11.11 | Maia can create and edit skills directly in chat, for both project-level and module-level skills, from Studio Pro 11.15. |
+| [Maia Agent Instructions (AGENTS.md)](/refguide/maia-agent-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-instructions.md → content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-agent-instructions.md

@@ -1,9 +1,11 @@
 ---
 title: "Maia Agent Instructions (AGENTS.md)"
-linktitle: "Maia Instructions"
-url: /refguide/maia-instructions/
+linktitle: "Agent Instructions"
+url: /refguide/maia-agent-instructions/
+aliases:
+  - /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."
+description: "Describes how to create and manage agent 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.
 ---
 
@@ -12,28 +14,28 @@ description: "Describes how to create and manage Maia Instructions (AGENTS.md) t
 {{% 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.
+To use 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.
+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 the given module.
 
-Maia Instructions follow the [AGENTS.md standard](https://agents.md) for agent instructions.
+Agent Instructions follow the [AGENTS.md standard](https://agents.md) for agent instructions.
 
-## Maia Instructions vs. Agent Skills {#instructions-vs-skills}
+## Agent 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. |
+| 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}
+## Creating a New Agent Instruction {#creating-instructions}
 
-To create a new Maia Instruction, follow these steps:
+To create a new agent 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**.
@@ -44,7 +46,7 @@ Studio Pro creates the `AGENTS.md` file. You can continue adding the instruction
 
 ### Instructions Content {#instructions-content}
 
-Maia Instructions are arbitrary Markdown files that follow the AGENTS.md standard. You can structure them any way you like.
+Agent 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.
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Maia Agent Skills"
+title: "Maia Agent Skills (SKILLS.md)"
 linktitle: "Agent Skills"
 url: /refguide/maia-agent-skills/
 weight: 95
@@ -12,10 +12,10 @@ description: "Describes how to create and manage agent skills that equip Maia wi
 {{% alert color="info" %}}
 This feature was released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.11.
 
-To use Maia Agent Skills, an internet connection and signing in to Studio Pro are required.
+To use Agent Skills, an internet connection and signing in to Studio Pro are required.
 {{% /alert %}}
 
-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.
+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.These generic concepts are technically compatible with any agent.
 
 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. 
 
@@ -24,13 +24,30 @@ Use agent skills to equip Maia with the domain knowledge and conventions it need
 Starting from Studio Pro 11.12, Maia supports not only project-level skills, but also skills for all application modules. These skills are exportable together with the module in which they are kept
 and can help you split your skills better.
 
+Starting from Studio Pro 11.15, you can also ask Maia to create new agent skills and edit existing ones directly in the chat, for both project-level skills and module-level skills, instead of managing `SKILL.md` files yourself.
+
 {{% alert color="info" %}}
 Agents skills are not supported for Add-on and Solution modules.
 {{% /alert %}}
 
 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}
+## Writing Agent Skills with Maia {#maia-managed-skills}
+
+Since Studio Pro 11.15, you do not need to manually create or edit `SKILL.md` files to manage your agent skills. Instead, you can ask Maia, directly in the chat, to create a new skill or edit an existing one, for both project-level skills and module-level skills.
+
+For example, you can ask Maia the following:
+
+* Create a skill that documents our naming conventions for entities and attributes.
+* Add a section about error handling to the <your-skill> skill.
+* Update the description of the <your-skill> skill in the <YourModule> module.
+* Turn the retry and logging pattern I have just implemented in this microflow into a reusable skill.
+
+The last example highlights a common use case: while working with Maia on a task, you can ask it to capture the conventions or decisions from that session into a skill, so the same guidance can be reused in future sessions.
+
+Maia automatically syncs the changes it makes to a skill, so they take effect immediately in your current chat session.
+
+## Creating an Agent Skill Manually {#creating-a-skill}
 
 To create a new agent skill in Studio Pro, follow these steps:
 
@@ -111,7 +128,7 @@ At the start of each chat session, Maia becomes aware of all agent skills in you
 
 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.
+If you manually 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}
 

content/en/docs/releasenotes/studio-pro/11/11.12.md

@@ -287,7 +287,7 @@ CDC can be used with the Mendix Event Broker or with a Bring Your Own Kafka (BYO
 * Maia now thinks before responding. You can see what it is considering in real time, and revisit its reasoning at any point during the conversation.
 * MCP OAuth authentication now uses a dedicated callback server on a fixed port range (44380–44384), enabling use with MCP servers that require pre-registered redirect URIs.
 * MCP connections now support Mendix Identity (MxId3) authentication. MCP servers hosted on *.mendix.com automatically receive the user's platform access token.
-* You can now add Maia Agent Instructions. Maia Instructions are agent instructions that are automatically added to the conversation context. You can add them to the project or module level. For more information, see [Maia Agent Instructions (AGENTS.md)](/refguide/maia-instructions/).
+* You can now add Agent Instructions. Agent Instructions are instructions that are automatically added to the conversation context. You can add them to the project or module level. For more information, see [Maia Agent Instructions (AGENTS.md)](/refguide/maia-agent-instructions/).
 * We introduced the following new features to skills in Maia:
     * A new **Skills** pane in Maia shows all custom skills that are currently loaded, their status, and which module they belong to (for module-level skills). You can filter the list to show only skills with errors. To apply the updated skills immediately, you can sync the skills. For more information, see [Skill Overview](/refguide/maia-agent-skills/#skill-overview) section in Maia Agent Skills.
     * You can now add custom skills to non-protected app modules. These skills are exported together with other contents of the module.