KakaFlow KB

Workspace skills

7 phút đọc

Workspace skills

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Guide for configuring and using workspace skills in Mastra, teaching agents how to perform specific tasks by loading reusable instruction sets.

Insight

Skills are reusable instruction packages that follow the Agent Skills specification (agentskills.io). A skill is a folder containing SKILL.md (instructions and metadata), optional references/ (supporting docs), scripts/ (executable scripts), and assets/ (images/files). Skills are configured on a Workspace via the skills option accepting string paths, arrays of paths, glob patterns, or dynamic functions. The skill folder structure uses named subdirectories like skills/code-[[concepts/danh-gia|Đánh giá / Reviews]]/SKILL.md. SKILL.md follows YAML frontmatter format with name, description, version, and tags fields. When skills are configured, agents automatically access three skill tools: skill (loads full instructions), skill_read (reads files from references/scripts/assets), and skill_search (searches across all skill content using BM25 or vector search). Skill resolution for same-named skills follows source-type priority: local > managed (.mastra/) > external (node_modules/). Conflicts with identical names and source types throw an error; use full paths as an escape hatch. VersionedSkillSource enables loading skills from a content-addressable blob store for production pinned versions, accepting versionTree, blobStore, and versionCreatedAt parameters. BM25 or vector search can be enabled to auto-index skills for agent discovery.

Hành động

To configure skills, import Workspace and LocalFilesystem from @mastra/core/workspace. Create a Workspace instance with the skills option set to paths (string, array, glob pattern, or function). Enable skill discovery by setting skills: ['skills'] or multiple directories with skills: ['skills', 'team-skills']. For dynamic paths based on context, pass a function: skills: ctx => { ... }. Agents automatically gain skill tools when workspace has skills configured, listing available skills in system messages. Search is enabled with bm25: true or vector search on the workspace. For versioned production deployment, import VersionedSkillSource and provide versionTree, blobStore, and versionCreatedAt parameters.

Kết quả

Agents automatically discover and activate configured skills during conversations. Skills are listed in the system message. The agent can reload skill instructions by calling the skill tool again if they leave context. Same-named skills resolve by source-type priority (local > managed > external). get() throws an error for unresolvable conflicts (same name and source type). VersionedSkillSource serves pinned skill versions from blob storage.

Điều kiện áp dụng

Added in @mastra/[email protected]. Requires Workspace and LocalFilesystem from @mastra/core/workspace.

Nội dung gốc (Original)

Workspace skills

Added in: @mastra/[email protected]

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

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

---
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

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

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

You can specify multiple skill directories:

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

Dynamic skills

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

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.

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 both named 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.
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

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.

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược