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

# Skills

檔案式 Agent 會從其 `skills/` 目錄探索 skills，並在建置時打包。Skills 是可重用的程序或參考資料，Agent 可在相關時載入，無需將所有細節放入始終生效的 prompt。

本頁說明檔案式慣例。如需了解以程式碼定義的 skills，請參閱 [Agent skills](https://mastra.zisheng.pro/zh-HK/docs/agents/skills)。如需了解 `SKILL.md` 封裝格式，請參閱 [Workspace skills](https://mastra.zisheng.pro/zh-HK/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.
```

## Skills、tools 與 instructions 的比較

| 需要               | 使用                                                                                             | 原因                       |
| ---------------- | ---------------------------------------------------------------------------------------------- | ------------------------ |
| 始終生效的身分、語氣或規則    | [`instructions.md`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/instructions) | 模型應在每一輪看到這些指引。           |
| 包含輸入及輸出的可調用操作    | [`tools/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/tools)                 | 模型需要執行程式碼、調用 API 或產生副作用。 |
| 在相關時載入的詳細參考資料或程序 | `skills/`                                                                                      | 模型只需在特定任務中取得完整指引。        |

## Skill 格式

Mastra 支援三種檔案式 skill 格式：

| 格式                       | 適用情況                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| TypeScript/JavaScript 模組 | 你希望透過程式碼 default-export [`createSkill()`](https://mastra.zisheng.pro/zh-HK/reference/agents/createSkill) 的結果。 |
| 封裝的 `SKILL.md` 目錄        | Skill 包含 instructions，以及 `references/` 下的支援檔案。                                                                |
| 一般 markdown 檔案           | Skill 是一個包含 frontmatter 及 instructions 的 markdown 檔案。                                                         |

對於封裝的 skills，`SKILL.md` frontmatter 必須包含 `description`。一般 markdown skills 的 frontmatter 亦必須包含 `description`。請說明何時應使用 skill，而非只描述 skill 包含的內容。

## 載入的內容

檔案式 Agent skills 會在建置時加入產生的 bundle，因此已部署的 Agent 不會從磁碟讀取這些檔案。

對於封裝的 skills，Mastra 會讀取：

- `SKILL.md` 的 metadata 及 instructions。
- `references/` 直接包含的檔案，作為支援參考內容。

參考檔案以檔案名稱作為鍵。探索期間會略過 `references/` 下的符號連結檔案及目錄。

## 與 config 的優先次序

探索到的 skills 會與 [`config.ts`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/config) 中的任何 `skills` 合併。如果名稱發生衝突，系統會以 `config.skills` 為準並記錄警告。

如果 `config.skills` 是函數，系統會忽略探索到的 skills 並記錄警告，因為函數值的 skills 無法以靜態方式合併。