Maia AI Agents skills🔗

A skill is a set of reusable instructions that Maia AI Agents can use to better respond to your prompts. Skills are useful if you often give Maia AI Agents repetitive prompts—they provide guidelines and standards for Maia AI Agents to follow, which means you don't need to include this information in every prompt.

Skills are:

Intelligently activated: Maia AI Agents choose when to use skills based on the prompts you give. For example, if you prompt Maia AI Agents to "create a new table" and you have created a skill that contains guidelines on table naming conventions, Maia AI Agents can choose to use this skill when creating your new table.
Resource-aware: Skills can reference additional files, such as template documents or example pipelines, that are stored in the same folder as the skill file. These can be used to provide Maia AI Agents with more context. These files can be Markdown files, pipelines, or Python or SQL scripts if these are supported in your environment.
Stackable: Maia AI Agents can use multiple skills in their response if relevant. This depends on how they interpret your prompt, as described above.

For more information about agent skills in a wider context, read the Agent Skills documentation.

When to use skills and context files🔗

Skills and context files should be used in different ways to help Maia AI Agents understand your data and provide better responses to your prompts. The table below clarifies some of the differences between skills and context files.

Skills	Context files
Provide guidelines or additional context that Maia AI Agents may use to answer your prompts, if they consider the guidelines relevant.	Provide rules that Maia AI Agents will always consider when answering your prompts.
Used to inform Maia AI Agents' response if Maia AI Agents interpret the skills as suitable for the task they are working on.	Always used to inform Maia AI Agents' response, no matter what your prompt is.
Should be used to give Maia AI Agents task-specific, context-dependent instructions.	Should be used for instructions that you want Maia AI Agents to consider in every prompt.

Skill best practices🔗

Write effective skill descriptions
- Clearly define the trigger: Describe the specific scenarios or tasks where this skill applies.
- Use keywords: Include terms that are likely to appear in related prompts.
- Avoid overlap: Ensure each skill has a distinct purpose that doesn't conflict with other skills.
Structure skill instructions clearly
- Start with the goal: Begin with what the skill should accomplish.
- Provide step-by-step guidance: Break complex procedures into numbered steps.
- Include templates: If the skill produces structured output, provide example templates.
- Specify constraints: Note any requirements, limitations, or standards that apply.
Test and refine skills
- Test with varied prompts: Try different phrasings to ensure the skill activates appropriately.
- Check for false activations: Verify the skill doesn't trigger for unrelated tasks.
- Iterate based on results: Refine instructions when outputs don't match expectations.
- Keep skills focused: If a skill becomes too broad, consider splitting it into multiple targeted skills.

Built-in skills🔗

Maia AI Agents have access to built-in skills that are designed to help with common tasks and use cases in Maia. These built-in skills cannot be edited. The table below lists the built-in skills that Maia AI Agents can use to respond to your prompts.

Built-in skill	Used for
Iterator components	Building pipelines that loop through data, such as iterating over rows or grids, or running a component multiple times with different variable values

Create a skill🔗

To create a skill, in the bottom left of the Maia AI Agents chat interface, click the Skills drop-down and then click Add new skill. This will start a conversation with Maia AI Agents in which you can tell Maia AI Agents the purpose of the skill and ask them to build the skill for you. You can also describe the problem you are trying to solve, and ask Maia AI Agents to create a corresponding skill.

For example, you could give Maia AI Agents the following prompts:

"Create a skill to enforce naming standards for all new tables and columns."
"Create a skill for loading data from Jira, using @my-jira-pipeline as an example pipeline. All new pipelines loading data from Jira should use the same authentication and connection options."

In the second example, you can add the my-jira-pipeline orchestration pipeline to the folder that Maia AI Agents create containing the SKILL.md file. This will prompt Maia AI Agents to use the example pipeline as additional context when using this skill.

Making skills available at project level🔗

Skills are committed and pushed in the same way as pipelines in your project. Once you have created a skill in your branch and pushed it to the remote, other users in the same project can merge from branch to pull your changes into their own branch. This will allow them to use the skill you have created.

Use skills in Maia AI Agents prompts🔗

Maia AI Agents will automatically use any relevant skills whenever you prompt Maia AI Agents to complete a task. If you want to tell Maia AI Agents to use a specific skill, type @ in the chat interface, followed by the name of your skill. The SKILL.md file in the corresponding skill's folder will appear in a dynamic list—press Enter or click the skill to reference it in your prompt.

View and edit skills🔗

You can view a list of all skills available in your Maia project by clicking the Skills drop-down in the bottom left of the Maia AI Agents chat interface.

Skills are stored in your project in a folder in the following location: .matillion/maia/skills/[skill name]/SKILL.md.

To edit a skill, open the SKILL.md file for the corresponding skill. You can do this in two ways:

Click the Skills drop-down. Open the Project section of the skills list, and click the Edit icon next to the name of the skill you want to edit.
In the Files panel, navigate to the SKILL.md file.

At the top of the SKILL.md file, you will see the name of the skill, and its description. Maia AI Agents use the description of your skill to determine when to use this skill. We recommend being as specific as possible about the purpose of this skill, so that Maia AI Agents activate it when suitable.

The rest of the file contains the information that Maia AI Agents need to use the skill, such as naming conventions, guidelines, and additional context. It's important to remember that Maia AI Agents will interpret these as guidance, not hard-coded rules. If you want to provide stricter instructions for Maia AI Agents to follow, use context files.