基于文件系统的 skills

基于文件系统的 skills 是由可复用指令和支持文件组成的目录。Mastra 从 skills 选项中的路径发现它们，然后使其可供使用该配置的每个 agent 使用。Skills 遵循 Agent Skills 规范。

当你想直接在单个 agent 的代码中定义 skill 时，请改用 agent skills。一个 agent 可以同时使用两种类型。如果直接 agent skill 和基于文件系统的 skill 同名，直接 agent skill 优先。

快速开始

创建一个包含 SKILL.md 文件的目录：

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.

配置该目录：

src/mastra/workspaces.ts

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

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

skills 路径相对于文件系统根目录，因此 Mastra 会发现在 ./workspace/skills/code-review/SKILL.md。使用此配置的 agent 现在可以在请求需要时发现并加载 code-review。

Skill 结构

每个 skill 都是一个包含必需 SKILL.md 文件的目录。它还可以包含支持文件：

workspace/skills/code-review

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

• SKILL.md：Mastra 在 agent 选择该 skill 时加载的元数据和指令
• references/：agent 可以按需读取或搜索的文档
• scripts/：该 skill 使用的脚本
• assets/：模板、图像和其他支持文件

将主要工作流保留在 SKILL.md 中。将详细材料移到 references/，以便 agent 仅在需要时读取。

SKILL.md 格式

YAML frontmatter 需要 name 和 description。name 必须与 skill 目录名匹配，最多包含 64 个小写字母、数字或连字符，不能以连字符开头或结尾，也不能包含连续连字符。Markdown 正文包含 agent 加载 skill 时返回给它的指令。

Mastra 还会读取可选的 license、compatibility、user-invocable 和 metadata 字段。关于完整的包格式和字段指南，请参阅 Agent Skills 规范。

Agents 如何使用 skills

配置 skills 后，Mastra 会将每个 skill 的名称、描述、路径和来源类型添加到系统消息中。这让 agent 无需将每个指令文件都加载到上下文中即可发现可用的 skills。

Mastra 还为 agent 提供三个工具：

工具	作用
skill	加载 skill 的 SKILL.md 指令，并列出其 reference、script 和 asset 文件。
skill_read	读取所选 skill 目录下任意文件的全部或部分内容。
skill_search	搜索 skill 指令和参考文件。

加载是无状态的。指令会作为工具结果保留在对话中，如果它们在压缩后离开上下文，agent 可以再次调用 skill。

配置 skill 路径

skills 数组接受以下几种路径形式：

路径	发现行为
skills	扫描每个直接子目录中的 SKILL.md 文件。
skills/code-review	直接加载一个 skill 目录。
skills/code-review/SKILL.md	直接加载一个 skill 文件。
./**/skills	查找匹配的目录，然后在每个目录下发现 skills。
./**/SKILL.md	查找并加载匹配的 skill 文件。

添加更多条目可从多个根目录（例如项目、团队或包目录）发现 skills。

Glob 遍历限制在 glob 基础目录下最多四层目录。

当有可用文件系统时，路径使用配置的文件系统。没有文件系统时，Mastra 从本地磁盘相对于应用进程的当前工作目录读取它们。显式的 skillSource会替换这两种默认行为。

同名 skills

Mastra 会在系统消息中列出每个不同的基于文件系统的 skill，包括其路径和来源类型。如果多个 skills 同名，按名称查找时使用以下优先级：

1. 本地项目路径
2. .mastra/skills 下的托管路径
3. node_modules 下的外部路径

如果多个最高优先级候选项具有相同的来源类型，Mastra 无法在它们之间选择并会抛出错误。请重命名其中一个 skill，或将其移动到不同的来源类型。

Agent 可以通过将系统消息中显示的精确路径传给 skill 或 skill_read 来绕过基于名称的解析。带或不带尾部 /SKILL.md 的路径都可以。如果多个配置路径解析到同一规范目录，Mastra 会将它们视为别名并仅列出该 skill 一次。

直接 agent skills会先于基于文件系统的 skills 解析。当两种类型使用相同名称时，直接 skill 胜出。

搜索 skill 内容

当配置了 BM25 或向量搜索以及 skills 时，Mastra 会自动索引每个 skill 的 SKILL.md 指令和参考文件。脚本和 assets 不会被索引。

没有 BM25 或向量搜索时，skill_search 会回退到对指令和参考文件进行不区分大小写的文本匹配。这使 skill 搜索无需单独的搜索配置即可使用，而索引搜索为更大的集合提供排名和语义检索。

动态 skill 路径

当可用路径取决于 request context 时，传入同步或异步函数。此示例为具有 developer 角色的用户添加开发 skills：

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 会为每次执行解析该函数，并为 agent 提供该请求对应的 skill 集。返回的路径支持与静态数组相同的目录、文件和 glob 形式。

自定义 skill 来源

当 skills 应来自配置的文件系统或本地磁盘之外的另一个后端时，设置 skillSource。自定义来源会为每个配置路径处理 skill 发现和文件读取。

例如，CompositeVersionedSkillSource 将来自内容寻址 blob 存储的已发布 skill 版本挂载到 Mastra 可以发现它们的目录下：

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

显式的 skillSource 在路径缺失时不会回退到配置的文件系统或本地磁盘。关于来源接口和相关选项，请参阅配置参考。

相关

• Agent skills
• Agent Skills 规范
• Sandboxes
• 搜索与索引
• createSkill() 参考