Language and structure review

Author: Yiyun333

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

@@ -12,37 +12,26 @@ description: "Describes how to create and manage agent skills that equip Maia wi
 {{% alert color="info" %}}
 This feature is released as part of [Maia Make](/refguide/maia-make/) capabilities in Studio Pro 11.11 and above.
 
-To use agent skills, an internet connection and signing in to Studio Pro are required.
+To use Maia Agent Skills, an internet connection and signing in to Studio Pro are required.
 {{% /alert %}}
 
-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.
+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, eliminating the need to repeat the same guidance across conversations.
+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 that is 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 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.
 
-For guidance on writing effective skills, see [Best Practices](https://agentskills.io/skill-creation/best-practices) and [Optimizing Descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) in the [Agent Skills documentation](https://agentskills.io/).
+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/).
 
-## How Agent Skills Work
-
-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.
+## Creating an Agent Skill {#creating-a-skill}
 
-If you add or edit a skill while a session is active, those changes take effect the next time you start a chat.
+To create a new agent skill in Studio Pro, follow these steps:
 
-For more on how skills load and when they apply, see the [Agent Skills specification](https://agentskills.io/specification).
-
-## Directory Structure {#directory-structure}
+1. In the **App Explorer**, expand **Maia** > **skills**.
+2. Right-click **skills** and click **Add** > **Skill**.
+3. Enter a name for the skill.
 
-Skills are stored in a `skillssource/` directory at the root of your app 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** (shortcut: <kbd>F4</kbd>) to make the changes visible in Studio Pro.
-
-```
-skillssource/
-  your-skill/
-    SKILL.md
-    references/
-      GLOSSARY.md
-      NOTES.md
-```
+Studio Pro creates the `SKILL.md` file. You can continue adding the skill content.
 
 ### SKILL.md Format {#skill-md-format}
 
@@ -62,32 +51,41 @@ See [my-reference](references/my-reference.md) for details.
 
 | Field | Required | Description |
 | --- | --- | --- |
-| `name` | Yes | Must match the skill's parent directory name exactly. See the [Agent Skills specification](https://agentskills.io/specification#name-field) for full naming rules. |
-| `description` | Yes | See the [Agent Skills specification](https://agentskills.io/specification#description-field). |
+| `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). |
+| `description` | Yes | See [Agent Skills Specification](https://agentskills.io/specification#description-field). |
 
-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`.
+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`.
 
-## Creating a Skill {#creating-a-skill}
+### Directory Structure {#directory-structure}
 
-To create a new agent skill:
+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.
 
-1. In the **App Explorer**, expand **Maia** > **skills**.
-2. Right-click **skills** and click **Add** > **Skill**.
-3. Enter a name for the skill.
-
-Studio Pro creates the new skill. Open the skill from the **App Explorer** to add your content.
+```
+skillssource/
+  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—a glossary of domain terms, a data dictionary, or detailed architecture notes, for example. Maia accesses reference file content on demand, only when relevant to your request.
+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:
+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.
 2. Click **Add** > **Reference**.
 3. Enter a name for the reference file.
 
-For more on how skills and reference files load, see the [Agent Skills specification](https://agentskills.io/specification#progressive-disclosure).
+For more information on how skills and reference files load, and when they apply, see [Agent Skills Specification](https://agentskills.io/specification#progressive-disclosure).
+
+## How Agent Skills Work
+
+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.
+
+If you add or edit a skill while a session is active, those changes take effect the next time you start a chat.
 
 ## Limitations {#limitations}
 
@@ -99,5 +97,5 @@ For more on how skills and reference files load, see the [Agent Skills specifica
 * [Maia Make Capabilities](/refguide/maia-make/)
 * [Mendix AI Assistance (Maia)](/refguide/mendix-ai-assistance/)
 * [Maia Chat](/refguide/maia-chat/)
-* [Agent Skills Best Practices](https://agentskills.io/skill-creation/best-practices) – guidance on writing effective skill content
+* [Best Practices for Skill Creators](https://agentskills.io/skill-creation/best-practices) – guidance on writing effective skill content
 * [Agent Skills Specification](https://agentskills.io/specification) – the full specification for the agent skills format