> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Skills

File-based Agent 从自身的 `skills/` 目录发现 Skill，并在构建时将其打包。Skill 是可复用的流程或参考资料，Agent 可以在相关时加载它们，无需将所有细节都放入始终启用的 prompt。

本页介绍基于文件的约定。有关代码定义的 Skill，请参阅 [Agent Skill](https://mastra.zisheng.pro/docs/agents/skills)。有关 `SKILL.md` 包格式，请参阅 [Workspace Skill](https://mastra.zisheng.pro/docs/workspace/skills)。

## 快速开始

最简单的 Skill 是 `skills/` 下的一个 Markdown 文件。文件名将成为 Skill 名称，`description` 则告诉 Agent 何时加载它。

```markdown
---
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 的区别

| 需求               | 使用                                                                                       | 原因                      |
| ---------------- | ---------------------------------------------------------------------------------------- | ----------------------- |
| 始终启用的身份、语气或规则    | [`instructions.md`](https://mastra.zisheng.pro/reference/file-based-agents/instructions) | 模型每一轮都应看到这些指导。          |
| 带有输入和输出的可调用操作    | [`tools/`](https://mastra.zisheng.pro/reference/file-based-agents/tools)                 | 模型需要执行代码、调用 API 或产生副作用。 |
| 在相关时加载的详细参考资料或流程 | `skills/`                                                                                | 模型只在特定任务中需要完整指导。        |

## Skill 格式

Mastra 支持三种基于文件的 Skill 格式：

| 格式                       | 适用场景                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| TypeScript/JavaScript 模块 | 希望通过代码默认导出 [`createSkill()`](https://mastra.zisheng.pro/reference/agents/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 的优先级

发现的 Skill 会与 [`config.ts`](https://mastra.zisheng.pro/reference/file-based-agents/config) 中的所有 `skills` 合并。如果名称冲突，`config.skills` 优先，并会记录警告。

如果 `config.skills` 是函数，Mastra 会忽略发现的 Skill 并发出警告，因为值为函数的 Skill 无法进行静态合并。