Introducing Filesystem Skills for Mastra Workspaces

Your agents can now share and reuse filesystem skills for common or agent-specific tasks.

Choose from a number of supported filesystem providers to host your skills, or use multiple filesystems in the same workspace. Use providers your team already knows for ad hoc contributions, or engineer-managed providers for versioned skill updates.

Mastra provides two ways to configure skills.

Agent skills are configured per-agent and ship with your bundled production code. Use when skills are scoped to a single agent and don't execute scripts.
Filesystem skills are configured on workspaces and can use local or remote filesystems to store skills. Use when skills are shared across agents, or when skills need to be updated without codebase changes. Combine with a workspace sandbox to enable script execution.

In both cases, agents get the same built-in tools to read and search skills. Configure filesystem search to match skills by keyword (BM25), by semantic-similarity (vector), or both.

Get started

Install the filesystem and sandbox providers. This example uses @mastra/google-drive and @mastra/platform-workspace:

Terminal

npm install @mastra/google-drive @mastra/platform-workspace

note

Requires @mastra/core@1.66.0 or later, added in PR #11986.

Create a workspace with mounts, a sandbox, and a skills path.

mounts: One or more storage providers, each accessible at its own path.
sandbox: Required to run executables from a skill's scripts/ folder.
skills: Paths inside the mounts where Mastra discovers SKILL.md files.

src/mastra/workspaces/skills-workspace.ts

import { Workspace } from "@mastra/core/workspace";
import { GoogleDriveFilesystem } from "@mastra/google-drive";
import { PlatformFilesystem, PlatformSandbox } from "@mastra/platform-workspace";
 
export const skillsWorkspace = new Workspace({
  id: "skills-workspace",
  mounts: {
    "/common-skills": new GoogleDriveFilesystem({
      folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
      serviceAccount: {
        clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
        privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!
      }
    }),
    "/agent-specific-skills": new PlatformFilesystem({})
  },
  sandbox: new PlatformSandbox({ idleTimeoutMinutes: 30 }),
  skills: ["/common-skills/skills", "/agent-specific-skills/skills"]
});

Skills

The /common-skills mount points at a Google Drive folder. Editable by team members with access to the shared drive:

Google Drive folder

└── skills/
    ├── dev-humor/
    │   ├── SKILL.md
    │   └── references/
    │       ├── tropes.md
    │       └── setups.md
    ├── meme-voice/
    │   └── SKILL.md
    └── poem-voice/
        └── SKILL.md

The /agent-specific-skills mount points at a Mastra Platform bucket. Editable through the platform API:

Mastra Platform bucket

└── skills/
    ├── meme-generation/
    │   ├── SKILL.md
    │   ├── references/
    │   │   ├── templates.md
    │   │   └── api.md
    │   └── scripts/
    │       └── find-template.sh
    └── poem-forms/
        └── SKILL.md

Scripts

Scripts in a skill's scripts/ folder require a configured sandbox to execute.

src/mastra/workspaces/skills-workspace.ts

import { Workspace } from "@mastra/core/workspace";
import { PlatformSandbox } from "@mastra/platform-workspace";
 
export const skillsWorkspace = new Workspace({
  // ...
  sandbox: new PlatformSandbox({ idleTimeoutMinutes: 30 })
});

Agents

Attach the workspace to any agents to use the filesystem skills:

src/mastra/agents/meme-agent.ts

import { Agent } from "@mastra/core/agent";
import { skillsWorkspace } from "../workspaces/skills-workspace";
 
export const memeAgent = new Agent({
  id: "meme-agent",
  name: "Meme Agent",
  instructions: /* ... */,
  model: "openai/gpt-6-astra",
  workspace: skillsWorkspace
});

src/mastra/agents/poem-agent.ts

import { Agent } from "@mastra/core/agent";
import { skillsWorkspace } from "../workspaces/skills-workspace";
 
export const poemAgent = new Agent({
  id: "poem-agent",
  name: "Poem Agent",
  instructions: /* ... */,
  model: "openai/gpt-6-astra",
  workspace: skillsWorkspace
});

For more information and full configuration options, see: