Workspace Skill

加入版本： @mastra/core@1.1.0

Skill 是可复用的指令，用于教 Agent 执行特定任务。它们遵循 Agent Skills 规范，这是一项用于打包 Agent 能力的开放标准。

Skill 是包含以下内容的文件夹：

• SKILL.md：提供给 Agent 的指令和 metadata
• references/：支持文档（可选）
• scripts/：可执行脚本（可选）
• assets/：图片和其他文件（可选）

Folder structure

skills/
  code-review/
    SKILL.md
    references/
      style-guide.md
      pr-checklist.md
    scripts/
      lint.ts

在 Workspace 上配置 Skill 后，Agent 可以在对话期间发现并激活它们。

SKILL.md 格式

创建 Skill 时，请遵循官方 Skill 规范。以下是用于代码审查 Skill 的 SKILL.md 示例：

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

配置 Skill

在 Workspace 上设置 skills 选项，启用 Skill 发现：

src/mastra/workspaces.ts

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

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

可以指定多个 Skill 目录：

src/mastra/workspaces.ts

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

也可以传入 Skill 目录或 SKILL.md 文件的直接路径：

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

使用 glob 模式可以发现嵌套目录中的 Skill：

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

动态 Skill

如果运行时 Skill 路径取决于上下文，请传入函数：

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

Agent 如何使用 Skill

Workspace 配置 Skill 后，Agent 会自动获得 Skill Tool。可用 Skill 会列在系统消息中，让 Agent 知道有哪些选项；Agent 可以按需加载任意 Skill。

Agent 有三种 Skill Tool：

• skill：加载 Skill 的完整指令，并在 Tool 结果中返回。Agent 每次需要 Skill 指引时都会调用它。
• skill_read：读取 Skill 的 references/、scripts/ 或 assets/ 目录中的文件。
• skill_search：搜索所有 Skill 内容。配置后使用 BM25 或向量搜索，否则回退到基本文本匹配。

这种设计是无状态的，无需跟踪激活状态。如果 Skill 指令离开对话上下文（由于上下文窗口限制或压缩），Agent 可以再次调用 skill 重新加载。

同名 Skill

当多个 Skill 目录包含同名 Skill 时，系统会发现并列出所有 Skill。Agent 会在系统消息中看到每个 Skill 及其路径和来源类型，因此可以加以区分。

Agent 按名称激活 Skill 时，会使用以下决胜规则决定返回哪一个：

1. 来源类型优先级：本地 Skill 优先于托管（.mastra/）Skill，后者优先于外部（node_modules/）Skill。
2. 无法解决的冲突会抛出错误：如果两个 Skill 名称和来源类型都相同（例如两个本地 Skill 均名为 brand-guidelines），get() 会抛出错误。重命名其中一个，或将其移动到其他来源类型即可解决冲突。
3. 路径逃生口：Agent 可以传入 Skill 的完整路径而不是名称，直接激活特定 Skill，完全绕过决胜规则。

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

如果 Workspace 启用了 BM25 或向量搜索，Skill 会自动建立索引。Agent 可以搜索 Skill 内容来查找相关指令。

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

自定义 Skill 来源

默认情况下，从 Workspace 文件系统读取 Skill。对于高级使用场景，可提供自定义 skillSource，从其他后端加载 Skill。

VersionedSkillSource 从内容寻址的 blob Store 提供已发布的 Skill 版本，因此生产环境中的 Agent 可以使用特定发布版本，而不接触实时文件系统：

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 接受三个参数：

• versionTree（SkillVersionTree）：将相对文件路径映射到 blob 条目的清单（{ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }）。
• blobStore（BlobStore）：内容寻址的 blob Store 实例，其中保存按 hash 引用的实际文件内容。
• versionCreatedAt（Date）：该 Skill 版本的发布时间戳，用作此版本中所有文件的修改时间。

提供 skillSource 后，Skill 发现将使用它，而不是 Workspace 文件系统。

Agent 级 Skill

也可以使用 createSkill() 和 Agent 的 skills 配置，直接向不含 Workspace 的 Agent 关联 Skill。当 Agent 级和 Workspace 级 Skill 同时存在时，它们会合并；发生名称冲突时，Agent 级 Skill 优先。

有关详情，请参阅 Agent Skill。

相关内容

• Agent Skill
• Agent Skills 规范
• Workspace 概述
• 搜索和索引
• createSkill() Reference