-
Notifications
You must be signed in to change notification settings - Fork 784
Add Maia Agent Skills documentation #11203
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
KONRADS098
wants to merge
6
commits into
mendix:development
Choose a base branch
from
KONRADS098:maia-skills-support
base: development
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
930025d
Add Maia Agent Skills documentation
KONRADS098 d6f7534
Language and structure review
Yiyun333 e5e3131
Review the "Maia Make Capabilities" index page and consistency check …
Yiyun333 d38c5a0
Reorganize Maia Make capabilities documentation
KONRADS098 a1f0350
Review tables for categorizing Maia Make capabilities
Yiyun333 0f927e3
Remove the Description column from the Supported Document Types table
Yiyun333 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
101 changes: 101 additions & 0 deletions
101
content/en/docs/refguide/mendix-ai-assistance/maia-make/maia-agent-skills.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| --- | ||
| title: "Maia Agent Skills" | ||
| linktitle: "Agent Skills" | ||
| url: /refguide/maia-agent-skills/ | ||
| weight: 95 | ||
| description: "Describes how to create and manage agent skills that equip Maia with domain-specific knowledge, applied automatically whenever relevant." | ||
| #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.11. | ||
|
|
||
| To use Maia Agent Skills, an internet connection and signing in to Studio Pro are required. | ||
| {{% /alert %}} | ||
|
Yiyun333 marked this conversation as resolved.
|
||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| Studio Pro creates the `SKILL.md` file. You can continue adding the skill content. | ||
|
|
||
| ### SKILL.md Format {#skill-md-format} | ||
|
|
||
| Each `SKILL.md` file must include YAML frontmatter at the top, followed by the skill content in Markdown: | ||
|
|
||
| ```yaml | ||
| --- | ||
| name: your-skill | ||
| description: Applies company-wide naming conventions for entities, attributes, and microflows. | ||
| --- | ||
|
|
||
| Write your skill instructions here in plain Markdown. Use the `references/` subdirectory | ||
| to add supplementary content and refer to it from here as needed. | ||
|
|
||
| See [my-reference](references/my-reference.md) for details. | ||
| ``` | ||
|
|
||
| | Field | Required | Description | | ||
| | --- | --- | --- | | ||
| | `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`. | ||
|
|
||
| ### 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. | ||
|
|
||
| ``` | ||
| 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, 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. | ||
| 2. Click **Add** > **Reference**. | ||
| 3. Enter a name for the reference file. | ||
|
|
||
| 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} | ||
|
|
||
| * Only Markdown files are supported as reference files. Files in other formats are ignored. | ||
| * Changes you make to skills take effect the next time you start a chat. | ||
|
|
||
| ## Read More | ||
|
|
||
| * [Maia Make Capabilities](/refguide/maia-make/) | ||
| * [Mendix AI Assistance (Maia)](/refguide/mendix-ai-assistance/) | ||
| * [Maia Chat](/refguide/maia-chat/) | ||
| * [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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Yiyun333 Are OQL, Navigation, and Menu considered as "documents"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@KONRADS098 Navigation and Menu are, but I am not sure about OQL :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
AFAIK OQL is only a property of the data model (including view entities)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@KONRADS098 let's check with the others.