如何打造真正有效的 Claude Code 技能 (完整指南)

您已經使用 Claude 一週了，卻一直在重複輸入同樣的內容。每次提交程式碼，您都得貼上那三條關於提交格式的規則。每次寫文件，您都得重新解釋您的風格。Claude 做得好，但對話一結束它就忘了，明天您又得全部重打一遍。

技能（skill）解決了這個問題。它是一個小小的資料夾，您只需建立一次，就能教會 Claude 一個永久性的工作流程，讓它在每次對話中自動套用，無需您再次要求。

以下是它的運作原理，簡而言之：技能是一個包含一個檔案的資料夾。Claude 會隨時保留該技能的一行摘要，只有在您的請求與之匹配時，才會載入完整的指令。這就是整個機制。

在本指南中，我們將從零建立一個真實的技能：commit-messages，它能以您指定的格式撰寫 git 提交訊息。如果您已安裝 Claude 且沒有其他東西，可以按照每個步驟操作。

您最終會得到什麼

技能的核心是一個資料夾，其中包含一個必要檔案 SKILL.md。隨著技能成長，可以加入三個選用資料夾：

1your-skill-name/
2├── SKILL.md          # 必要 - 主要技能檔案
3├── scripts/          # 選用 - 可執行程式碼
4├── references/       # 選用 - 文件資料
5└── assets/           # 選用 - 範本等

SKILL.md 本身有兩個部分：一個簡短的標頭，告訴 Claude 何時使用該技能；以及下方的指令，告訴 Claude 做什麼。這種拆分很重要。Claude 會不斷讀取標頭，因此它始終知道技能存在，但只有在您的請求匹配時，它才會載入指令。請記住這個區別，因為本指南中的幾乎所有內容都源自於此。

建立它

技能存放在您家目錄下的 .claude/skills 資料夾中，Claude Code 和桌面應用程式都會讀取這個資料夾。它是隱藏的，而且可能還不存在，因此最快的方法是使用一條指令來建立它，同時建立技能資料夾。

在 Mac 上，打開終端機並執行：

1mkdir -p ~/.claude/skills/your-skill-name

在 Windows 上，打開 PowerShell 並執行：

1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"

資料夾名稱不只是裝飾用。Claude 會將其視為技能的識別碼，而且有一個格式規則比其他任何規則更容易讓人出錯：

• 使用 kebab-case：notion-project-setup ✔
• 不要空格：Notion Project Setup ✖
• 不要底線：notion_project_setup ✖
• 不要大寫：NotionProjectSetup ✖

在該資料夾中，建立一個名為 SKILL.md 的檔案，並用任何文字編輯器開啟。從這裡開始，所有內容都將放入該檔案中。

在撰寫之前先設計它

有效的技能始於兩個決定，在您撰寫檔案之前就必須做出。這兩個決定感覺都可以跳過，但實際上都不能。

首先，明確決定技能應該在何時觸發。寫下兩三個真實情境，使用使用者實際上會輸入的詞語：

• "commit these changes"
• "write a commit message for this diff"
• "stage and commit"

這不是白費功夫。這些詞語將成為您描述和後續測試的原始材料，而一個沒有經過這樣設計的技能，往往會模糊不清，正是這種模糊使得它永遠無法觸發。

其次，決定您如何知道它有效。最重要的標準是技能是否會自動載入，無需您指定名稱。如果您每次都需要手動叫用它，那麼技能雖然在技術上執行了，但實際上失敗了。與此同時，也要觀察它是否能在您中途不修正的情況下完成任務，以及它是否能在不同對話中給出相同形狀的結果。

描述是成敗關鍵

在檔案的所有內容中，標頭中的描述最為重要，因為這是 Claude 決定是否載入技能時唯一會讀取的部分。您的指令可能完美無缺，但這無關緊要，因為如果描述不匹配，Claude 根本不會讀取它們。大多數「無法運作」的技能，問題實際上就出在這裡。

一個好的描述用一句話回答兩個問題：技能做什麼，以及 Claude 應該在何時使用它。後半部分是人們經常遺漏的。

以下是差異：

1# 弱 - 只說它是什麼，沒有給 Claude 可供匹配請求的依據
2description: Helps with git commits.
3
4# 強 - 指出它應該觸發的時刻
5description: Writes git commit messages in Conventional Commits format. Use when the user asks to commit changes, write a commit message, or stage and commit files.

弱版本告訴 Claude 技能存在，但從未將其與您可能說的任何話聯繫起來。強版本則列舉了實際的詞語，因此當您輸入 "commit these changes" 時，Claude 就有東西可以匹配。請使用使用者真正會用的詞語，整個描述保持在 1024 個字元以下，且不要在裡面放入 < 或 >。

當技能無法觸發時，幾乎總是需要在這裡修正。加入您實際使用的措辭。如果您說 "save my work"，但描述只提到 "commit"，Claude 就無法將兩者連結起來。反之，如果技能在不應該觸發時觸發，則縮小描述範圍或加入負面觸發條件：

1description: Writes git commit messages in Conventional Commits format. Use when committing changes. Do not use for writing code comments or documentation.

在您依賴技能之前，有一個快速的方法可以檢查您的成果。直接問 Claude：

"你什麼時候會使用 commit-messages 技能？"

Claude 會用自己的話複述您的描述。如果這與您實際希望技能觸發的時機不符，您就找到了問題所在，而且問題出在描述，而不是底下的指令。

撰寫 Claude 真正會遵循的指令

在標頭下方是主體，使用純 Markdown。這裡是您實際工作流程所在，有兩個習慣能區分 Claude 會遵循的指令與它會悄悄忽略的指令。

第一個是具體明確。Claude 會執行具體的指令，而忽略模糊的指令，因此您越精確，它的行為就越可靠：

1# 糟糕
2在最終確定前驗證提交。
3
4# 好
5執行 `python scripts/validate.py "<message>"`。
6如果失敗，修正以下項目：
7- 無效類型：使用 feat, fix, docs, refactor, test, chore
8- 摘要超過 60 個字元：縮短它

第二個是順序。Claude 優先處理它先讀到的內容，因此一條埋在長檔案底部的規則，是一條容易被忽略的規則。將任何必須嚴格遵守的規則放在頂部，並加上一個標題來提示：

1## 重要事項
2- 摘要行始終少於 60 個字元
3- 僅使用現在式："add"，而非 "added"

此外，語言本身也有其限制。指令是經過解讀的，這意味著 Claude 會很好地遵循它們，但並非每次都一模一樣。當某個檢查確實需要在每次執行時都通過時，不要用文字描述它，而是將其移入一個腳本，並讓指令執行它。程式碼每次都會做同樣的事情；一句話則不然。（這就是 scripts/ 資料夾的用途，接下來會介紹。）

一個在大多數技能中都能適用的結構如下：

1# 技能名稱
2
3## 重要事項
4必須遵守的關鍵規則。
5
6## 指令
7逐步、具體且可操作。
8
9## 範例
10具體的輸入和輸出。Claude 複製範例比遵循規則更可靠。

保持檔案精簡。當它開始超出核心指令時，就是將額外細節移出的時候，這正是選用資料夾的用途。

腳本、參考資料、資源

到目前為止，所有內容產生了一個能給 Claude 指令的技能。三個選用資料夾則將其轉變為一個能給 Claude 工具的技能，而這正是技能能做到普通提示詞做不到的事情的地方。

scripts/ 存放 Claude 要執行的程式碼，用於任何需要精確處理的事項。與其信任 Claude 用肉眼檢查提交格式是否正確，不如交給它一個檢查腳本：

1# scripts/validate.py
2import sys
3msg = sys.argv[1]
4types = ("feat", "fix", "docs", "refactor", "test", "chore")
5
6if msg.split(":")[0] not in types:
7    print(f"無效類型。請使用：{', '.join(types)}")
8elif len(msg.split("\n")[0]) > 60:
9    print("摘要過長（超過 60 個字元）")
10else:
11    print("OK")

然後在 SKILL.md 中告訴 Claude 使用它：

1在最終確定前，執行 `python scripts/validate.py "<message>"`
2並修正它標記的任何問題。

現在格式規則是由每次都相同方式執行的程式碼強制執行，而不是依賴 Claude 記住要檢查。

references/ 存放僅在需要時才載入的文件。假設您的提交慣例有兩頁的範圍、頁尾和邊界情況。將所有這些都放入 SKILL.md，則每次提交（即使只改一行）都會載入它們。改為移入參考檔案：

1your-skill-name/
2├── SKILL.md
3└── references/
4    └── conventions.md

並在主檔案中指向它：

1如需完整慣例清單，請參閱 references/conventions.md

Claude 僅在任務需要時才會開啟該檔案。這就是技能保持輕量運作的全部原因：繁重的細節存放在磁碟上，直到真正相關時才載入，而不是每次都在上下文中跟著跑。

assets/ 存放技能在其輸出中使用的檔案，而非作為指導閱讀的檔案，例如範本、設定檔或標誌。提交技能不需要任何資源，但一個生成報告的技能可能會在這裡保留一個 template.md 並每次填入內容，這樣每份報告都會有相同的結構。

總而言之，這三個資料夾是區分「告訴 Claude 您如何工作」的技能和「交給 Claude 確切工具來以您的方式完成工作」的技能的關鍵。

需要記住的一件事

技能並不是教會 Claude 一種新能力。它已經知道如何撰寫提交訊息。技能的作用是讓它每次都以您的方式完成工作，無需您再次說明。

而當技能無法運作時，原因幾乎從來不是您苦心經營的指令。而是描述。Claude 在讀取底下任何內容之前，就先根據那單一行描述決定是否載入技能。把描述寫對，底下的一切才能被真正使用。

如果這篇文章對您有幫助，請前往我的個人檔案並追蹤。我撰寫關於科技、AI 和真正運作的系統。

Ciao,

@undefinedKi