官方 Claude Skill 完整建構指南與實作重點

參考資料：
（1）官方 Claude Skill 完整建構上手指南（Facebook 貼文整理）
（2）前文 Build Skills，不要只打造複雜的 Agent 架構 已整理演講核心與 Cursor 實作，本篇專注官方指南的實作細節。

官方 33 頁的 Skills 建構指南，重點不是教你「怎麼寫一個很炫的 Agent」，而是教你怎麼把一個真實工作流程，實際落成一個可重複使用、可分享的 Skill。以下整理核心觀念與實作做法。

一、心態：把 Claude 當成「超聰明但需要 onboarding 的同事」

想像有個特別聰明的同事，與其每次都重新解釋「我們公司怎麼寫報告、怎麼交接設計、怎麼跑上線流程」，不如花一次時間說清楚，讓他記住。之後只要說一句「用我們之前說好的方式幫我做這個」，對方就知道該怎麼做。

Claude Skill 就是這份「一次講清楚的 onboarding 套件」：一個資料夾，裡面裝著清楚的指示、流程與偏好，教會 Claude 怎麼處理特定任務。一旦配置好，你就不必每次都重新講一遍。

具體來說，Skill 就是把工作流程、偏好風格、公司規範或專業知識打包起來。例如：自動生成符合公司風格指南的報告、從設計稿生成開發文件、執行複雜的資料分析，或管理多步驟的專案協作流程。

二、三個設計哲學：Progressive Disclosure、Composability、Portability

Progressive Disclosure（漸進式揭露）
Skill 不是一次把所有東西塞給 Claude，而是分三層：

• 第一層：YAML frontmatter — 提供「我是誰、什麼時候用我」這種精簡 metadata，永遠會被讀到。
• 第二層：SKILL.md 正文 — 只有當 Claude 判斷這個 Skill 有用時才讀，內含完整流程、規則、範例。
• 第三層：references/ 裡的延伸文件 — 只有在需要更細的 API 說明、範本時才載入。

Composability（可組合性）
一個 Skill 不應該試圖「包山包海」，而是謙虛地負責單一任務，讓多個 Skills 可以像樂團成員一樣協作。例如「行銷文案 Skill」+「拼字校正 Skill」+「SEO 優化 Skill」可以串起來，而不是做一個超大 Skill 把全部塞進去。

Portability（可攜性）
寫好的 Skill 可以在 Claude.ai、Claude Code、API 上共用，同一份程式與說明到處跑。這是為了未來「開放標準」做準備——理想上，一個 Skill 可以在多個 AI 平台上通用。

三、官方推薦的 Skill 資料夾結構（附實作細節）

官方標準長這樣：

your-skill-name/
├── SKILL.md          # 必要，Skill 入口與規範說明
├── scripts/          # 可選：自動化腳本（Python、Shell、JS…）
├── references/       # 可選：API 文件、範例、錯誤碼說明
└── assets/           # 可選：靜態資源（模板、圖示、字型…）

• 資料夾命名：只能用 kebab-case（小寫 + -），例如 report-generator、figma-handoff，不能有空格、大寫或底線。
• SKILL.md 是唯一的入口，不用再放 README.md。給人類看的 README 放在 GitHub 專案外層即可；給 Claude 看的內容統一寫在 SKILL.md 與 references/。

一個對應前面理念的 SKILL.md 範例（簡化版）：

---
name: report-generator
description: >
  根據結構化資料產生商業報告與簡報大綱。
  使用者提到「季報」「年報」「商業報告」時使用，
  或上傳含有營收、成本、成長率的表格檔案時觸發。
version: 1.0.0
authors:
  - name: your-name
    email: you@example.com
---

## 使用情境

- 使用者說「幫我生成 Q4 季報」或「依照這份數據寫年報」。
- 來源資料通常是 CSV / Excel / 資料庫查詢結果匯出。

## 核心工作流程

1. 解析輸入資料，檢查是否包含必要欄位（營收、成本、時間區間）。
2. 若資料不完整，先請使用者補充或重新匯出。
3. 依照 `references/report-structure.md` 的章節順序生成初稿。
4. 呼叫 `scripts/validate_report.py` 檢查段落完整性與數據一致性。
5. 若檢查失敗，根據錯誤訊息修正並重新生成。
6. 給出最終版本與摘要。

這裡可以看到三層結構：Frontmatter 提供精簡 metadata；正文寫「具體要怎麼做」與「遇到錯誤怎麼處理」；較長的章節模板或 API 細節放進 references/，由 SKILL.md 連過去。

四、Scripts 與 References：把「重複的手工活」變成工具

scripts/ 通常放的是：

• 驗證腳本，例如 validate_report.py、check_figma_tokens.js。
• 批次處理腳本，例如 sync_to_notions.sh、export_figma_assets.ts。
• 測試與 demo 腳本，例如 test_scenarios.py。

references/ 常見內容：

• API 指南與速率限制說明。
• 錯誤碼與排錯指引。
• 範例輸入/輸出模板（例如標準化的報告章節架構）。

這樣做的好處是：Claude 不需要每次「憑空想像」腳本或規則，而是直接讀你已經寫好的東西；你也可以像維護一般程式碼一樣維護 Skills。

五、三大 Skill 類型與撰寫技巧（實作角度）

官方指南把 Skills 大致分成三類：

1. 文件與素材建立型

   • 目標：生成高品質且一致的輸出（網頁、簡報、技術文件…）。
   • 重點：在 references/ 中放好模板與風格指南，SKILL.md 明寫「必備章節、語氣、審核清單」。

2. 工作流程自動化型

   • 目標：把多步驟流程（如客戶上線、Sprint 規劃）寫成 SOP。
   • 重點：在 SKILL.md 明確拆解步驟與依賴順序，必要時搭配 scripts/ 跑驗證或回滾。

3. MCP 加強型（工具協調器）

   • 目標：讓 Claude 聰明地串起多個 MCP 工具，例如 Sentry + GitHub、Linear + Slack。
   • 重點：定義好每個工具「在這個流程中的角色」；在 SKILL.md 詳列錯誤處理與重試策略；減少使用者每次都要口頭交代「先查 A 再發 B 再更新 C」的負擔。

撰寫時，最關鍵的欄位是 frontmatter 的 description：要清楚寫出這個 Skill「具體做什麼」、「什麼時候」該用它、使用者實際可能說出的關鍵字（觸發語）。模糊的說法（如「處理專案相關工作」）會導致 Skill 不觸發或亂觸發；官方建議在 description 中同時寫出「要用的情境」與「不要用的情境」。

六、設計、測試與迭代：官方建議的開發流程

官方文件很強調：不要從程式碼開始，而是從 Use Case 開始。

定義 Use Case

• 目標：使用者想達成什麼？（例如「規劃 Sprint」「從設計稿生出交接文件」）
• 步驟：這個目標需要哪些具體步驟？是否有前後依賴？
• 工具：僅用 Claude 內建能力即可，還是需要 MCP / 外部 API？

定義成功指標

• 觸發率：在應該觸發的情境下，Skill 實際被載入的比例。
• 錯誤率：MCP 呼叫成功率、流程中斷次數。
• 穩定性：多次重跑同一請求，輸出是否穩定。

三層測試方式

• Claude.ai 手動測試：快速確認觸發與行為是否合理。
• 在 Claude Code 中寫腳本批次測試多個情境（10–20 個 case）。
• 透過 API 做「準正式環境」測試，確保部署後行為一致。

常見問題與對策

• Skill 沒被觸發（undertriggering）：description 太模糊，需補上真實觸發語，並加上「不要在 X、Y 情境下使用」的反面描述。
• Skill 觸發太頻繁（overtriggering）：功能定義太寬，或 description 沒有限定場景；需要收斂用途或拆成多個 Skills。
• API 呼叫失敗：先驗證 MCP 本身是否可用，再檢查 Skill 內工具名稱、參數是否正確；必要時在 SKILL.md 裡加上重試與錯誤回報規則。
• 效能問題（tokens 太多）：把長說明移到 references/，確保 SKILL.md 保持精簡，並避免一次載入過多 Skills。

七、發布與分享：從個人到組織，再到開放生態

實作面上，官方目前建議：

• 自己用：直接把 Skill 資料夾放到 Claude.ai 的 Settings / Capabilities / Skills，或 Claude Code 的 skills/ 目錄。
• 團隊用：由管理員在團隊 workspace 統一部署，成為「組織內標準 Skill 套件」，例如「公司寫作風格 Skill」「程式碼審查 Skill」。
• 開源給社群：把 Skill 放上 GitHub（Skill 內部不放 README，而是在 repo 根目錄寫 README 給人看）；補上用法截圖、範例、與對應 MCP 的說明；說清楚「這個 Skill 解決什麼實際問題」，而不是只列技術細節。

官方也明講：Anthropic 想把 Agent Skills 做成開放標準，讓未來其他平台也能讀同一套 Skills。長遠來看，你現在寫的每個 Skill，都可能成為「跨平台可重用的專業模組」。

總結

官方指南的核心是：從 Use Case 出發 → 用三層結構與單一職責設計 Skill → 善用 scripts/ 與 references/ → 用 description 與測試迭代控制觸發與穩定性 → 再依需求從個人、團隊到開源分享。搭配前文 Build Skills，不要只打造複雜的 Agent 架構 的演講概念與 Cursor 實作，即可把領域知識真正落成可複利、可分享的 Skills。