Revise Maia Make docs

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

@@ -7,17 +7,17 @@ description_list: true
 #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 
+## Introduction
 
 {{% alert color="info" %}}
 Maia Make capabilities are available in Studio Pro 11.8 and above.
 
-To use Maia Make capabilities, an internet connection and signing in to Studio Pro are required.
+To use Maia Make capabilities, you need an internet connection and must be signed in to Studio Pro.
 {{% /alert %}}
 
-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. 
+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.
 
-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.
+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. It also supports story-based development by generating app artifacts based on existing user stories.
 
 ## Maia Make Capabilities Overview
 
@@ -51,12 +51,12 @@ The following table lists Maia Make Standalone Capabilities and the Studio Pro v
 | Capability | Description | Available in Maia Make from | Remarks |
 | --- | --- | --- | --- |
 | [Maia Chat](/refguide/maia-chat/) | Answers questions about all aspects of Mendix development. | Studio Pro 11.8 | |
-| [Maia Explain](/refguide/maia-explain/) | Explains the purpose and logic of existing documents. | Studio Pro 11.8 | |
+| [Maia Explain](/refguide/maia-explain/) | Explains the purpose and logic of existing documents. | Studio Pro 11.8 | Can be used directly in the chat interface, or in the App Explorer by right-clicking a document and clicking **Maia Explain**. |
 | [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 Instructions](/refguide/maia-instructions/) | Extends Maia with instructions to be followed with every prompt. | Studio Pro 11.12 | |
 
 ### Maia Make General Capabilities
 
@@ -66,7 +66,7 @@ The following table lists the general capabilities of Maia Make and the Studio P
 | --- | --- | --- | --- |
 | Story-based development | Generates app artifacts based on existing user stories to support story-driven development workflows. | Studio Pro 11.8 | |
 | PDF/image support | Allows you to provide PDFs and images as input to help Maia better understand your requirements. | Studio Pro 11.8 | |
-| Adding documents as context | Lets you add relevant documents, to provide Maia with additional context. | Studio Pro 11.8 | |
+| Adding documents as context | Lets you add relevant documents to provide Maia with additional context. | Studio Pro 11.8 | |
 | Editing existing documents | Enables Maia to modify existing documents, including renaming elements. | Studio Pro 11.8 | |
 | Removing elements | Allows Maia to remove elements from documents to support more advanced refactoring tasks. | Studio Pro 11.9 | |
 | Undo support | Allows you to undo Maia-generated changes on a per-document basis. | Studio Pro 11.9 | |
@@ -83,7 +83,7 @@ To access the conversational interface and Maia Make capabilities, in the upper-
 
 {{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-interface.png" max-width=40% alt="Maia Make interface" >}}
 
-Alternatively, you can also click **View** at the Studio Pro top bar and select **Maia** to open the interface.
+Alternatively, you can click **View** on the Studio Pro top bar and select **Maia** to open the interface.
 
 {{% alert color="info" %}}
 In Studio Pro 11.7 and below, the **Chat** tab is only used for [Maia Chat](/refguide/maia-chat/) where you can ask questions about all aspects of Mendix.
@@ -92,50 +92,54 @@ There is also the **Learn** tab under the **Maia** pane. It is a separate Maia c
 {{% /alert %}}
 
 {{% alert color="warning" %}}
-The Maia ({{% icon name="sparkles" %}} ) icon on the right side of the top bar does not work in Studio Pro 11.8.
+The Maia ({{% icon name="sparkles" %}}) icon on the right side of the top bar does not work in Studio Pro 11.8.
 {{% /alert %}}
 
 ### Maia Make Capabilities Interface Overview
 
 The conversational interface includes the following features.
 
+{{% alert color="info" %}}
+Maia Make loses the conversation history if you exit Studio Pro.
+{{% /alert %}}
+
 #### New Chat
 
 Clicking **New Chat** allows you to clear the messages and start a new conversation that does not reference your current chat.
 
-{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/new-chat.jpg" width="250px" >}}
+{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/new-chat.jpg" width="250px" alt="" >}}
 
-#### Configure MCP Connections 
+#### Configure MCP Connections
 
 This option ({{% icon name="plug" %}}) allows you to connect external [MCP](https://modelcontextprotocol.io/introduction) servers to Maia, giving it access to third-party tools during chat. For more information on how to configure MCP connections, see [Maia MCP Client](/refguide/maia-mcp/).
 
-{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/configure.jpg" width="250px" >}}
+{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/configure.jpg" width="250px" alt="" >}}
 
 #### Add
 
 **{{% icon name="paperclip" %}} Add** allows you to attach images, PDFs, or user stories to help Maia understand your requirements better.
 
-{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/add.jpg" width="250px" >}}
+{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/add.jpg" width="250px" alt="" >}}
 
-#### Add file to Maia Chat 
+#### Add file to Maia Chat
 
-This option (@ icon) 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.
+This option (@ icon) 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**, where it appears in the context menu.
 
-{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/add-files.jpg" width="250px" >}}
+{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/add-files.jpg" width="250px" alt="" >}}
 
 #### Changed List
 
 A list of items added or changed by Maia appears above the chat box. Click an entry to open the relevant document. To undo all changes, click **Undo all**. To undo a single change, click the undo button on the right side of that item.
 
-{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/changed-list.png" width="250px" >}}
+{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-make-capabilities/changed-list.png" width="250px" alt="" >}}
 
 #### Clarifying Questions
 
 {{% alert color="info" %}}
 This feature is available for Studio Pro 11.12 and above.
 {{% /alert %}}
 
-When Maia needs more information, it will ask clarifying questions through a dedicated UI to improve the quality of its response.
+When Maia needs more information, it asks clarifying questions through a dedicated UI to improve the quality of its response.
 
 ## Save a Maia Session {#save-maia-session}
 
@@ -192,10 +196,58 @@ To configure an OpenAI-compatible provider, follow these steps:
 
 [Private Mendix Platform](/private-mendix-platform/) provides an environment where you can develop and deploy your applications within your own enterprise security boundary to ensure the highest levels of data security and compliance. Because Private Mendix Platform instances are hosted within the enterprise firewall, selecting an LLM provider other than the default [Mendix Platform](#mendix-platform) requires you to also configure the LLM Gateway URL.
 
-{{< figure src="/attachments/private-platform/pmp-llm-gateway.png" class="no-border" >}}
+{{< figure src="/attachments/private-platform/pmp-llm-gateway.png" class="no-border" alt="" >}}
 
 The LLM Gateway URL is configured during the installation or upgrade of Private Mendix Platform. For more information, see [Installing Maia for Private Mendix Platform](/private-mendix-platform/interactive-installation/#maia).
 
+## Best Practices
+
+### Text Input
+
+To achieve optimal results, provide context about your app or the document you are working on by describing its main use cases, customer needs, or other relevant details. The more Maia knows about what you are building, the more tailored and accurate the generated results will be.
+
+#### Providing Context
+
+Below are some examples of prompts you can use as a starting point:
+
+* The app will help users...
+* This module handles...
+* Customers need to be able to...
+* The page will be used to...
+* Generate a workflow for a process that...
+* This feature allows users to...
+
+#### Editing and Improving
+
+Below are examples of prompts you can use to ask Maia to make further edits or request explanations and suggestions for improving a document:
+
+* Can you explain the function and purpose of this document?
+* I want to add an attribute `ATTRIBUTE_NAME` to the entity `ENTITY_NAME`.
+* Can you add a button called `BUTTON_NAME` to the page?
+* I want an area on the page where users can...
+* Remove the ... widget.
+* How can I make this page more user-friendly or visually appealing?
+* Could you identify any potential issues with this document and recommend solutions?
+* Can you give me suggestions to improve this workflow?
+
+#### Workflows
+
+You can provide a BPMN image representing employee onboarding alongside your text input. Maia can analyze the image, rework it using Mendix Workflows terminology, and generate the corresponding activities. Use text input alongside the image to specify any differences. For example, "Generate a workflow based on this BPMN image, but make sure it waits before sending an email to the new employee."
+
+#### Microflows
+
+When generating microflows, consider the following additional guidelines:
+
+* **Be specific:** Clearly describe the desired outcome and the steps involved. For example, instead of using *Create a user*, use *Create a new user object, set its name attribute to 'John Doe', and commit it*.
+* **Use keywords:** Incorporate terms relevant to microflow activities, such as *create object*, *retrieve*, *change object*, *show message*, *loop*, or *decision*. This can help with correct microflow generation.
+* **Provide context:** If your microflow interacts with existing entities or attributes, mention them in your text input.
+
+### Image Input
+
+The image size is limited to 512 KB. Make sure to select a clear image to help Maia better understand your request. For example, you can provide a screenshot, a photo, a design mock-up, or a close-up picture of a drawing. Avoid heavily compressed or low-quality images, as these may result in the loss of important details.
+
+Keep in mind that Maia analyzes only the structure of the image. Maia does not change the theming of your app, such as the color scheme. This can cause some differences between the provided image and the generated page.
+
 ## Read More
 
 * [Mendix AI Assistance (Maia)](/refguide/mendix-ai-assistance/)

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

@@ -10,22 +10,21 @@ description: "Describes how to create and manage agent skills that equip Maia wi
 ## Introduction
 
 {{% alert color="info" %}}
-This feature was released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.11.
+This feature is part of [Maia Make](/refguide/maia-make/) and was introduced in Studio Pro 11.11.
 
-To use Maia Agent Skills, an internet connection and signing in to Studio Pro are required.
+To use Maia Agent Skills, you need an internet connection and must be signed in to Studio Pro.
 {{% /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.
 
 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.
+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 that captures your company's Mendix naming conventions lets Maia apply 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 modules. These skills are exportable together with the module in which they are kept
-and can help you split your skills better.
+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.
 
 {{% alert color="info" %}}
-Agents skills are not supported for Add-on and Solution modules.
+Agent 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/).
@@ -34,12 +33,12 @@ For guidance on writing effective skills, see [Best Practices for Skill Creators
 
 To create a new agent skill in Studio Pro, follow these steps:
 
-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. In the **App Explorer**, find either the **Maia** node under **App** for project-level skills, or the **Maia** node under a module if you want 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.
+Studio Pro creates the `SKILL.md` file. You can now add the skill content.
 
 ### SKILL.md Format {#skill-md-format}
 
@@ -67,9 +66,9 @@ 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. 
-You can also sync the changes by pressing the **Sync** button in the **Maia skills** overview pane.
+You can also sync the changes by clicking the **Sync** button in the **Maia skills** overview pane.
 
-Project-level skills are stored directly under `skillssource` directory:
+Project-level skills are stored directly under the `skillssource` directory:
 
 ```
 skillssource/
@@ -80,7 +79,7 @@ skillssource/
       NOTES.md
 ```
 
-Skills for particular modules are stored under `_modules` subdirectory:
+Skills for particular modules are stored under the `_modules` subdirectory:
 
 ```
 skillssource/
@@ -109,20 +108,20 @@ 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.
+Make sure to provide an informative description of a skill, as it is the primary information Maia uses to decide whether to read it.
 
 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
+From 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">}}
+{{< figure src="/attachments/refguide/mendix-ai-assistance/maia-make/maia-agent-skills/skills-pane.png" alt="" 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.
+To apply the updated skills immediately, click the **Sync** button in the **Skills** pane.
 
 ## Limitations {#limitations}