Skip to main content
Mastra 1.0 is available 🎉 Read announcement

Workspace Skills

Added in: @mastra/core@1.1.0

Skills are reusable instructions that teach agents how to perform specific tasks. They follow the Agent Skills specification - an open standard for packaging agent capabilities.

A skill is a folder containing:

  • SKILL.md: Instructions and metadata for the agent
  • references/: Supporting documentation (optional)
  • scripts/: Executable scripts (optional)
  • assets/: Images and other files (optional)
Folder structure
/skills
  /code-review
    SKILL.md
    /references
      style-guide.md
      pr-checklist.md
    /scripts
      lint.ts

When skills are configured on a workspace, agents can discover and activate them during conversations.

SKILL.md format
Direct link to SKILL.md format

Follow the official skill specification when creating your skill. Here is an example SKILL.md for a code review skill:

SKILL.md
---
name: code-review
description: Reviews code for quality, style, and potential issues
version: 1.0.0
tags:
  - development
  - review
---

# Code Review

You are a code reviewer. When reviewing code:

1. Check for bugs and edge cases
2. Verify the code follows the style guide in references/style-guide.md
3. Suggest improvements for readability
4. Run the linter using scripts/lint.ts

## What to look out for

- Unused variables and imports
- Missing error handling
- Security vulnerabilities
- Performance issues

Configuring skills
Direct link to Configuring skills

Enable skill discovery by setting the skills option on your workspace:

src/mastra/workspaces.ts
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['/skills'],
});

The skills directory is relative to your basePath. You can specify multiple skill directories:

src/mastra/workspaces.ts
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    '/skills',      // Project skills
    '/team-skills', // Shared team skills
  ],
});

Dynamic skills
Direct link to Dynamic skills

For dynamic skill paths based on context, pass a function:

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: (context) => {
    const paths = ['/skills'];
    if (context.user?.role === 'developer') {
      paths.push('/dev-skills');
    }
    return paths;
  },
});

How agents use skills
Direct link to How agents use skills

When an agent activates a skill, the skill's instructions are added to the conversation context. The agent can then follow those instructions and access the skill's references and scripts.

Under the hood this involves:

  1. Lists available skills in the system message
  2. Allows agents to activate skills during conversation
  3. Provides access to skill references and scripts

If BM25 or vector search is enabled on the workspace, skills are automatically indexed. Agents can search across skill content to find relevant instructions.

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['/skills'],
  bm25: true,
});
On this page