Claude 官方 Skills 完整指南：從零開始打造你的 AI 技能包

前言

Skill 是 Claude 生態系中非常實用的擴充機制——簡單來說，就是用一個資料夾把「你希望 Claude 怎麼運作」這件事固化下來。不用每次對話都重新解釋你的偏好、流程和專業知識，教一次就夠了。

這份指南是 Anthropic 官方出品的完整教學，從 Skill 的基礎概念到規劃設計、測試迭代、分發部署，再到五大實戰模式和除錯指南，33 頁的內容一次掌握。

第一章：基礎概念

Skill 是什麼？

一個 Skill 就是一個資料夾，裡面包含：

SKILL.md（必需）：用 Markdown 寫的指令檔案，帶 YAML frontmatter
scripts/（可選）：可執行程式碼（Python、Bash 等）
references/（可選）：按需載入的參考文件
assets/（可選）：模板、字型、圖示等輸出資源

核心設計原則

漸進式披露

Skill 用三層體系來管理資訊載入：

第一層（YAML frontmatter）：始終載入到 Claude 的系統提示詞中，只提供足夠資訊讓 Claude 知道何時該用這個 Skill。
第二層（SKILL.md 正文）：當 Claude 判斷 Skill 跟當前任務相關時才載入，包含完整指令和指導。
第三層（關聯檔案）：Skill 目錄內的附加檔案，Claude 只在需要時才去查找和讀取。

可組合性

Claude 可以同時載入多個 Skill，你的 Skill 應該能跟其他 Skill 和平共存。

可攜性

Skill 在 Claude.ai、Claude Code 和 API 上表現一致，寫一次就能在所有平台上執行。

Skills + MCP 的關係

MCP 提供的是連接層——工具、資料存取。Skill 提供的是知識層——工作流程和最佳實踐。兩者結合，使用者不用自己琢磨每一步該怎麼做。

第二章：規劃與設計

從用例出發

寫程式之前，先確定 2-3 個 Skill 要支援的具體用例。好的用例定義應包含：觸發條件、執行步驟、預期結果。

三種常見用例分類

分類 1：文件與資產建立

適用場景：建立一致的、高品質的輸出——文件、簡報、應用程式、設計、程式碼等。核心技巧包括嵌入風格指南、用模板結構保證輸出一致性。

分類 2：工作流程自動化

適用場景：受益於統一方法論的多步驟流程。核心技巧包括帶驗證關卡的步驟工作流程、常見結構的模板、內建審查和改進建議。

分類 3：MCP 增強

適用場景：為 MCP 伺服器提供的工具存取新增工作流程指導。核心技巧包括按順序協調多個 MCP 呼叫、嵌入領域專業知識。

技術要求

檔案結構

your-skill-name/
├── SKILL.md        # 必需 - 主 Skill 檔案
├── scripts/        # 可選 - 可執行程式碼
├── references/     # 可選 - 參考文件
└── assets/         # 可選 - 模板等

關鍵規則

必須精確命名為 SKILL.md（區分大小寫）
資料夾命名使用 kebab-case：notion-project-setup ✅
不能有空格、底線或大寫
Skill 資料夾內不要包含 README.md

YAML Frontmatter

YAML frontmatter 決定了 Claude 是否載入你的 Skill，這部分一定要寫好。

最小必需格式

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

欄位說明

name（必需）：只能用 kebab-case，不能有空格或大寫，應該跟資料夾名一致
description（必需）：必須同時包含 Skill 做什麼、什麼時候用它（觸發條件），不超過 1024 字元，不能有 XML 標籤
license（可選）：開源時使用，常見 MIT、Apache-2.0
compatibility（可選）：說明環境要求

寫好 description 的技巧

好的 description 結構：[做什麼] + [什麼時候用] + [核心能力]

# ✅ 好
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs" or "design-to-code handoff".

# ❌ 壞
description: Helps with projects.

第三章：測試與迭代

測試方法

Claude.ai 手動測試：直接跑查詢觀察行為，迭代快
Claude Code 腳本測試：自動化測試用例，可重複驗證
Skills API 程式測試：構建評估套件，系統性驗證

使用 skill-creator

skill-creator 是 Anthropic 提供的輔助工具，能根據自然語言描述產生 Skill、建議觸發短語、審查並發現常見問題。

基於反饋迭代

觸發不足：在 description 中加入更多細節和關鍵字
觸發過度：新增負面觸發條件，更具體地限定範圍
執行問題：改進指令，增加錯誤處理

第四章：分發與共享

當前分發方式

個人使用者安裝 Skill：透過 Claude.ai 的 Settings > Capabilities > Skills 上傳，或放到 Claude Code 的 skills 目錄
組織級 Skill：管理員可以在工作區範圍內部署 Skill，支援自動更新和集中管理

透過 API 使用 Skills

/v1/skills 端點用於列出和管理 Skill
透過 Messages API 的 container.skills 參數新增 Skill
在 Claude Console 中進行版本控制和管理

第五章：模式與除錯

五大設計模式

模式 1：順序工作流程編排

適用場景：使用者需要按特定順序執行的多步驟流程。核心技巧：明確的步驟順序、步驟間依賴、每步驗證、失敗時的回復指令。

模式 2：多 MCP 協調

適用場景：工作流程跨越多個服務。核心技巧：清晰的階段劃分、MCP 之間的資料傳遞、進入下一階段前驗證。

模式 3：迭代優化

適用場景：輸出品質透過迭代改進。核心技巧：明確的品質標準、迭代改進、驗證腳本。

模式 4：情境感知的工具選擇

適用場景：同一目標，不同情境用不同工具。核心技巧：清晰的決策標準、備選方案、對選擇過程保持透明。

模式 5：領域專業知識嵌入

適用場景：Skill 需要新增超越工具存取的專業知識。核心技巧：領域專業知識嵌入邏輯、行動前先合規、全面的文件記錄。

除錯指南

Skill 上傳失敗

「Could not find SKILL.md」：檔案沒有精確命名為 SKILL.md
「Invalid frontmatter」：YAML 格式問題，檢查分隔符和引號
「Invalid skill name」：名稱有空格或大寫，改用 kebab-case

Skill 不觸發

檢查 description 是否太籠統、有沒有包含使用者實際會說的觸發短語、涉及特定檔案類型的有沒有提到。

Skill 觸發太頻繁

新增負面觸發條件、更具體地限定範圍。

MCP 連線問題

確認 MCP 伺服器已連線、檢查認證、獨立測試 MCP、驗證工具名稱。

指令沒被遵循

常見原因：指令太冗長、關鍵指令被埋沒、表述模糊。解決方案：保持簡潔、把關鍵指令放在頂部、用明確的語言。

第六章：資源與參考

官方文件

Best Practices Guide
Skills Documentation
API Reference
MCP Documentation

範例 Skills

GitHub: anthropics/skills，包含 Anthropic 建立的 Skill，可以直接客製使用。

工具

skill-creator：Claude.ai 和 Claude Code 中內建，可以根據描述產生 Skill、審查並提供改進建議。使用方式：「Help me build a skill using skill-creator」。

常見問題

Q: Skill 跟 Prompt 模板有什麼區別？
A: Prompt 模板是一次性的——每次用都要手動貼上或呼叫。Skill 是持久化的知識包，Claude 能自動識別什麼時候該用、怎麼用。而且 Skill 支援多檔案結構，不只是一段文字。

Q: 一個 Skill 的 SKILL.md 應該多長？
A: 核心指令控制在 5,000 詞以內。詳細的參考文件放到 references/ 目錄裡。

Q: 可以同時啟用多少個 Skill？
A: 技術上沒有硬限制，但同時啟用 20-50 個以上可能導致回應變慢或品質下降。建議按功能分組，按需啟用。

Q: 怎麼快速入門？
A: 最快的方式：在 Claude.ai 中使用 skill-creator。告訴 Claude「Help me build a skill using skill-creator for [你的用例]」，它會引導你完成整個流程。

原文連結：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en