Skills
File-based Agent 从自身的 skills/ 目录发现 Skill，并在构建时将其打包。Skill 是可复用的流程或参考资料，Agent 可以在相关时加载它们，无需将所有细节都放入始终启用的 prompt。
本页介绍基于文件的约定。有关代码定义的 Skill，请参阅 Agent Skill。有关 SKILL.md 包格式，请参阅 Workspace Skill。
快速开始快速开始的直接链接
最简单的 Skill 是 skills/ 下的一个 Markdown 文件。文件名将成为 Skill 名称，description 则告诉 Agent 何时加载它。
src/mastra/agents/weather/skills/temperature-units.md
---
description: Use when reporting temperatures or comparing forecast units.
---
Always report temperatures in Celsius and Fahrenheit. Include the user's preferred unit first when known.
Skill、Tool 与 instructions 的区别Skill、Tool 与 instructions 的区别的直接链接
| 需求 | 使用 | 原因 |
|---|---|---|
| 始终启用的身份、语气或规则 | instructions.md | 模型每一轮都应看到这些指导。 |
| 带有输入和输出的可调用操作 | tools/ | 模型需要执行代码、调用 API 或产生副作用。 |
| 在相关时加载的详细参考资料或流程 | skills/ | 模型只在特定任务中需要完整指导。 |
Skill 格式Skill 格式的直接链接
Mastra 支持三种基于文件的 Skill 格式：
| 格式 | 适用场景 |
|---|---|
| TypeScript/JavaScript 模块 | 希望通过代码默认导出 createSkill() 的结果。 |
打包的 SKILL.md 目录 | Skill 包含 instructions 以及 references/ 下的支持文件。 |
| 扁平 Markdown 文件 | Skill 是一个包含 frontmatter 和 instructions 的 Markdown 文件。 |
对于打包的 Skill，SKILL.md frontmatter 中必须包含 description。扁平 Markdown Skill 的 frontmatter 中也必须包含 description。请说明何时使用该 Skill，而不只是它包含什么内容。
加载的内容加载的内容的直接链接
File-based Agent Skill 会在构建时添加到生成的 bundle 中，因此部署后的 Agent 不会从磁盘读取它们。
对于打包的 Skill，Mastra 会读取：
SKILL.md中的 metadata 和 instructions。references/直属目录下的文件，作为支持性参考内容。
参考文件以文件名作为键。发现期间会跳过 references/ 下的符号链接文件和目录。
与 config 的优先级与 config 的优先级的直接链接
发现的 Skill 会与 config.ts 中的所有 skills 合并。如果名称冲突，config.skills 优先，并会记录警告。
如果 config.skills 是函数，Mastra 会忽略发现的 Skill 并发出警告，因为值为函数的 Skill 无法进行静态合并。