Claude Code 技能：SKILL.md 撰寫指南與使用時機

Claude Code 技能是一個包含 SKILL.md 檔案的資料夾，其中定義了名稱、描述和指令。Claude 在每次互動時都會檢視所有技能的描述，並僅在任務符合或使用者輸入 /skill-name 時，才會載入完整的指令。這使得技能成為儲存偶爾需要而非總是需要的知識的理想場所。

以下所有資訊均已根據 2026 年 10 月 5 日的 Claude Code 技能文件（Claude Code 2.1.289）進行核對，其他工具也已在同日根據其各自文件進行檢查。今年，技能的變化比 Claude Code 的任何其他部分都多：自訂斜線指令已整合其中，其他代理也開始讀取相同的資料夾，且有幾個欄位比大多數教學文章都新。

Claude Code 中的技能是什麼？技能將指令、可選的支援檔案和工具權限打包成 Claude 可以按需取用的內容。它回答了每個 CLAUDE.md 最終都會提出的問題：對於某種任務很重要，但對其他任務卻是雜訊的知識應該放在哪裡？CLAUDE.md 在每個會話開始時都會被讀取。

一個技能在被需要之前，只會佔用一行描述的成本。自訂斜線指令現在也屬於技能。例如，在 .claude/commands/deploy.md 的檔案和在 .claude/skills/deploy/SKILL.md 的技能都會建立 /deploy 指令，且行為相同。舊的指令檔案仍然有效，但新的工作應該使用技能，因為只有技能才能攜帶支援檔案。

如何建立技能？在儲存庫的 .claude/skills/ 資料夾下（或個人使用的 ~/.claude/skills/）建立一個資料夾，並在其中放入一個 SKILL.md 檔案。前置元資料（frontmatter）必須從第一行開始。

例如，.claude/skills/webhook-change/SKILL.md 的內容可能如下：---

name: webhook-change

description: "在新增或變更支付 webhook 處理器、其重試機制或其冪等性金鑰時使用。"

paths: src/payments/**

---

1. 處理器應具備冪等性，以供應商的事件 ID 為金鑰。2. 重試機制透過 src/lib/retry.ts 執行，五次嘗試後進入死信佇列。原因：docs/decisions/0012-webhook-retries.md 3. 在開啟 PR 之前，在 tests/webhooks/ 中新增一個重播測試。請參閱 checklist.md 以獲取完整的審查清單。

該資料夾可以包含更多檔案。SKILL.md 會連結到這些檔案，而 Claude 僅在任務需要時才會讀取它們；資料夾中的腳本會被執行，而不是被讀取。Anthropic 的建議是將 SKILL.md 保持在 500 行以下，並將詳細內容移至這些支援檔案中。

SKILL.md 中重要的前置元資料欄位。每個欄位都是可選的，以下是會改變行為的欄位：

description：說明技能的功能和使用時機。Claude 會根據您的請求與其進行匹配，以決定是否載入該技能。與 when_to_use 結合後，在清單中的字元數上限為 1,536。

when_to_use：額外的觸發情境和範例請求，會附加到描述中。

paths：限制技能自動載入的 glob 模式，格式與路徑範圍規則相同。

disable-model-invocation：設為 true 表示只有您可以使用 /name 執行它。適用於任何具有副作用的操作，例如部署。

user-invocable：設為 false 會將其從 / 選單中隱藏。只有 Claude 可以載入它。

allowed-tools：在呼叫技能的回合中預先批准的工具。此授權會在您的下一條訊息中清除。

context: fork：在具有自己上下文的子代理中執行技能，預設在背景執行。可與 agent 搭配使用以選擇子代理類型。

model：在技能執行期間覆寫會話模型。

Claude 如何決定使用技能？透過三步驟的漸進式揭露。每個技能的名稱和描述在每次互動時都會存在於上下文中，因此 Claude 知道有哪些技能可用。當您的請求與描述匹配，或您輸入指令時，渲染後的 SKILL.md 會作為一條訊息進入對話，並在會話的其餘時間內保持存在。

支援檔案僅在指令引導 Claude 讀取它們時才會載入。這帶來兩個結果：描述是完整的觸發器，因此應將其寫成它所服務的任務（例如「在新增或變更支付 webhook 處理器時使用」），而不是作為標題（例如「Webhooks」）。此外，技能並非沒有成本：五十個描述在每個提示詞中都會佔用五十行，無論它們是否被觸發。

技能儲存在哪裡，以及哪個優先？

| 位置 | 路徑 | 適用對象 |

|---|---|---|

| 企業管理設定目錄 | （由企業部署） | 組織部署機器上的所有人。最高優先級。 |

| 個人 | ~/.claude/skills/<name>/ | 您，在此機器上的每個專案。 |

| 專案 | .claude/skills/<name>/ | 所有複製此儲存庫的人。 |

| 巢狀 | <subdir>/.claude/skills/ | 在單一儲存庫（monorepo）該部分工作的會話。 |

| 外掛程式 | <plugin>/skills/<name>/ | 任何啟用該外掛程式的人，以 /plugin-name:skill-name 形式使用。 |

當兩個技能共享名稱時，企業設定優先於個人設定，個人設定優先於專案設定。外掛程式技能具有命名空間，永不被覆蓋。若要與團隊共享技能，請將其提交到 .claude/skills/；若要在不同儲存庫之間共享，請將其作為外掛程式發布。關於哪些 .claude/ 檔案應該提交，請參閱「是否應該提交 CLAUDE.md」。

Cursor、Copilot 和 Codex 會讀取 Claude Code 技能嗎？VS Code 中的 Cursor 和 Copilot 會，但 Codex 不會。技能遵循 Agent Skills 開放標準，因此 SKILL.md 格式是共享的，但每個工具都會在自己的資料夾中尋找。

| 工具 | 讀取的專案技能資料夾 |

|---|---|

| Claude Code | .claude/skills/，以及外掛程式。不讀取 .agents/skills/。 |

| Cursor | .agents/skills/ 和 .cursor/skills/，以及「為了相容性」讀取 .claude/skills/ 和 .codex/skills/。 |

| VS Code 中的 Copilot | .github/skills/、.claude/skills/、.agents/skills/。 |

| OpenAI Codex | 從工作目錄到儲存庫根目錄的每個目錄中的 .agents/skills/。 |

來源：Cursor skills、VS Code agent skills、Codex skills。因此，一個位於 .claude/skills/ 的技能可以被四個工具中的三個讀取。若要同時觸及 Codex，請將每個技能保留在 .agents/skills/ 中，並將其資料夾符號連結到 .claude/skills/：Claude Code 和 Codex 都記錄了它們會遵循符號連結的技能資料夾。Codex 的相關資訊在 Codex skills 中。

Cursor 和 Copilot 會讀取這兩個資料夾，因此請檢查技能是否未重複列出。僅限 Claude 的欄位，例如 context: fork，不屬於標準的一部分，因此不要指望它們在其他工具中有效；Claude Code 文件列出了哪些欄位是標準的。

技能現在也可以來自伺服器。MCP Skills 擴充功能（SEP-2640）已定稿，因此 MCP 伺服器可以在其工具旁邊列出並提供 SKILL.md 資料夾。MCP 網站表示 SDK 和主機支援仍在實施中，因此在依賴它之前請檢查其客戶端矩陣。

如何測試技能，以及找出無人使用的技能？有三個內建指令，都比大多數技能指南還要新：

| 指令 | 啟用版本 | 功能 |

|---|---|---|

| /skill-doctor | 2.1.261 | 顯示哪些已載入的技能未被使用，以及每個技能在上下文中的成本，以便您可以關閉一些。報告會在 /plugin Stats 分頁中開啟。 |

| claude plugin eval | 2.1.269 | 在有和沒有外掛程式的獨立會話中執行外掛程式的評估套件，進行評分，並在低於閾值時以非零值退出，以便 CI 可以將其作為門檻。tool_used: Skill grader 會衡量技能觸發的頻率。 |

| /doctor prompt-audit | 2.1.283 | 審核 CLAUDE.md 檔案、技能、代理和指令中為舊模型編寫的提示詞模式，並指出過時路徑和衝突檔案。 |

claude plugin eval 涵蓋了外掛程式中附帶的技能。對於位於 .claude/skills/ 中的技能，文件則指向 skill-creator 外掛程式自己的評估循環。這兩種格式不可互換。

我的 Claude Code 技能為何沒有觸發？根據文件，請依序檢查以下原因：

| 原因 | 解決方案 |

|---|---|

| disable-model-invocation: true | 只有 /name 有效。如果希望 Claude 自行選擇技能，請將其移除。 |

| 描述與請求不符 | 將其改寫為任務，將關鍵用例放在首位，並新增 when_to_use 範例。 |

| paths glob 未匹配到任何相關檔案 | 根據 Claude 正在處理的檔案檢查 glob 模式。 |

| 被 skillOverrides 或權限規則隱藏 | 執行 /skills 查看可見的技能，並執行 /permissions 查看 Skill(...) 規則。 |

| 前置元資料解析失敗 | 技能仍會載入，但沒有設定任何欄位。請驗證 YAML 並檢查日誌。 |

更深層的問題是，有些問題是任何欄位都無法解決的。在 Vercel 的 Next.js 評估中，有 56% 的情況下技能從未被調用，而保持預設行為的技能通過率為 53%，與完全沒有文件相同。在 AGENTS.md 中壓縮的文件索引通過率為 100%（Vercel，2026 年 1 月）。

技能是一種賭注，賭模型會注意到它需要該技能。對於每次都必須發生的事情，請使用 hook；其權衡取捨請參閱 hook 指南以及 CLAUDE.md vs skills vs hooks。

技能與 CLAUDE.md：何去何從？Anthropic 自己的最佳實踐劃清了界線：CLAUDE.md 用於廣泛適用的內容，而「對於僅在某些時候相關的領域知識或工作流程，則應使用技能」。一個好的判斷標準是，新工程師在第一天執行每項任務時是否都需要這行內容。

如果是，則使用 CLAUDE.md。如果僅在處理支付相關事務時才需要，則使用帶有 paths glob 的技能。如果這是一個您特意執行的程序，則使用帶有 disable-model-invocation 的技能。

Harbor 的作用。技能會像 CLAUDE.md 的內容一樣累積。每個技能的添加成本很低，但卻很少有人移除它們，而且每個描述都會出現在每個提示詞中。harbor context 是 Harbor 中唯一不需要帳戶和網路的指令，它會讀取機器並列印每次互動的常駐預算：技能索引、未索引的技能檔案、代理定義、MCP 工具和注入的上下文，以及每個項目的來源。它還會標記沒有描述的技能檔案，這些是 Claude 無法自行選擇的技能。

執行 npm install -g harborloop 後，再執行 harbor context。技能仍然是某人編寫的檔案。其中的決策通常首先在拉取請求審查或 Slack 討論串中做出，當其中一個決策改變時，每個重複該決策的技能副本都必須手動更改。

Harbor 保留決策本身，而不是副本。它會讀取這些地方，由一個人批准哪些成為事實（或您設定的政策批准例行事項），然後每個代理都會獲得適用於該任務的事實。它會計算每個事實被提供多少次，以及答案引用它的頻率；引用是證據，但不是證明。請參閱「提供與引用」。

從您已有的內容開始。首先執行 harbor context；CLI 參考資料解釋了每一行，快速入門大約需要十分鐘。

問題與解答：

Claude Code 中的技能是什麼？技能是一個包含 SKILL.md 檔案的資料夾，其中包含名稱、描述和指令。Claude 在每次互動時都會檢視所有描述，並僅在任務符合或您輸入 /skill-name 時，才會載入完整的指令。

Claude Code 技能儲存在哪裡？專案技能位於 .claude/skills/<name>/SKILL.md，並透過 Git 共享。個人技能位於 ~/.claude/skills/。外掛程式也可以附帶技能，以 /plugin-name:skill-name 的形式執行。

Cursor 和 Codex 會讀取 Claude Code 技能嗎？Cursor 會：它會為了相容性載入 .claude/skills，VS Code 中的 Copilot 也會讀取它。Codex 不會；它讀取 .agents/skills。

將資料夾保留在 .agents/skills 中，並將其符號連結到 .claude/skills，以觸及所有四個工具，因為 Claude Code 和 Codex 都遵循符號連結的技能資料夾。

我的 Claude Code 技能為何沒有觸發？檢查是否設定了 disable-model-invocation，描述是否與任務匹配，paths glob 是否匹配相關檔案，以及是否被 skillOverrides 或權限規則隱藏。執行 /skills 查看 Claude 可以看到什麼。

我應該使用技能還是 CLAUDE.md？CLAUDE.md 用於適用於每個任務的內容，而技能則用於僅在某些時候重要的知識或工作流程。對於每次都必須發生的事情，請使用 hook，因為技能取決於模型是否選擇載入它。

聲明：我在 Harbor 工作，這篇筆記由 Harbor 發布。