You can now add skills directly to your Mastra agents. Download packaged ones or write your own. Use them with both code-registered or file-based agents.

We first shipped agent skills in February, but scoped them to a workspace. We still recommend workspace scoping when your skill needs to run scripts or work with a filesystem. But for most skills, you can now use a more streamlined approach.

You can add skills either in code or in a markdown file (with file-based agents).

For a single agent, you can add both workspace-level and agent-level skills – they’re merged at runtime. Agent-level skills take precedence, which lets you overwrite workspace-based skills.

Get started

Setting up skills differs slightly between code-registered and file-based agents. Here's a simplified example for each.

Code-registered agents

Define the skill using createSkill():

import { createSkill } from "@mastra/core/skills";
 
export const forecasting = createSkill({
  name: "forecasting",
  description: "Use when the user asks about multi-day forecasts.",
  instructions: `
    When summarizing a multi-day forecast:
    1. Report each day's high and low
    2. Call out precipitation chances
    3. Note any significant changes between days
  `
});

Import a skill and add it to an agent's skills array:

import { Agent } from "@mastra/core/agent";
import { forecasting } from "../skills/forecasting";
 
export const weatherAgent = new Agent({
  // ...
  skills: [forecasting]
});

Code-registered agents can also accept a function for skills: that reads requestContext values — letting you swap skills for different users, tenants, or roles.

File-based agents

Create a markdown file in an agent's skills/ folder:

└── weather-agent/
    ├── config.ts
    ├── instructions.md
    // ...
    └── skills/
        └── forecasting.md
        └── temperature-units.ts // Defined using createSkill()

The filename becomes the skill's name, and the body is the instructions:

When summarizing a multi-day forecast:
 
1. Report each day's high and low
2. Call out precipitation chances
3. Note any significant changes between days

In both cases, agents get access to skill, skill_read, and skill_search tools so they can discover and load skills during conversations.

For more information and full configuration options, see:

• Agent skills
• File-based agents — Add skills
• Workspace skills