建構 Claude Code 的經驗教訓：我們如何運用技能

技能已成為 Claude Code 中最常用的擴充點之一。它們彈性、易於建立且方便分發。

但這種彈性也使得難以判斷什麼最有效。哪些類型的技能值得建立？撰寫出色技能的秘訣是什麼？您何時應該與他人分享它們？

在 Anthropic，我們已在 Claude Code 中廣泛地使用技能，數百種技能正在積極使用中。這些是我們在運用技能加速開發方面所學到的經驗教訓。

什麼是技能？

如果您是技能新手，我建議您閱讀我們的文件或觀看我們在 Skilljar 上關於 Agent 技能的最新課程，本文將假設您對技能已有一定程度的了解。

我們聽到關於技能的一個常見誤解是，它們「只是 markdown 檔案」，但技能最有趣的部分是它們不只是文字檔。它們是資料夾，可以包含 Agent 可以發現、探索和操作的腳本、資產、資料等。

在 Claude Code 中，技能還具有多種配置選項，包括註冊動態 hook。

我們發現 Claude Code 中一些最有趣的技能巧妙地運用了這些配置選項和資料夾結構。

技能類型

在歸類整理我們所有的技能後，我們注意到它們歸類為幾個重複出現的類別。最好的技能明確地歸屬於其中一類；較令人困惑的技能則橫跨多個類別。這不是一個權威性列表，但它是一個很好的思考方式，可以幫助您判斷組織內部是否缺少任何技能。

1. 程式庫與 API 參考

解釋如何正確使用程式庫、CLI 或 SDK 的技能。這些技能可以適用於內部程式庫，也可以適用於 Claude Code 有時會遇到問題的常用程式庫。這些技能通常包含一個參考程式碼片段資料夾，以及 Claude 在撰寫腳本時應避免的陷阱列表。

範例：

• billing-lib — 您的內部計費程式庫：邊緣案例、潛在問題等。

• internal-platform-cli — 您的內部 CLI 包裝器中的每個子命令，並附帶使用時機範例。

• frontend-design — 讓 Claude 更好地掌握您的設計系統。

2. 產品驗證

描述如何測試或驗證您的程式碼是否正常運作的技能。這些技能通常與外部工具（如 playwright、tmux 等）搭配使用以進行驗證。

驗證技能對於確保 Claude 的輸出正確無誤極其有用。讓一位工程師花費一週時間，專注於讓您的驗證技能變得卓越是值得的。

考慮使用一些技巧，例如讓 Claude 錄製其輸出的影片，以便您能確切看到它測試了什麼，或者在每個步驟強制執行程式化斷言。這些通常是透過在技能中包含各種腳本來完成的。

範例：

• signup-flow-driver — 在無頭瀏覽器中執行註冊 → 電子郵件驗證 → 入職流程，並在每個步驟中加入斷言狀態的 hook。

• checkout-verifier — 使用 Stripe 測試卡驅動結帳 UI，驗證發票是否實際處於正確狀態。

• tmux-cli-driver — 用於互動式 CLI 測試，其中您正在驗證的內容需要 TTY。

3. 資料擷取與分析

連接到您的資料和監控堆疊的技能。這些技能可能包含用於憑證擷取資料的程式庫、特定的儀表板 ID 等，以及關於常見工作流程或獲取資料方法的說明。

範例：

• funnel-query — 「我應該加入哪些事件才能看到註冊 → 啟用 → 付費」以及實際包含規範 user_id 的表格。

• cohort-compare — 比較兩個群組的留存率或轉換率，標記統計上顯著的差異，並連結到區段定義。

• grafana — 資料源 UID、叢集名稱、問題 → 儀表板查詢表。

4. 業務流程與團隊自動化

將重複性工作流程自動化為一個命令的技能。這些技能通常是相當簡單的指示，但可能對其他技能或 MCP 有更複雜的依賴關係。對於這些技能，將先前的結果儲存在日誌檔中可以幫助模型保持一致並反思先前的工作流程執行。

範例：

• standup-post — 彙總您的票務追蹤器、GitHub 活動和先前的 Slack → 格式化的站立會議報告，僅顯示差異。

• create--ticket — 強制執行 schema（有效列舉值、必填欄位）以及建立後工作流程（通知審閱者、在 Slack 中連結）。

• weekly-recap — 合併的 PR + 已關閉的票務 + 部署 → 格式化的回顧貼文。

5. 程式碼搭建與範本

為程式庫中特定功能生成框架樣板程式碼的技能。您可以將這些技能與可組合的腳本結合使用。當您的搭建具有無法完全由程式碼涵蓋的自然語言需求時，它們特別有用。

範例：

• new--workflow — 使用您的註解來搭建新的服務/工作流程/處理器。

• new-migration — 您的遷移檔案範本以及常見陷阱。

• create-app — 新的內部應用程式，預先配置您的身份驗證、日誌記錄和部署設定。

6. 程式碼品質與審查

在您的組織內部強制執行程式碼品質並協助審查程式碼的技能。這些可以包括確定性腳本或工具以實現最大穩健性。您可能希望將這些技能作為 hook 的一部分或在 GitHub Action 內部自動執行。

• adversarial-review — 產生一個「新視角」的子 Agent 進行評論，實施修復，並迭代直到發現的問題降級為吹毛求疵。

• code-style — 強制執行程式碼風格，特別是 Claude 預設不擅長的風格。

• testing-practices — 關於如何撰寫測試以及測試內容的說明。

7. CI/CD 與部署

協助您在程式庫中擷取、推送和部署程式碼的技能。這些技能可能會參考其他技能來收集資料。

範例：

• babysit-pr — 監控 PR → 重試不穩定的 CI → 解決合併衝突 → 啟用自動合併。

• deploy- — 建置 → 冒煙測試 → 逐步流量發布並比較錯誤率 → 回歸時自動回滾。

• cherry-pick-prod — 隔離工作樹 → cherry-pick → 衝突解決 → 附帶範本的 PR。

8. 運行手冊

接受症狀（例如 Slack 討論串、警報或錯誤簽章），透過多工具調查，並產生結構化報告的技能。

範例：

• -debugging — 映射症狀 → 工具 → 您的最高流量服務的查詢模式。

• oncall-runner — 擷取警報 → 檢查常見問題 → 格式化發現結果。

• log-correlator — 給定一個請求 ID，從所有可能接觸過它的系統中提取匹配的日誌。

9. 基礎設施操作

執行例行維護和操作程序的技能 — 其中一些涉及破壞性操作，並受益於防護措施。這些技能讓工程師更容易在關鍵操作中遵循最佳實踐。

範例：

• -orphans — 尋找孤立的 pod/volume → 發布到 Slack → 浸泡期 → 使用者確認 → 級聯清理。

• dependency-management — 您組織的依賴項審批工作流程。

• cost-investigation — 「為什麼我們的儲存/出口費用飆升」以及特定的儲存桶和查詢模式。

建立技能的技巧

一旦您決定要建立的技能，您該如何撰寫它？這些是我們發現的一些最佳實踐、技巧和訣竅。

我們最近也發布了 Skill Creator，讓在 Claude Code 中建立技能變得更容易。

不要陳述顯而易見的事實

Claude Code 對您的程式庫了解很多，Claude 對程式撰寫也了解很多，包括許多預設觀點。如果您發布的技能主要關於知識，請嘗試專注於讓 Claude 跳脫其常規思維方式的資訊。

前端設計技能就是一個很好的例子 — 它是由 Anthropic 的一位工程師透過與客戶迭代來改進 Claude 的設計品味，避免像 Inter 字體和紫色漸變這樣的經典模式而建立的。

建立一個陷阱區塊

任何技能中訊號最強的內容是陷阱區塊。這些區塊應該從 Claude 在使用您的技能時遇到的常見失敗點中建立。理想情況下，您會隨著時間的推移更新您的技能以捕捉這些陷阱。

使用檔案系統與漸進式揭露

正如我們之前所說，技能是一個資料夾，而不僅僅是一個 markdown 檔案。您應該將整個檔案系統視為一種上下文工程和漸進式揭露的形式。告訴 Claude 您的技能中有哪些檔案，它將在適當的時候讀取它們。

漸進式揭露最簡單的形式是指出其他 markdown 檔案供 Claude 使用。例如，您可以將詳細的函數簽章和使用範例拆分到 references/api.md 中。

另一個例子：如果您的最終輸出是一個 markdown 檔案，您可以在 assets/ 中為其提供一個範本檔案以供複製和使用。

您可以擁有參考資料、腳本、範例等資料夾，這有助於 Claude 更有效地工作。

避免限制 Claude

Claude 通常會嘗試遵循您的指示，由於技能是如此可重複使用，您會希望小心不要在指示中過於具體。給予 Claude 所需的資訊，但給予它適應情況的彈性。例如：

仔細思考設定

有些技能可能需要使用者提供上下文進行設定。例如，如果您正在建立一個將您的站立會議報告發布到 Slack 的技能，您可能希望 Claude 詢問要發布到哪個 Slack 頻道。

一個好的模式是將此設定資訊儲存在技能目錄中的 config.json 檔案中，如上述範例所示。如果未設定配置，Agent 就可以向使用者詢問資訊。

如果您希望 Agent 呈現結構化的多選問題，您可以指示 Claude 使用 AskUserQuestion 工具。

描述欄位是供模型使用的

當 Claude Code 啟動一個會話時，它會建立所有可用技能及其描述的列表。Claude 會掃描此列表以決定「是否有適用於此請求的技能？」這意味著描述欄位不是摘要 — 它是描述何時觸發此 PR 的說明。

記憶體與資料儲存

有些技能可以透過在其中儲存資料來包含某種形式的記憶。您可以將資料儲存在任何簡單的內容中，例如僅追加的文字日誌檔或 JSON 檔案，或者像 SQLite 資料庫一樣複雜的內容。

例如，一個 standup-post 技能可能會保留一個 standups.log 檔案，其中包含它撰寫的每個貼文，這意味著下次您執行它時，Claude 會讀取自己的歷史記錄，並能判斷自昨天以來發生了什麼變化。

儲存在技能目錄中的資料在您升級技能時可能會被刪除，因此您應該將其儲存在一個穩定資料夾中，截至今天，我們提供 ${CLAUDE_PLUGIN_DATA} 作為每個 plugin 的穩定資料夾來儲存資料。

儲存腳本與生成程式碼

您可以賦予 Claude 最強大的工具之一就是程式碼。給予 Claude 腳本和程式庫讓 Claude 將其精力花在組合上，決定下一步要做什麼，而不是重建樣板程式碼。

例如，在您的資料科學技能中，您可能有一個函數程式庫，用於從事件源擷取資料。為了讓 Claude 進行複雜分析，您可以為它提供一組輔助函數，如下所示：

然後，Claude 可以即時生成腳本來組合此功能，以便對「週二發生了什麼？」等提示進行更進階的分析。

隨需 Hook

技能可以包含僅在呼叫技能時才啟用，並持續整個會話期間的 hook。將此用於更具主觀性的 hook，您不希望它們始終運行，但有時卻極其有用。

例如：

• /careful — 透過 Bash 上的 PreToolUse 匹配器，阻止 rm -rf、DROP TABLE、force-push、kubectl delete。您只希望在知道正在操作生產環境時才啟用此功能 — 始終開啟會讓您抓狂。

• /freeze — 阻止任何不在特定目錄中的編輯/寫入。在偵錯時很有用：「我想添加日誌，但我總是意外地『修復』不相關的內容」。

分發技能

技能的最大好處之一是您可以與團隊的其他成員分享它們。

您有兩種方式可以與他人分享技能：

• 將您的技能提交到您的程式庫（在 ./.claude/skills 下）。

• 建立一個 plugin，並擁有一個 Claude Code Plugin 市集，使用者可以在其中上傳和安裝 plugin（在此處的文件中閱讀更多資訊）。

對於跨相對較少程式庫的小型團隊來說，將技能提交到程式庫中運作良好。但每個提交的技能也會為模型的上下文增加一點負擔。隨著規模的擴大，內部 plugin 市集允許您分發技能，並讓您的團隊決定安裝哪些技能。

管理市集

您如何決定哪些技能進入市集？人們如何提交它們？

我們沒有一個集中式團隊來決定；相反，我們嘗試有機地發現最有用的技能。如果您有一個希望人們試用的技能，您可以將其上傳到 GitHub 中的沙盒資料夾，並在 Slack 或其他論壇中引導人們使用它。

一旦技能獲得關注（由技能擁有者決定），他們就可以提交 PR 將其移至市集。

需要注意的是，建立不良或冗餘的技能可能相當容易，因此確保在發布前進行策劃的方法很重要。

組合技能

您可能希望擁有相互依賴的技能。例如，您可能有一個上傳檔案的檔案上傳技能，以及一個生成 CSV 並上傳的 CSV 生成技能。這種依賴管理尚未原生內建於市集或技能中，但您可以按名稱引用其他技能，如果它們已安裝，模型將會呼叫它們。

衡量技能

為了了解技能的表現，我們使用 PreToolUse hook，它允許我們記錄公司內部的技能使用情況（範例程式碼在此處）。這意味著我們可以找到受歡迎或與我們的預期相比觸發不足的技能。

結論

技能是 Agent 極其強大、靈活的工具，但仍處於早期階段，我們都在摸索如何最佳地使用它們。

請將此視為我們發現有效的有用技巧的集合，而不是權威指南。了解技能的最佳方式是開始使用、實驗並找出適合您的方案。我們大多數的技能最初只是幾行程式碼和一個陷阱，並隨著 Claude 遇到新的邊緣案例，人們不斷地改進它們。

希望這對您有所幫助，如果您有任何問題，請告訴我。