Workspace skills

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.

note

Workspace skills are discovered through a workspace and shared with every agent that uses it. To attach skills directly to one agent without requiring a workspace, use agent skills.

When to use skills

Use workspace skills when your agent needs to:

• Follow repeatable instructions for specialized tasks
• Load detailed guidance only when it becomes relevant
• Share instructions, reference files, scripts, and assets across agents
• Discover capabilities from one or more directories
• Search skill content alongside other workspace content

Quickstart

Create a skill with a SKILL.md file:

workspace/skills/code-review/SKILL.md

---
name: code-review
description: Reviews code for bugs and readability issues
---

# Code review

Check the code for bugs, missing error handling, and unclear naming.

Configure the skill directory on a workspace:

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

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

Agents that use this workspace can now discover and load the code-review skill when needed.

Skill structure

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

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

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
  ],
})

You can also pass a direct path to a skill directory or SKILL.md file:

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['path/to/my-skill'],
})

Glob patterns let you discover skills across nested directories:

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

How agents use skills

When a workspace has skills configured, agents automatically get access to skill tools. Available skills are listed in the system message so the agent knows what's available, and the agent can load any skill on demand.

The agent has three skill tools:

• skill: Loads a skill's full instructions and returns them in the tool result. The agent calls this whenever it needs a skill's guidance.
• skill_read: Reads a file from a skill's references/, scripts/, or assets/ directory.
• skill_search: Searches across all skill content. Uses BM25 or vector search when configured, otherwise falls back to basic text matching.

Skill tools are registered when skills are configured. They aren't part of WORKSPACE_TOOLS, which configures filesystem, sandbox, search, and LSP tools.

This design is stateless, there is no activation state to track. If the skill instructions leave the conversation context (due to context window limits or compaction), the agent can call skill again to reload them.

Same-named skills

When multiple skill directories contain a skill with the same name, all of them are discovered and listed. The agent sees every skill in its system message, along with each skill's path and source type, so it can tell them apart.

When the agent activates a skill by name, tie-breaking determines which one is returned:

1. Source-type priority: local skills take precedence over managed (.mastra/) skills, which take precedence over external (node_modules/) skills.
2. Unresolvable conflicts throw: if two skills share the same name and the same source type (for example, two local skills that both use the name brand-guidelines), get() throws an error. Rename one or move it to a different source type to resolve the conflict.
3. Path escape hatch: the agent can pass a skill's full path instead of its name to activate a specific skill, bypassing tie-breaking entirely.

Example: local skill shadows an external package skill

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    'node_modules/@myorg/skills', // external: provides "brand-guidelines"
    'skills', // local: also provides "brand-guidelines"
  ],
})

// get('brand-guidelines') returns the local copy (local > external)
// get('node_modules/@myorg/skills/brand-guidelines') returns the external copy

Skill search

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,
})

Custom skill source

By default, skills are read from the workspace filesystem. For advanced use cases, provide a custom skillSource to load skills from a different backend.

VersionedSkillSource serves published skill versions from a content-addressable blob store, so production agents use a specific published version without touching the live filesystem:

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { VersionedSkillSource } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
  skillSource: new VersionedSkillSource(versionTree, blobStore, versionCreatedAt),
})

VersionedSkillSource accepts three parameters:

• versionTree (SkillVersionTree): A manifest mapping relative file paths to blob entries ({ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }).
• blobStore (BlobStore): A content-addressable blob store instance that holds the actual file contents referenced by hash.
• versionCreatedAt (Date): The timestamp when this skill version was published. Used as the modification time for all files in the version.

When skillSource is provided, it's used instead of the workspace filesystem for skill discovery.

Agent-level skills

You can also attach skills directly to an agent without a workspace using createSkill() and the agent's skills config. When both agent-level and workspace-level skills exist, they merge, agent-level skills take precedence on name conflicts.

See Agent skills for details.

Dynamic skills

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

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ctx => {
    const paths = ['skills']
    if (ctx.requestContext?.get('userRole') === 'developer') {
      paths.push('dev-skills')
    }
    return paths
  },
})

Related

• Agent skills
• Agent skills specification
• Sandbox
• Search and indexing
• createSkill() reference