Claude Skills
實戰指南
The Complete Guide to Building Skills for Claude
一份專為開發者與團隊打造的階梯式教育手冊，
教您如何將
SOP 與專家知識轉化為自動化工作流。
核心概念：什麼是 Skill？
Skill 是一個裝載了指令與工作流的資料夾，它能讓 Claude 精準掌握您專屬的作業流程，而無需每次對話都重新解釋背景。
一個標準的 Skill 資料夾包含：
- SKILL.md (必填)：核心指令，包含決定何時觸發的 YAML 前置資料。
- scripts/ (選填)：可執行的自動化腳本 (如 Python、Bash)。
- references/ (選填)：讓 Claude 按需讀取的參考文件與手冊。
優勢：透過教導 Claude 一次，未來即可永久受益，並確保團隊產出的高度一致性。
階梯式開發路徑 (The Staircase)
Step 1. 規劃與場景
定義明確的 Use Case，決定觸發條件與目標，評估是否需要搭配外部工具 (MCP)。
Step 2. 結構建立
建立資料夾，配置必須的 SKILL.md，並遵循嚴格的 kebab-case 命名規範。
Step 3. 撰寫指令
設定精準的 YAML 觸發詞，並運用漸進式揭露原則撰寫強大的 Markdown 指令。
Step 4. 測試與發布
從手動單一任務測試開始，確認 API 與功能無誤後，打包為 ZIP 並發布給團隊。
MCP 與 Skills 的強大組合
(What Claude can do)
賦予工具靈魂的關鍵大腦
如果 MCP (Model Context Protocol) 提供了對外連線的「四肢」，例如讀取 Notion 或建立 Linear 任務；那麼 Skills 就是告訴 Claude 該如何正確使用這些工具的「大腦」。
沒有 Skill 的 MCP：用戶面對工具箱不知從何下手，每次都需要重新下達複雜 Prompt。
搭配 Skill 的
MCP：預設工作流自動啟動，將最佳實踐 (Best Practices) 嵌入每一次互動中，降低整合學習門檻。
三大核心應用場景 (Use Cases)
1. 文件與資產生成
用於創建具備高度一致性與品質的輸出物。可嵌入品牌指南、模板結構與發布前的品質檢查清單。(無需外部工具)
2. 工作流自動化
適用於多步驟流程，能確保 Claude 按部就班執行，並包含自動驗證機制。通常需協調多個 MCP 伺服器。
3. MCP 增強防護
專為增強既有 MCP 伺服器所設計。注入領域知識 (如：Sentry 自動分析 Bug)、提供自動上下文，並預防常見的 API 錯誤。
YAML 撰寫準則：決定生死的第一線
嚴格的命名規範 (Naming)
Claude 非常挑剔資料夾與檔案名稱的格式，任何微小的錯誤都會導致 Skill 無法載入。
- 主檔名必須精確為 SKILL.md (區分大小寫，不可寫成 skill.md)。
- 資料夾與
name:欄位必須使用 kebab-case。 - 嚴格禁止包含空格、大寫字母或底線 (例如：
Notion_Setup是錯誤的)。 - 禁止包含
README.md於 Skill 根目錄內。
描述與觸發詞 (Description)
Description 是 Claude 判斷是否主動啟動 Skill 的唯一依據，長度需小於 1024 字元。
- 必須同時包含：「它能做什麼」與「何時該使用它」(具體觸發詞)。
- 例如：「用於分析設計圖稿。當用戶上傳 fig 檔案，或要求『設計規格』時使用。」
- 資安禁令：絕對禁止在 YAML 中使用 XML 標籤
< >，以防 Prompt 注入攻擊。
指令設計的最佳實踐 (Best Practices)
具體且可執行
避免空泛的指示。例如，不要寫「妥善驗證資料」，應該明確指示：「執行
scripts/validate.py，若出現錯誤，請檢查是否遺漏必填欄位。」程式碼比語言更具確定性。
漸進式揭露機制
為避免消耗過多 Token，保持 SKILL.md 精簡，僅放核心步驟。將詳細的 API 規範或龐大的樣板移至 references/
資料夾，讓 Claude 需要時再去讀取。
預設錯誤處理
預見系統可能發生的錯誤並提供解法。例如設立一個「常見問題」區塊：「若遭遇連線拒絕，請用戶至設定 > 擴充功能中重新連線。」這能大幅減少人工介入。
實戰案例一：Code Review 助手
單一任務標準結構
這是一個不需要外部 MCP 工具的標準 SKILL.md 寫法。重點在於明確的前置條件與防呆機制。
- YAML 區塊：精準定義觸發條件。
- Role (角色設定)：賦予 Claude 專家視角。
- Workflow (工作流)：用數字編號強制執行順序。
- Rules (限制)：明確告知「不該做什麼」，防止過度干預。
name: strict-pr-reviewer
description: 當使用者上傳程式碼片段，或要求 Code Review 時觸發。
---
# Role
你是一位嚴格且資深的後端架構師。
# Workflow
被觸發時，請嚴格按順序執行以下步驟：
1. **安全性掃描**：檢查是否有 SQL Injection 或 Hardcoded 密碼。
2. **效能評估**：標出時間複雜度超過 O(N^2) 的寫法。
3. **產出報告**：以 Markdown 表格呈現修改建議。
# Rules
- 絕對**不要**直接給出完整重寫的程式碼。
- 只提供具體的修改指引與思路。
實戰案例二：串接 MCP 的自動化
name: linear-bug-reporter
description: 協助將對話中的錯誤日誌直接轉換為 Linear 任務。
---
# Objective
分析錯誤日誌，並主動使用 `linear` MCP 建立 Bug Ticket。
# Instructions
1. 從使用者的 Error Log 中提取：代碼、時間、可能原因。
2. 自動呼叫 `linear_create_issue` 工具。
3. 將 Title 設定為 `[Bug] {錯誤代碼}` 格式。
# Error Handling (Fallbacks)
- 若找不到 `linear` 工具或連線失敗，**請勿道歉**。
- 直接回退：產出 Markdown Bug 報告，請使用者手動複製。
多步驟與錯誤回退處理
這示範了如何讓 Claude 像一個 RPA 機器人一樣調用外部 API，並具備自我修復的邏輯。
- Objective (目標)：一句話講明這個腳本的最終目的。
- 工具調用指示：明確寫出要呼叫的工具名稱 (如
linear_create_issue)。 - Fallback (回退機制)：極度重要！預設 MCP 可能會斷線，告訴 Claude 在工具失效時該如何改用純文字輸出，避免流程中斷。
測試與驗證階段
「先在單一任務上確保 Claude 能完美執行，再將該成功模式提取並封裝為 Skill。」
全面測試指南：三個關鍵維度
| 測試維度 | 測試目標 | 衡量與檢驗標準 (Metrics) |
|---|---|---|
| 觸發測試 (Triggering) | 確保 Skill 在正確的時機點被載入，並且不會在無關話題中過度觸發。 | 90% 的相關請求能自動觸發 Skill (不需用戶手動叫出)；使用無關指令時保持靜默。 |
| 功能測試 (Functional) | 驗證工作流是否如預期產出正確結果，且妥善處理各種邊緣情況。 | 0 個未處理的 API 錯誤；工具呼叫皆成功完成；確保輸出格式結構一致。 |
| 效能對比 (Performance) | 證明導入 Skill 後，整體流程效率優於原始的「人工引導」基線。 | 對話來回次數大幅減少；所需的 Token 消耗量降低；無需用戶介入糾正。 |
進階設計：五大常見專家模式
- 順序編排 (Sequential Workflow)：嚴格定義步驟 1 到步驟 N。適用於具備先後依賴關係的任務，如「新建客戶 -> 設定付款 -> 寄送歡迎信」。
- 多 MCP 協同 (Multi-MCP)：跨服務編排。如將 Figma 設計匯出 (MCP 1)、存入 Google Drive (MCP 2)、並在 Linear 建立任務 (MCP 3)。
- 迭代優化 (Iterative Refinement)：建立「產出草稿 -> 腳本驗證 -> 自動修正」的封閉迴圈，直到品質達標才結束對話。
- 上下文感知 (Context-aware)：為 Claude 建立決策樹。例如：「若檔案大於 10MB，調用雲端硬碟 MCP；若為程式碼，調用 GitHub MCP。」
- 領域知識注入 (Domain-specific)：在呼叫 API 前嵌入合規檢查或風控邏輯，讓 Claude 表現得像一位資深專家。
最終步：封裝與發布
打包與安裝：完成測試後，將資料夾壓縮為 .zip。個人用戶可透過 Claude.ai 上傳；企業團隊管理員則可將其佈署至整個
Workspace (自動更新)。
開源與 API：您可以將 Skill 託管於 GitHub，提供清晰的 README.md 安裝教學。若是應用程式開發者，也能透過
API 的 container.skills 參數以程式化方式調用。
行銷定位：在推廣時，專注於「成果」而非技術。強調「此 Skill 能在幾秒鐘內為您完成專案配置」，讓 MCP 與 Skill 成為您系統整合的最大賣點。
準備好打造專屬 Skill 了嗎？
「用知識驅動工具，讓自動化成為團隊標準」