Skill overview and improvements of instructions

Author: petarvukmirovic

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

@@ -53,7 +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** – lets you define project- or module-level instructions (AGENTS.md) that steer agent behavior. Use them to set common context for your prompts, such as naming conventions or language preferences, so they are automatically included whenever relevant. For more information, see [Maia Agent Instructions](/refguide/maia-instructions/).
+* **Maia Agent Instructions** – lets you define project- or module-level instructions (AGENTS.md) that steer agent behavior. Use them to set common context for your prompts, such as company conventions or environment restrictions, so they are automatically included whenever relevant. For more information, see [Maia Agent Instructions](/refguide/maia-instructions/).
 
 Recommenders:
 

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

@@ -104,10 +104,19 @@ 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 only information Maia uses to decide whether to read your skill.
+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
+
+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 skill overview pane. The pane shows whether each skill loaded
+successfully, including any error message, the references that were found, and the module the skill belongs to.
+
+Updates to skills, whether you add a new skill or change an existing one, appear only after you start a new session.
+You can force Maia to sync skill information mid-session by clicking **Sync** in the skill overview 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

@@ -15,20 +15,21 @@ This feature was released as part of [Maia Make](/refguide/maia-make/) capabilit
 To use Maia Agent Instructions, an internet connection and signing in to Studio Pro are required.
 {{% /alert %}}
 
-Maia Instructions are a [standard-compliant](https://agents.md) way to steer the behavior of the agent for your project or module. They allow you to define common
-context of your prompts (such as naming conventions or styling preferences) only once as they are automatically loaded when necessary.
+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 on the project level or on the module level. Project-level instructions are automatically included in every conversation started within the given project. Module-level instructions are automatically included whenever documents in the given module are read, updated, or created.
+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:
 
 |               | Instructions                                                                                        | Skills                                                                                   |
 | ------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| Loading       | Deterministically loaded, whenever working with the given project or module                         | Agent decides to load skills on demand, based on their description                       |
-| Applicability | Project or module-wide instructions that should always be part of context (e.g. preferred language) | Instructions that are applicable only in certain situations (e.g. microflow conventions) |
-| Organization  | Single file, should be kept as short as possible                                                    | Allows you to split instructions into multiple files that Maia reads on demand as needed |
+| 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}