Filesystem-backed skills

Filesystem-backed skills are directories of reusable instructions and supporting files. Mastra discovers them from paths in the skills option, then makes them available to every agent using that configuration. Skills follow the Agent Skills specification.

Use agent skills instead when you want to define a skill directly in one agent's code. An agent can use both types. If a direct agent skill and a filesystem-backed skill have the same name, the direct agent skill takes precedence.

Quickstart

Create a directory 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 directory:

src/mastra/workspaces.ts

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

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

The skills path is relative to the filesystem root, so Mastra discovers ./workspace/skills/code-review/SKILL.md. An agent using this configuration can now discover and load code-review when a request needs it.

Skill structure

Each skill is a directory with a required SKILL.md file. It can also contain supporting files:

workspace/skills/code-review

code-review/
  SKILL.md
  references/
    style-guide.md
  scripts/
    lint.ts
  assets/
    review-template.md

• SKILL.md: Metadata and instructions that Mastra loads when the agent selects the skill
• references/: Documentation that the agent can read or search as needed
• scripts/: Scripts used by the skill
• assets/: Templates, images, and other supporting files

Keep the main workflow in SKILL.md. Move detailed material to references/ so the agent only reads it when needed.

SKILL.md format

The YAML frontmatter requires name and description. The name must match the skill directory name, contain at most 64 lowercase letters, numbers, or hyphens, not start or end with a hyphen, and not contain consecutive hyphens. The Markdown body contains the instructions returned to the agent when it loads the skill.

Mastra also reads the optional license, compatibility, user-invocable, and metadata fields. See the Agent Skills specification for the complete package format and field guidance.

How agents use skills

When skills are configured, Mastra adds each skill's name, description, path, and source type to the system message. This lets the agent discover available skills without loading every instruction file into its context.

Mastra also gives the agent three tools:

Tool	Does
skill	Loads a skill's SKILL.md instructions and lists its reference, script, and asset files.
skill_read	Reads all or part of any file under the selected skill directory.
skill_search	Searches skill names, descriptions, instructions, and reference files.

Loading is stateless. The instructions remain in the conversation as a tool result, and the agent can call skill again if they leave the context after compaction.

Turn off the skills list

With many skills, listing all of them in the system message costs tokens on every request. Add SkillsProcessor with injectCatalog: false to replace the list with a short instruction to find skills with skill_search and load them with skill:

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { SkillsProcessor } from '@mastra/core/processors'
import { workspace } from '../workspaces'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support Agent',
  instructions: 'You help customers with support requests.',
  model: 'openai/gpt-6.1-sol',
  workspace,
  inputProcessors: [new SkillsProcessor({ injectCatalog: false })],
})

The agent keeps the skill, skill_read, and skill_search tools for both filesystem-backed and agent skills. skill_search works without any search setup: it matches query words against skill names, descriptions, and content. For larger collections, configure BM25 or vector search on the workspace to improve ranking. Agent skills are always indexed.

Keep the default list when you have a few dozen skills: the agent sees every option at once, and the list is a stable prefix that providers can cache. Turn it off when you have around a hundred skills or more, or when the size of the system message matters. The search instruction stays the same size however many skills you add.

SkillSearchProcessor also hides the list, but replaces the standard tools with its own search_skills and load_skill tools and only covers workspace skills. Configure one or the other, not both: together, the agent gets both sets of tools. See the SkillsProcessor reference for all options.

Configure skill paths

The skills array accepts several path forms:

Path	Discovery behavior
skills	Scans each immediate subdirectory for a SKILL.md file.
skills/code-review	Loads one skill directory directly.
skills/code-review/SKILL.md	Loads one skill file directly.
./**/skills	Finds matching directories, then discovers skills under each one.
./**/SKILL.md	Finds and loads matching skill files.

Add more entries to discover skills from several roots, such as project, team, or package directories.

Glob traversal is limited to four directory levels below the glob base.

Paths use the configured filesystem when one is available. Without a filesystem, Mastra reads them from local disk relative to the application process's current working directory. An explicit skillSource replaces both defaults.

Same-named skills

Mastra lists every distinct filesystem-backed skill in the system message, including its path and source type. If several skills have the same name, a lookup by name uses this priority:

1. Local project paths
2. Managed paths under .mastra/skills
3. External paths under node_modules

If multiple highest-priority candidates have the same source type, Mastra can't choose between them and throws an error. Rename one skill or move it to a different source type.

The agent can bypass name-based resolution by passing the exact path shown in the system message to skill or skill_read. Paths with or without the trailing /SKILL.md work. If several configured paths resolve to the same canonical directory, Mastra treats them as aliases and lists the skill once.

Direct agent skills are resolved before filesystem-backed skills. A direct skill wins when both types use the same name.

Search skill content

When BM25 or vector search is configured alongside skills, Mastra automatically indexes each skill's name, description, SKILL.md instructions, and reference files. Scripts and assets aren't indexed.

Without BM25 or vector search, skill_search falls back to case-insensitive text matching across the name, description, instructions, and references. Results are ranked by how many query words they contain, and words found in a skill's name or description count more. This keeps skill search available without a separate search configuration, while indexed search provides ranking and semantic retrieval for larger collections.

A result from a reference file includes the file path, such as references/style-guide.md, so the agent can pass it to skill_read.

When the agent asks for a skill name that doesn't exist, skill and skill_read list every available skill if there are 20 or fewer. With more skills, they suggest up to five close matches and point the agent to skill_search, so a mistyped name doesn't add the whole skill list to the conversation.

Dynamic skill paths

Pass a synchronous or asynchronous function when the available paths depend on request context. This example adds development skills for users with the developer role:

src/mastra/workspaces.ts

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

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

    if (requestContext?.get('user-role') === 'developer') {
      paths.push('developer-skills')
    }

    return paths
  },
})

Mastra resolves the function for each execution and gives the agent the skill set for that request. The returned paths support the same directory, file, and glob forms as a static array.

Custom skill sources

Set skillSource when skills should come from a backend other than the configured filesystem or local disk. A custom source handles skill discovery and file reads for every configured path.

For example, CompositeVersionedSkillSource mounts published skill versions from a content-addressable blob store under directories where Mastra can discover them:

src/mastra/workspaces.ts

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

const skillSource = new CompositeVersionedSkillSource(
  [
    {
      dirName: 'code-review',
      tree: versionTree,
      versionCreatedAt,
    },
  ],
  blobStore,
)

const workspace = new Workspace({
  skills: ['.'],
  skillSource,
})

An explicit skillSource doesn't fall back to the configured filesystem or local disk when a path is missing. See the configuration reference for the source interface and related options.

Related

• Agent skills
• Agent Skills specification
• Sandboxes
• Search and indexing
• createSkill() reference