Skill

檔案式 Agent 會從 skills/ 目錄探索 Skill，並在建置時將它們納入 bundle。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 的差異

需求	使用項目	原因
持續生效的身分、語氣或規則	instructions.md	模型每一輪都應看到此指引。
具有輸入與輸出的可呼叫動作	tools/	模型需要執行程式碼、呼叫 API 或產生副作用。
只在相關時載入的詳細參考資料或操作流程	skills/	模型只在特定任務中需要完整指引。

Skill 格式

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

格式	適用情況
TypeScript/JavaScript 模組	你想透過程式碼 default export 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 中的所有 skills 合併。若名稱發生衝突，config.skills 會優先，並記錄警告。

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