Agent Skills 進階篇
五大 Workflow 設計模式 × 完整 Troubleshooting 指南
📚 這是進階篇。還沒看過概念基礎？先看「Agent Skills 開發概念指南」→
先選思路：Problem-first vs Tool-first
設計 Skill 前，先確定你的出發點——這決定了你要套用哪種 Pattern。
🎯 Problem-first
用戶描述的是「我要達到什麼結果」，Skill 負責決定呼叫哪些工具、按什麼順序。
用戶說：
「幫我設置一個新的專案工作空間」
Skill 內部自動協調 MCP 工具的呼叫順序。
🔧 Tool-first
用戶已經有工具（如 Notion MCP），Skill 提供的是「如何使用這個工具的最佳實踐」。
用戶說：
「我連接了 Notion MCP，幫我管理專案」
Skill 提供針對 Notion 的工作流專業知識。
* 大多數 Skill 偏向其中一個方向。確定你的方向後，再選擇下面最符合的 Pattern。
五大 Workflow Design Patterns
這五個 Pattern 來自 Claude 官方整理的早期採用者與內部團隊案例，不是死板模板，而是常見的高效設計思路。選一個最符合你 Use Case 的作為起點。
Use when：用戶需要按固定順序完成多步驟流程
範例結構
# Workflow: Onboard New Customer # Step 1: Create Account Call MCP tool: create_customer Parameters: name, email, company # Step 2: Setup Payment Call MCP tool: setup_payment_method Wait for: payment method verification # Step 3: Create Subscription Call MCP tool: create_subscription Parameters: plan_id, customer_id (from Step 1) # Step 4: Send Welcome Email Call MCP tool: send_email Template: welcome_email_template
關鍵技巧
- 明確標示步驟之間的依賴關係（如 Step 3 需要 Step 1 的 customer_id）
- 每個步驟都要有驗證（Validation）
- 提供失敗時的 Rollback 說明
Troubleshooting 指南
Skill 不如預期？以下是六種最常見的問題與對應的診斷步驟。
Error: "Could not find SKILL.md"
檔名大小寫必須完全一致，rename 成 SKILL.md（注意大寫）
Error: "Invalid frontmatter"
檢查 YAML 格式：前後必須有 --- 分隔符，引號要閉合。技能名稱欄位（name:）不能有空格或說明用引號的錯誤。
Error: "Invalid skill name"
名稱只能用小寫字母和連字符。❌ My Cool Skill → ✅ my-cool-skill
描述太通用
"Helps with projects" 不夠具體，Claude 不知道何時使用。加入用戶實際會說的觸發語境。
觀察 Claude 如何理解你的 Skill
問 Claude：「你什麼時候會使用 [skill name] skill？」Claude 會引用你的描述。根據回答調整。
加入具體的觸發 Use case
描述中加入 "Use when..."，包含具體的檔案類型或任務情境。
加入 Negative triggers
在描述中明確寫出 "Do NOT use for..." 排除不相關的觸發場景。
縮小 Scope
把 "Processes documents" 改為 "Processes PDF legal documents for contract review"。越具體越好。
驗證 MCP Server 是否已連接
Claude.ai → Settings → Extensions → 確認目標服務顯示 "Connected" 狀態
先獨立測試 MCP
不透過 Skill，直接叫 Claude 呼叫 MCP（"Use [Service] MCP to fetch my projects"）。如果這也失敗，問題在 MCP 不在 Skill。
確認工具名稱
Skill 中引用的 MCP tool names 要完全和 MCP server documentation 一致，區分大小寫。
指令太冗長
SKILL.md 限制在 5,000 字以內。重要指令放在最前面，用 ## Important / ## Critical 標題強調。
語言描述太模糊
❌ "Make sure to validate things properly" → ✅ "CRITICAL: Before calling create_project, verify: Project name is non-empty, at least one team member assigned, start date is not in the past"
用腳本取代語言驗證
對關鍵驗證步驟，用程式腳本（Python/Bash）執行，而不是靠語言指令。代碼是確定性的，語言解讀不是。
防止「偷懶」跳步驟
在 SKILL.md 中加入：# Performance Notes / - Take your time to do this thoroughly / - Do not skip validation steps（放在用戶 Prompt 中比 SKILL.md 更有效）
SKILL.md 太大
將詳細文件移到 references/ 資料夾，SKILL.md 只保留連結。嚴格限制 SKILL.md 在 5,000 字以內。
同時啟用 Skill 太多
不建議同時啟用超過 20-50 個 Skills。考慮按用途分組成「Skill Packs」，按需啟用。
還沒掌握 Progressive Disclosure、命名規則、腳本穩健性等基礎概念？
← 回到基礎篇