打造 Claude Code 的經驗：我們如何使用 Skills（翻譯）

翻譯說明：本文翻譯自 Anthropic 工程師 Thariq Shihipar（@trq212）的文章 Lessons from Building Claude Code: How We Use Skills。Thariq 是 Claude Code 團隊的成員，這篇文章分享了 Anthropic 內部使用 Skills 的實戰經驗。翻譯由 Fox 完成，所有觀點與建議均為原作者立場。

Skills 已經成為 Claude Code 中最常被使用的擴充機制之一。它們靈活、容易製作、也容易分發。

但這種靈活性也讓人很難判斷什麼做法最好。哪些類型的 Skills 值得做？寫好一個 Skill 的祕訣是什麼？什麼時候該分享給其他人？

我們在 Anthropic 內部大量使用 Claude Code 的 Skills，目前有數百個在日常使用中。以下是我們在用 Skills 加速開發過程中學到的經驗。

什麼是 Skills？

如果你對 Skills 還不熟悉，建議先閱讀我們的文件或觀看我們在 Skilljar 上的最新課程，本文假設你已經有一些基礎認識。

關於 Skills，一個常見的誤解是「它們只是 Markdown 檔案」。但 Skills 最有趣的地方在於，它們不只是文字檔，而是可以包含腳本、資源檔、資料等內容的資料夾，Agent 可以探索和操作這些內容。

在 Claude Code 中，Skills 還有豐富的設定選項，包括註冊動態 Hooks。

我們發現，Claude Code 中最有趣的 Skills，往往是那些創造性地運用了設定選項和資料夾結構的。

Skills 的類型

在整理了我們所有的 Skills 之後，我們注意到它們會聚集成幾個重複出現的類別。最好的 Skills 清楚地屬於其中一類，最令人困惑的則橫跨好幾類。這不是一個完整的清單，但可以幫你思考你的組織裡是否缺少了某一類。

1. 函式庫與 API 參考

說明如何正確使用某個函式庫、CLI 或 SDK 的 Skills。可以是內部函式庫，也可以是 Claude Code 有時會搞錯的常見函式庫。這類 Skills 通常會附帶參考程式碼片段的資料夾，以及一份讓 Claude 避免踩坑的注意事項清單。

範例：

• billing-lib — 你的內部計費函式庫：邊界情況、常見陷阱等
• internal-platform-cli — 內部 CLI 的每個子命令，附帶使用時機範例
• frontend-design — 讓 Claude 更懂你的設計系統

2. 產品驗證

描述如何測試或驗證程式碼是否正常運作的 Skills。通常會搭配外部工具如 Playwright、tmux 等來執行驗證。

驗證類 Skills 對確保 Claude 的產出品質非常有用。值得讓一位工程師花一整週專門把驗證類 Skills 做好。

可以考慮的技巧包括：讓 Claude 錄製產出的影片，這樣你可以看到它實際測試了什麼；或者在每一步強制執行程式化的狀態檢查。這些通常透過在 Skill 裡放入各種腳本來實現。

範例：

• signup-flow-driver — 在無頭瀏覽器中跑完 註冊 → 信箱驗證 → 新手引導，每步都有狀態斷言的 Hook
• checkout-verifier — 用 Stripe 測試卡驅動結帳 UI，驗證帳單是否真的進入正確狀態
• tmux-cli-driver — 用於需要 TTY 的互動式 CLI 測試

3. 資料擷取與分析

連接到你的資料和監控系統的 Skills。這類 Skills 可能包含帶有憑證的資料擷取函式庫、特定的儀表板 ID 等，以及常見工作流程或取得資料方式的說明。

範例：

• funnel-query — 「要 JOIN 哪些事件才能看到 註冊 → 啟用 → 付費」，加上實際存放標準 user_id 的資料表
• cohort-compare — 比較兩個群組的留存率或轉換率，標記統計顯著差異，連結到分群定義
• grafana — 資料來源 UID、叢集名稱、問題 → 儀表板對照表

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

把重複性工作流程自動化成一道命令的 Skills。這類 Skills 通常是相當簡單的指令，但可能依賴其他 Skills 或 MCP。對這類 Skills 來說，把歷次執行結果存在日誌檔裡，可以幫助模型保持一致性，並回顧先前的執行情況。

範例：

• standup-post — 彙整你的票務追蹤、GitHub 活動和先前的 Slack 訊息 → 格式化的站立會議報告，只顯示差異
• create-ticket — 強制執行結構（有效的列舉值、必填欄位），加上建立後的工作流程（通知審查者、在 Slack 貼連結）
• weekly-recap — 合併的 PR + 關閉的票 + 部署 → 格式化的週報

5. 程式碼鷹架與範本

為程式碼庫中的特定功能產生框架樣板的 Skills。你可以把這些 Skills 和可組合的腳本結合使用。當你的鷹架有自然語言的需求、無法純靠程式碼覆蓋時，這類 Skills 特別有用。

範例：

• new-workflow — 用你的註解建立新的服務/工作流/處理器
• new-migration — 你的遷移檔範本加上常見陷阱
• create-app — 預先接好你的認證、日誌和部署設定的新內部應用程式

6. 程式碼品質與審查

在你的組織內強制執行程式碼品質並協助程式碼審查的 Skills。可以包含確定性腳本或工具以達到最大穩健性。你可能會想在 Hooks 或 GitHub Action 中自動執行這些 Skills。

範例：

• adversarial-review — 生成一個全新視角的子 Agent 來挑毛病，實施修復，反覆迭代直到問題降級為吹毛求疵
• code-style — 強制執行程式碼風格，特別是 Claude 預設做不好的風格
• testing-practices — 如何撰寫測試以及要測試什麼的說明

7. CI/CD 與部署

幫助你在程式碼庫中擷取、推送和部署程式碼的 Skills。這類 Skills 可能會引用其他 Skills 來收集資料。

範例：

• babysit-pr — 監控 PR → 重試不穩定的 CI → 解決合併衝突 → 啟用自動合併
• deploy-service — 建置 → 冒煙測試 → 逐步流量切換並比較錯誤率 → 回歸時自動回滾
• cherry-pick-prod — 隔離的工作樹 → cherry-pick → 衝突解決 → 使用範本建立 PR

8. 運維手冊

接收一個症狀（例如 Slack 討論串、告警或錯誤簽章），走過多工具調查流程，並產出結構化報告的 Skills。

範例：

• service-debugging — 把症狀對應到工具和查詢模式，適用於你流量最高的服務
• oncall-runner — 擷取告警 → 檢查常見嫌疑 → 格式化發現
• log-correlator — 給定一個請求 ID，從每個可能經手的系統拉取相關日誌

9. 基礎設施操作

執行例行維護和操作程序的 Skills，其中一些涉及需要防護機制的破壞性操作。這些讓工程師更容易在關鍵操作中遵循最佳實踐。

範例：

• resource-orphans — 找到孤立的 Pod/Volume → 發到 Slack → 靜置期 → 用戶確認 → 級聯清理
• dependency-management — 你的組織的依賴套件審批工作流程
• cost-investigation — 「為什麼我們的儲存/出站流量帳單暴增」，附帶特定的 Bucket 和查詢模式

製作 Skills 的技巧

決定了要做什麼 Skill 之後，該怎麼寫？以下是我們發現的一些最佳實踐、技巧和訣竅。

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

別講廢話

Claude Code 對你的程式碼庫了解很多，Claude 對寫程式也了解很多，包括許多預設的看法。如果你發布的 Skill 主要是知識型的，盡量聚焦在能把 Claude 推出常規思維的資訊上。

前端設計 Skill 就是一個好例子，它由 Anthropic 的一位工程師透過與客戶反覆迭代來改善 Claude 的設計品味，避免像 Inter 字型和紫色漸層這類經典模式。

建立「常見陷阱」區塊

任何 Skill 中訊號最強的內容就是「常見陷阱」（Gotchas）區塊。這些區塊應該從 Claude 在使用你的 Skill 時遇到的常見失敗點中累積起來。理想情況下，你會隨著時間更新你的 Skill 來捕捉這些陷阱。

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

如同前面提到的，Skill 是一個資料夾，不只是一個 Markdown 檔。你應該把整個檔案系統視為上下文工程和漸進式揭露的一種形式。告訴 Claude 你的 Skill 裡有哪些檔案，它會在適當的時機讀取它們。

最簡單的漸進式揭露形式是指向其他 Markdown 檔讓 Claude 使用。例如，你可以把詳細的函式簽名和使用範例拆分到 references/api.md。

另一個範例：如果你的最終產出是一個 Markdown 檔，你可以在 assets/ 中放一個範本檔供複製使用。

你可以建立參考文件、腳本、範例等資料夾，幫助 Claude 更有效地工作。

避免過度限制 Claude

Claude 通常會盡量遵循你的指示，而且因為 Skills 是高度可重用的，你要小心不要在指示中過於具體。給 Claude 它需要的資訊，但也給它適應情況的彈性。

想清楚設定流程

有些 Skills 可能需要用戶提供上下文來設定。例如，如果你正在製作一個把站立會議報告發到 Slack 的 Skill，你可能會希望 Claude 詢問要發到哪個 Slack 頻道。

一個好的做法是把這些設定資訊存在 Skill 目錄中的 config.json 檔案裡。如果設定還沒完成，Agent 就可以向用戶詢問資訊。

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

Description 欄位是給模型看的

當 Claude Code 啟動一個會話時，它會建立一份所有可用 Skills 及其描述的清單。這份清單就是 Claude 用來判斷「這個請求有沒有對應的 Skill？」的依據。也就是說，description 欄位不是摘要，而是描述什麼時候該觸發這個 Skill。

記憶與資料儲存

有些 Skills 可以透過在內部儲存資料來實現一種記憶功能。你可以用簡單的追加式文字日誌或 JSON 檔來儲存資料，也可以用複雜的 SQLite 資料庫。

例如，一個 standup-post Skill 可能會保留一個 standups.log，記錄它寫過的每一篇報告。這意味著下次你執行它時，Claude 會讀取自己的歷史記錄，並能判斷從昨天以來發生了什麼變化。

儲存在 Skill 目錄中的資料在你升級 Skill 時可能會被刪除，所以你應該把資料存在穩定的資料夾中。目前我們提供 ${CLAUDE_PLUGIN_DATA} 作為每個插件的穩定儲存資料夾。

儲存腳本與動態產生程式碼

你能給 Claude 最強大的工具之一就是程式碼。提供給 Claude 腳本和函式庫，讓它把回合花在組合和決定下一步該做什麼，而非重建樣板程式碼。

例如，在你的資料科學 Skill 中，你可能有一組從事件來源擷取資料的函式庫。為了讓 Claude 做複雜分析，你可以給它一組輔助函式。

Claude 就可以即時產生腳本來組合這些功能，對「週二發生了什麼？」這類提示做更進階的分析。

隨選 Hooks

Skills 可以包含只在被呼叫時才啟動的 Hooks，並在會話期間持續生效。用這個功能來放那些你不想一直執行、但有時極度有用的強約束 Hooks。

範例：

• /careful — 透過 PreToolUse 匹配器封鎖 Bash 中的 rm -rf、DROP TABLE、force-push、kubectl delete。只在你知道自己在碰正式環境時才需要，一直開著會讓你抓狂
• /freeze — 封鎖不在特定目錄中的任何 Edit/Write。在除錯時很有用：「我想加日誌但一直不小心改到不相關的東西」

分發 Skills

Skills 最大的好處之一是你可以和團隊其他人分享。

有兩種分享方式：

• 把 Skills 簽入你的 repo（放在 ./.claude/skills 下）
• 製作一個 plugin，利用 Claude Code Plugin Marketplace 讓用戶上傳和安裝插件（詳見文件）

對於在相對少數 repo 中工作的小型團隊，把 Skills 簽入 repo 效果很好。但每個簽入的 Skill 都會稍微增加模型的上下文。隨著規模擴大，內部 Plugin Marketplace 可以讓你分發 Skills，並讓團隊成員自行決定要安裝哪些。

管理 Marketplace

如何決定哪些 Skills 進入 Marketplace？人們怎麼提交？

我們沒有一個集中的團隊來做決定，而是嘗試有機地找到最有用的 Skills。如果你有一個想讓人試用的 Skill，可以上傳到 GitHub 的沙盒資料夾，然後在 Slack 或其他論壇指向它。

一旦一個 Skill 獲得了關注（由 Skill 擁有者自行判斷），他們就可以提交 PR 把它移入 Marketplace。

提醒一下，建立品質不佳或多餘的 Skills 很容易，所以在發布前確保有某種審核機制很重要。

組合 Skills

你可能會想讓 Skills 之間互相依賴。例如，你可能有一個上傳檔案的 Skill，和一個產生 CSV 並上傳的 Skill。這種依賴管理目前還沒有原生內建在 Marketplace 或 Skills 中，但你可以直接用名稱引用其他 Skills，模型會在它們已安裝的情況下呼叫它們。

衡量 Skills

為了了解一個 Skill 的表現，我們使用 PreToolUse Hook 來記錄公司內部的 Skill 使用情況（範例程式碼在這裡）。這讓我們能找到受歡迎的 Skills，或者觸發率低於預期的 Skills。

結語

Skills 是代理 AI 極其強大且靈活的工具，但目前仍處於早期階段，我們都還在摸索如何用好它們。

把這篇文章想成一袋我們見過有效的實用技巧，而非一份權威指南。理解 Skills 最好的方式就是開始動手、實驗，看看什麼對你有用。我們大部分的 Skills 一開始都只有幾行文字和一條陷阱提醒，後來因為大家在 Claude 遇到新的邊界情況時不斷補充，才越來越好。

希望這篇文章對你有幫助，有任何問題歡迎提出。

原文連結：Lessons from Building Claude Code: How We Use Skills
原文作者：Thariq Shihipar（@trq212），Anthropic Claude Code 團隊
翻譯：Fox（狐說八道）