Skills

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

本頁說明檔案式慣例。如需了解以程式碼定義的 skills，請參閱 Agent skills。如需了解 SKILL.md 封裝格式，請參閱 Workspace skills。

快速開始

最簡單的 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.

Skills、tools 與 instructions 的比較

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

Skill 格式

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

格式	適用情況
TypeScript/JavaScript 模組	你希望透過程式碼 default-export 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 中的任何 skills 合併。如果名稱發生衝突，系統會以 config.skills 為準並記錄警告。

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