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

# Skill

檔案式 Agent 會從 `skills/` 目錄探索 Skill，並在建置時將它們納入 bundle。Skill 是可重複使用的操作流程或參考資料，Agent 能在相關時載入，不必將所有細節都放進持續生效的 prompt。

本頁說明檔案式慣例。以程式碼定義的 Skill 請參閱 [Agent Skill](https://mastra.zisheng.pro/zh-TW/docs/agents/skills)；`SKILL.md` 套件格式請參閱 [Workspace Skill](https://mastra.zisheng.pro/zh-TW/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/zh-TW/reference/file-based-agents/instructions) | 模型每一輪都應看到此指引。            |
| 具有輸入與輸出的可呼叫動作       | [`tools/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/tools)                 | 模型需要執行程式碼、呼叫 API 或產生副作用。 |
| 只在相關時載入的詳細參考資料或操作流程 | `skills/`                                                                                      | 模型只在特定任務中需要完整指引。         |

## Skill 格式

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

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

封裝式 Skill 的 `SKILL.md` frontmatter 必須包含 `description`。單一 markdown Skill 的 frontmatter 也必須包含 `description`。請描述何時使用 Skill，而不只是 Skill 包含什麼內容。

## 載入的內容

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

對於封裝式 Skill，Mastra 會讀取：

- `SKILL.md` 中的 metadata 與 instructions。
- `references/` 正下方作為支援參考內容的檔案。

參考檔案以檔名作為 key。探索期間會略過 `references/` 下的 symlink 檔案與目錄。

## 與 config 的優先順序

探索到的 Skill 會與 [`config.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/config) 中的所有 `skills` 合併。若名稱發生衝突，`config.skills` 會優先，並記錄警告。

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