Claude Code 技能：運作原理與觸發時機深度解析

這篇文章最初發表於 khadim.tech。簡而言之，Claude Code 技能是一個包含 SKILL.md 檔案的資料夾，其中包含一個簡短的 YAML 標頭，其名稱和描述會告訴 Claude 何時使用該技能，而實際指令則僅在技能執行時載入。當您的請求符合條件時，Claude 會自行選用技能，或者您可以手動執行 /skill-name。

在我對 Claude Code 2.1.310 進行的 108 次測試中，當技能名稱或描述明確指出其功能時，15 個符合請求中有 15 個成功載入技能；若兩者皆不明確，則 15 個請求中僅有 5 個載入；而當設定 disable-model-invocation: true 時，技能則從未載入，此時 Claude 會在沒有技能規則的情況下完成任務。

我在自己的代理儲存庫中運行 71 個 Claude Code 技能，並在我的 YouTube 頻道 Khadim Labs 上製作簡短的 Claude Code 教學。在製作技能相關的影片時，我讓 Claude Code 從一句話中編寫一個技能，結果它做出了一個我沒有要求的決定。

因此，我測量了 Claude 何時會自行載入技能，因為每份指南都說「寫一個好的描述」，但沒有一份展示這會帶來什麼改變。

Claude Code 技能是一個包含 SKILL.md 檔案的資料夾，它會教導 Claude Code 一個特定的程序。這個檔案分為兩個部分：由 --- 行包圍的 YAML 前置資料 (frontmatter)，以及後續的 Markdown 指令。

Anthropic 的技能文件明確指出前置資料的規則：「所有欄位都是可選的。僅建議提供 description 欄位，以便 Claude 知道何時使用該技能。」技能名稱預設為資料夾的名稱。

例如：---name: tidy-folderdescription: Sort the loose files in the current folder into subfolders by type. Use when the user asks to tidy, clean up, organize or sort a folder.---# tidy-folderOnly move files. Never delete or overwrite anything. Finish with a table of what moved.

技能之所以成本低廉，是因為它們的載入方式。Claude Code 只會在上下文 (context) 中保留技能的名稱和描述，而「完整的技能內容僅在被調用時才載入」。一個 400 行的程序在被請求需要之前幾乎不花費任何資源，而 CLAUDE.md 則在每個會話中完整載入。

技能遵循 Agent Skills 開放標準，而 Claude Code 在此基礎上增加了自己的欄位，例如調用控制和在子代理中運行技能。

Claude Code 技能的儲存位置分為幾種範圍：個人技能儲存於 ~/.claude/skills/<name>/SKILL.md，可在該機器的所有專案中使用；專案技能儲存於 .claude/skills/<name>/SKILL.md，一旦提交後，所有複製該儲存庫的人都能使用；外掛程式技能儲存於 <plugin>/skills/<name>/SKILL.md，當外掛程式啟用時，可透過 /plugin-name:skill-name 執行；企業技能則儲存於受管理的設定目錄中，部署到組織的每台機器上。

當兩個技能名稱相同時，企業級技能優先於個人技能，個人技能又優先於專案技能。舊的 .claude/commands/deploy.md 檔案仍然有效，因為「自訂指令已合併到技能中」，且技能會覆蓋同名的指令檔案。/skills 指令會列出 Claude Code 找到的所有技能，它也會監控這些資料夾，因此新增或編輯的 SKILL.md 會在運行中的會話中即時生效，無需重新啟動。

您可以手動編寫 SKILL.md，但最快的方法是描述您想要的功能。我在一個運行 Claude Code 2.1.310 的乾淨 Windows 虛擬機中輸入：「建立一個名為 tidy-folder 的個人技能。它將當前資料夾中的檔案依類型分類到子資料夾中，將截圖放入專屬的 Screenshots 資料夾，絕不刪除任何東西，並以一個簡短的移動清單表格作結。」

五十秒後，它便在 ~/.claude/skills/tidy-folder/SKILL.md 寫好了一個長達 2,936 字元的技能檔案。

這是它未經編輯的前置資料：---name: tidy-folderdescription: Sort the loose files in the current folder into subfolders by type (Images, Documents, Spreadsheets, Audio, Video, Archives, Code, Other), put screenshots in a Screenshots folder, never delete anything, and finish with a table of what moved. Use when the user asks to tidy, clean up, organize or sort a folder.disable-model-invocation: true---

技能主體還添加了一些我沒有明確說明的規則。它只對資料夾中的直接檔案操作，並跳過隱藏和系統檔案。當檔案名稱衝突時，它會透過添加 (1)、(2) 等來保留兩個檔案，並使用 PowerShell 的 Move-Item 指令移動檔案，而不帶 -Force 參數。如果資料夾看起來像一個專案（例如包含 .git 資料夾或解決方案檔案），它會先停止並詢問，因為移動檔案可能會破壞專案。

我從未要求前置資料中的最後一行。disable-model-invocation: true 使技能僅限手動執行：Claude 不會自行載入它，只有當您輸入 /tidy-folder 時才會運行。Claude 設定此項是因為該技能會移動檔案。

文件以相同方式描述此欄位，適用於「您希望手動觸發的工作流程」，其範例是一個執行 Git 提交的技能。手動在一個包含 16 個雜亂檔案的資料夾上運行後，它報告「移動 16 個，跳過 0 個，刪除 0 個」。

接著我問：「修改我的 tidy-folder 技能，讓你在我要求整理資料夾時可以自行使用。」它刪除了那一行。在一個包含 16 個檔案的新資料夾中，一個簡單的「整理這個資料夾。」指令在沒有任何斜線指令的情況下載入了該技能，遵循相同的規則，再次移動了 16 個檔案，跳過 0 個，刪除 0 個。

我給 Claude Code 提供了六種不同前置資料的相同技能主體。其中兩個變數是：技能名稱是否說明其功能（tidy-folder 或 helper），以及描述是否說明其功能（Claude 編寫的長描述、Folder utility. 或 General helper.）。

第六個版本是添加了 disable-model-invocation: true 的特定版本。每個版本都收到了六個請求：五個以不同措辭要求整理資料夾，一個只詢問資料夾中有什麼。

我在 2026 年 10 月 26 日進行了三輪測試，總共 108 次運行。每次運行都在一個新的資料夾中開始，包含六個虛擬檔案，技能位於 .claude/skills/ 中，使用 Claude Code 2.1.310 和 Opus 5.5（claude-opus-5-5）以無頭模式運行 claude -p。

技能清單中還包含同步到我 claude.ai 帳戶的九個技能（PDF、Word、Excel 等），但沒有一個是關於資料夾的。當 Claude 調用其技能工具時，就算作一次觸發。檔案指令被阻止，因此沒有實際移動任何東西。

測試結果顯示，Claude 同時讀取名稱和描述，只要有一個清晰的訊號就足夠了。一個具有明確名稱的兩字描述每次都能觸發技能，一個無意義名稱但有明確描述的技能也能觸發。若兩者皆不明確，觸發率則降至 15 次中的 5 次。五種不同的整理措辭沒有實質差異，而僅詢問資料夾內容的請求在任何版本中都未載入技能。

手動執行那一列需要仔細審視。Claude 從未載入該技能，但它也沒有拒絕這項工作：在所有 15 次運行中，它直接使用 PowerShell 或 Bash 自行整理檔案，而沒有遵循技能的規則。如果這些規則很重要（例如我的規則是「絕不刪除任何東西」），那麼請輸入 /tidy-folder，或者讓 Claude 自行載入技能。

這項測試是在一個模型上，將一個技能與大約十幾個其他技能進行比較。當技能數量更多時，Claude Code 會開始從清單中刪除描述，但保留所有名稱（下一節），這也是將技能命名為其功能的原因之一。

如果您的 Claude Code 技能沒有觸發，請依序檢查以下幾點，我自己也曾遇到前兩項問題。首先，技能名稱或描述沒有說明其功能。請使用人們會輸入的詞彙（例如「整理、清理、組織或排序資料夾」），並將該使用情境放在首位，因為每個描述在清單中會被截斷為 1,536 個字元。

其次，disable-model-invocation: true 被設定了。它可能在您沒有手動編寫的情況下出現，就像我的 tidy-folder 技能所示，因此在重寫描述之前請先閱讀前置資料。第三，前置資料解析失敗。Claude Code 僅在開頭的 --- 是檔案的第一行時才會讀取前置資料。

如果標記之間的 YAML 格式錯誤，技能將在沒有任何欄位的情況下載入，因此 /skill-name 仍然有效，但 Claude 沒有描述可以匹配。欄位名稱必須完全匹配，包括連字號，Claude Code 會忽略未知欄位而不報錯。claude --debug 會顯示解析錯誤。

第四，您擁有的技能太多了。名稱和描述的清單大約佔用模型上下文視窗的 1%，當它溢出時，Claude Code 會刪除您最少使用的技能的描述，但保留其名稱。/doctor 會估計清單的成本，而 skillListingBudgetFraction 設定可以提高預算。

第五，技能設定了路徑。然後它只會對當前工作目錄中匹配的檔案啟用。最快的檢查方法是詢問 Claude「有哪些技能可用？」如果技能不在答案中，Claude 就無法選擇它。

Claude Code 技能與 CLAUDE.md、斜線指令、子代理和 Hook 之間存在差異。CLAUDE.md 在每個會話中完整載入，適用於始終適用的事實和規則。技能則始終載入名稱和描述，主體僅在使用時載入，適用於程序、清單和參考資料。斜線指令（.claude/commands/）與技能相同，兩者已合併，適用於現有指令，新工作建議使用技能。

子代理在自己的上下文視窗中運行，適用於不應佔用主要對話的工作；一個帶有 context: fork 的技能會將其指令傳遞給子代理。Hook 在每個匹配事件上運行，適用於每次都必須遵守且不涉及判斷的規則。文件提供了一個簡單的測試，用於將內容從 CLAUDE.md 移出：「當您不斷將相同的指令、清單或多步驟程序貼到聊天中，或者當 CLAUDE.md 的某個部分已發展成程序而非事實時，就建立一個技能。」

當 Claude 每次都跳過必須遵守的規則時，他們建議將該規則移至 Hook 中。

我的代理儲存庫中包含 71 個技能，涵蓋了我審查合併請求、發布網站和經營 YouTube 頻道等工作。其中有兩個教訓讓我花費了不少時間。首先，不要將技能命名為內建指令。我曾有一個名為 resume 的履歷技能，結果導致 Claude Code 的內建 /resume 指令（用於重新開啟先前的會話）停止運作。

這是文件記載的行為：「在本地終端機會話中，您的技能會取代內建指令，但不會取代其別名。」我將我的技能重新命名為 resume-cv，現在索引我技能的腳本會拒絕使用內建名稱。其次，為每個技能保留一份副本並指向它。我的技能儲存在一個 Claude Code 不會掃描的普通 skills/ 資料夾中。

一個腳本會為每個技能寫入一個單行指標到 .claude/commands/<name>.md（「讀取 skills/<name>/SKILL.md 並遵循它」），這樣 / 指令就能運作，同時指令保持在一個位置，當指標遺失或過時時，同一個腳本會導致建置失敗。

當我第一次生成它們時，所有 55 個指標都在已運行的會話中生效，無需重新啟動。包含 tidy-folder 運行的技能影片，已在我的 YouTube 頻道上發布。

常見問題：模糊的描述會阻止 Claude 使用技能嗎？如果名稱清晰，則不會。在我的測試中，一個名為 tidy-folder 且描述為「資料夾工具」的技能，在 15 個整理請求中全部載入。而一個名為 helper 且描述為「通用助手」的技能，僅在 15 個請求中載入 5 次，因此請給 Claude 至少一個清晰的訊號，最好是兩者都提供。

Claude Code 技能會佔用上下文嗎？會，但不多。Claude Code 會在上下文中保留每個技能的名稱和描述，並僅在技能運行時才載入完整的 SKILL.md。每個描述會被截斷為 1,536 個字元，整個清單大約佔用模型上下文視窗的 1%；超過此限制後，最少使用的技能會失去其描述，但保留其名稱。

新增技能後需要重新啟動 Claude Code 嗎？不需要。Claude Code 會監控技能資料夾，並在運行中的會話中即時讀取新的或編輯過的 SKILL.md。唯一的例外是當會話啟動時不存在的頂層技能資料夾：對於這種情況，請運行 /reload-skills。

技能和斜線指令有什麼區別？現在差異很小。自訂指令已合併到技能中，所以...