🔧 阿川の電商水電行
引言
2026年1月，Anthropic發佈了一份名為「The Complete Guide to Building Skills for Claude」的32頁PDF文件。
技能是使Claude能一致性執行特定任務的機制。只需將Markdown文件放入資料夾，即可改變Claude的行為。這是一種所謂的「可重複使用的提示」，不需要每次複製粘貼提示或說明。
儘管本指南內容充實，但用英語完整閱讀32頁的PDF相當費力。本文將總結該指南的核心內容，並解釋在實務中實際有效的部分。
目標讀者
- 在業務中使用Claude Code / Claude.ai的人
- 每次重複相同說明感到麻煩的人
- 雖然知道MCP，但尚未接觸技能的人
文章中可獲得的內容
- 理解技能的設計思想和結構
- 掌握5個實踐模式
- 事先了解常見的卡關點及其應對方法
技能的真相：一個資料夾能改變什麼
技能的實體驚人地簡單。
your-skill-name/
├── SKILL.md # 必需。指令的本體
├── scripts/ # 可選。可執行程式碼
├── references/ # 可選。補充文件
└── assets/ # 可選。模板等必需的檔案僅為 SKILL.md，而且內容為Markdown格式。無需編程，任何人都可以撰寫。
那麼，僅這些為何如此強大呢？讓我們來看看指南所示的設計思想。
指南所教的三個設計原則
1. 漸進式揭露
技能的加載分為三個階段控制。
| 等級 | 加載對象 | 時機 |
|---|---|---|
| 第1 | YAML前頭資訊 | 總是被加載 |
| 第2 | SKILL.md內容 | 技能觸發時 |
| 第3 | references/ 內的檔案 |
Claude判斷需要時 |
這一點至關重要。前頭資訊總是存在於上下文窗口中。換句話說，在技能啟用時，這部分的令牌始終消耗。而內容僅在「需要時」被加載。
正因如此，即使啟用20個技能仍具實用性。所有技能的前頭資訊始終駐留，而實際指令僅在啟動時顯示出來。這是一種節省上下文與專業性的設計。
反過來說，前頭資訊過大的技能會壓迫其他技能或對話。前頭資訊應聚焦於「何時使用」的判定資訊，具體的指令則應寫在內容中。
2. 可組合性
Claude可以同時加載多個技能。指南明確指出「你的技能不應假設是唯一功能」。
在實務中，自然會出現以下組合。
qiita-writing+frontend-design→ 在Qiita文章中嵌入互動式示範sentry-code-review+linear-tasks→ 自動檢測錯誤並創建任務
技能不應該獨立完成，而應以組合方式使用為設計前提。
3. 可攜性
技能在Claude.ai、Claude Code以及API中都能正常運行。一旦創建，就可在任何環境中直接使用。
description佔9成：技能觸發的機制
指南中最用心的部分是YAML前頭資訊的 description 欄位的寫法。
---
name: your-skill-name
description: 何為使用。用於用戶請求[特定片語]時。
---description 是技能的「觸發條件」。Claude根據用戶的請求，對照有效的技能的 description，然後自動加載相關性高的技能。
也就是說，這裡的寫法決定一切。
好的description與壞的description的差異
# 壞的例子：過於模糊，可能適用於任何情況
description: 支援項目。
# 好的例子：包含具體的觸發短語
description: 管理包含
Sprint計畫、任務創建、狀態追蹤的
Linear專案工作流程。使用於用戶提到「Sprint」
「Linear任務」「專案計畫」或請求「創建票據」的時候。指南所示的結構簡單。
[何為使用] + [何時使用] + [主要功能]
這三個要素若完整，技能會在適當時間觸發。反之，若「何時使用」缺失，則可能無法觸發，或在不相關的場合觸發。
如果技能未被觸發，改善內容無論如何都沒有意義。問題幾乎確定出在 description 上。調試的第一步是詢問Claude「[技能名稱]技能何時使用？」。Claude會引用 description 回答，這樣即可立即明白不足的條件。
MCP與技能的關係：廚房與食譜
指南中最容易理解的類比是「廚房與食譜」。
- MCP = 專業廚房（工具、材料、設備的訪問）
- 技能 = 食譜（創建有價值事物的逐步指示）
僅僅連接MCP，對用戶來說會變得「那麼，能做什麼？」有了技能，當需要已構建的工作流程時，它能自動啟動。
| 只有MCP | MCP + 技能 | |
|---|---|---|
| 初次體驗 | 「不知道該做什麼」 | 工作流程自動引導 |
| 結果穩定性 | 取決於用戶的提示 | 一致的品質 |
| 支援負荷 | 使用方法的問題頻繁 | 學習曲線較低 |
對於提供MCP的服務而言，技能的提供不再是「撰寫使用說明文件」，而是「將使用說明直接嵌入Claude」。
三個技能類別
指南將用例分為三個類別。
類別1：文件與資產創建
不需要外部工具，僅用Claude內建功能即可完成的技能。
範例：前端設計、文件生成、簡報製作
內嵌樣式指南與模板，保證一致的輸出品質。這是最簡單的入門類別。
類別2：工作流程自動化
以一致的方法論執行多步驟過程的技能。
範例：skill-creator（創建技能的技能）、Sprint計畫
包含驗證閘道和改進循環，標準化步驟。
類別3：MCP增強
在MCP伺服器提供的工具訪問上添加工作流程知識的技能。
範例：使用Sentry的錯誤數據自動修正PR中的錯誤技能
將多個MCP調用按照正確的順序聯繫起來，並嵌入領域專業知識。
首次創建技能時，建議從類別1開始。這不依賴外部因素，僅需一個SKILL.md檔案，以便進行設計、測試和改進的循環。
五種實踐模式
指南的第五章介紹了實際有效的五種模式。以下是每種「使用時機」的整理。
模式1：順序工作流程
使用時機： 步驟有順序，前一步的結果將在後一步使用的情況
範例：客戶入門（帳戶創建 → 支付設置 → 訂閱 → 歡迎郵件）
重點在於每個步驟中加入驗證，並明確寫出失敗時的回滾指示。「如果Step 2失敗了，Step 1的結果怎麼辦」這樣寫會使實運用變得不易出錯。
模式2：多MCP協調
使用時機： 一個工作流程跨越多服務的情況
範例：設計交接（Figma → Drive → Linear → Slack）
明確分隔階段，設計在階段間傳遞數據。「Phase 1的輸出成為Phase 2的輸入」的依賴關係需明示。
模式3：迭代改進
使用時機： 一口氣產出完美結果困難，想透過迭代提升品質的情況
範例：報告生成（草案 → 品質檢查 → 改進 → 再檢查 → 最終化）
在 scripts/ 中準備驗證腳本來進行品質檢查是有效的。語言指令有解釋的誤差，但程式碼是確定的。
模式4：根據情境選擇工具
使用時機： 雖然目標相同，根據情況最佳方式會有所不同的情況
範例：文件保存（大型文件 → 雲存儲、代碼 → GitHub、臨時文件 → 本地）
明示判斷樹，設計能將即使選擇原因解釋給用戶。
模式5：領域特定的智慧
使用時機： 專業知識比工具訪問更具價值的情況
範例：合規性支付處理（制裁名單檢查 → 管轄區驗證 → 風險評估 → 處理 → 審計追蹤）
通過將領域規則嵌入技能，實現「不僅調用工具，還要在調用工具之前進行正確的順序判斷」。
常見的卡關點及應對方法
從指南的故障排除中摘錄出特別容易遇到的問題。
技能未被觸發
這是最常見的問題。其原因幾乎在於 description。
檢查清單：
description是否過於一般（「支援項目」不會觸發）- 是否包含用戶實際會說的短語
- 是否提及相關的文件類型
調試方法： 問Claude「[技能名稱]技能何時使用？」
技能頻繁被觸發
在不合適的場景中，技能意外被啟動的問題。
應對方法： 在 description 中添加否定觸發器（「不使用於～」）。
description: 進行CSV檔案的高級數據分析。用於統計建模、回歸、聚類。
不適用於簡單數據探索（使用data-viz技能）。指令不被遵循
技能已被加載，但Claude未按指示運作時。
常見原因：
- 指令過於冗長 → 以要點式簡潔化
- 重要指示被埋沒 → 將其放置於開頭
- 模糊表達 → 應列舉具體條件，而非「適當進行驗證」。
指南中提到的進階技巧是，重要的驗證編寫成腳本的做法。將Python或Bash放置於 scripts/ 中，通過程式檢查。這是因為「語言解釋是不確定的，但程式碼是確定的」這一理念。
上下文過大使速度變慢
應對方法：
- 將SKILL.md的內容限制在5000字以內
- 將詳細文件分離到
references/中 - 檢查是否同時啟用20～50以上的技能
測試的思考方式
指南將測試分為三個階段。
| 測試類型 | 目的 | 方法 |
|---|---|---|
| 觸發測試 | 是否在適當時機觸發 | 執行10～20個測試查詢，確認觸發率 |
| 功能測試 | 是否生成正確輸出 | 重複執行相同任務3～5次，確認一致性 |
| 性能比較 | 有技能時是否改進 | 與無技能情況比較（交互次數、錯誤率、令牌消耗） |
特別實用的是「性能比較」的觀點。指南中的例子指出，沒有技能時需15次交互、3次API錯誤、耗費12,000令牌的任務，有技能後改為2次確認、0次錯誤、耗費6,000令牌。
指南建議「首先針對1個困難任務進行迭代，將成功的方案提煉為技能」。而不是一開始就設計完美的技能，而是先在實際對話中尋找成功模式，再將其技能化，這樣的速度會更快。
配布與開放標準
技能已作為「代理技能」進行開放標準化設計。與MCP相似，具有不受特定平台限制的特點。
現時的配布方式主要有兩種。
- Claude.ai → 從設定 > 功能 > 技能上傳ZIP檔案
- Claude Code → 將資料夾放置於
~/.claude/skills/中
對於組織，還提供管理員在整個工作區域中部署技能的功能。
從API使用技能也是可行的，使用 /v1/skills 端點和Messages API的 container.skills 參數進行程式控制。
總結：技能不僅僅是「可重複使用的提示」
通過本指南可以看出，技能不僅僅是「訊息的存儲」。
- 漸進式揭露有效利用上下文
- description控制觸發時機
- references/在需要時展開知識
- scripts/進行確定性的驗證
正因有這種設計，技能不光是「省去每次解釋的麻煩」，也是「結構性地提升Claude的判斷與輸出品質」的機制。
首先找出自己業務中「每次都要向Claude解釋的部分」，嘗試將其做成技能。最初的技能在15～30分鐘內即可運行。
參考連結
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
