Maia skills🔗

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

Skills are:

Intelligently activated: Maia chooses when to use skills based on the prompts you give. For example, if you prompt Maia to "create a new table" and you have created a skill that contains guidelines on table naming conventions, Maia 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 with more context. These files can be Markdown files, pipelines, or Python or SQL scripts if these are supported in your environment.
Stackable: Maia can use multiple skills in its response if relevant. This depends on how it interprets 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 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 may use to answer your prompts, if it considers them relevant.	Provide rules that Maia will always consider when answering your prompts.
Used to inform Maia's response if Maia interprets them as suitable for the task it is working on.	Always used to inform Maia's response, no matter what your prompt is.
Should be used to give Maia task-specific, context-dependent instructions.	Should be used for instructions that you want Maia 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 has access to built-in skills that are designed to help with common tasks and use cases in the Data Productivity Cloud. These built-in skills cannot be edited. The table below lists the built-in skills that Maia 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 chat interface, click the Skills drop-down menu and then click Add new skill. This will start a conversation with Maia in which you can tell Maia the purpose of the skill and ask it to build the skill for you. You can also describe the problem you are trying to solve, and ask Maia to create a corresponding skill.

For example, you could give Maia 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 creates containing the SKILL.md file. This will prompt Maia 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 prompts🔗

Maia will automatically use any relevant skills whenever you prompt Maia to complete a task. If you want to tell Maia 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 Data Productivity Cloud project by clicking the Skills drop-down menu in the bottom left of the Maia 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 menu. 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 uses 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 activates it when suitable.

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