搞不懂Skills？看看Claude Code內部工程師們是怎么玩的

編譯｜冷貓

你還在為你的龍蝦笨笨的而煩惱嗎？

你還在為找不到合適的 Skills 安裝而焦頭爛額嗎？

你還在為網上找到的 Skills 可能不安全而心驚膽戰嗎？

養了這么久龍蝦，是時候開始構建自己的 Skills 了。這時候，一篇來自 Anthropic 團隊的 Skills 秘籍在外網廣為流傳，為想要構建 Skills 的開發者和智能體用戶提供了絕佳的參考資料。

• 博客標題：Lessons from Building Claude Code: How We Use Skills
• 博客鏈接：https://x.com/trq212/status/2033949937936085378

這篇文章來自于 Anthropic 的 Claude Code 團隊工程師，Skills 功能核心參與者 Thariq Shihipar。內容大多是 Anthropic 內部使用 Skills 的實戰經驗和總結。

我們對該博客進行了全文編譯，希望讀者從中獲取關于 Skills 制作、使用和推廣分發相關的經驗。

以下是博客全文：

Skills 已經成為 Claude Code 中使用最廣泛的擴展方式之一。它們靈活、易于創建，也方便分發。

但這種靈活性也帶來了一個問題：很難判斷什么才是最佳實踐。什么類型的 Skills 值得開發？寫出一個優秀 Skill 的秘訣是什么？又應該在什么時候將它們分享給他人？

在 Anthropic 內部，我們已經在 Claude Code 中廣泛使用 Skills，目前有數百個 Skills 在實際運行中。

這些是我們在使用 Skills 來加速開發過程中總結的一些經驗。

什么是 Skills ？

如果你剛接觸 Skills，建議先閱讀我們的文檔：

相關鏈接：https://code.claude.com/docs/en/skills

本文默認你已經對 Skills 有一定了解。

我們經常聽到一個常見的誤解：認為 Skills「只是一些 Markdown 文件」。但實際上，Skills 最有趣的地方在于 —— 它們并不僅僅是文本文件，而是一個文件夾，里面可以包含腳本、資源、數據等內容，供智能體進行發現、探索和操作。

在 Claude Code 中，Skills 還具備多種配置選項，包括注冊動態鉤子（hooks）等。

相關鏈接：https://code.claude.com/docs/en/skills#frontmatter-reference

我們發現，一些最有意思的 Skills，正是通過巧妙利用這些配置選項和文件結構來實現的。

Skills 類型

在整理我們所有 Skills 之后，我們發現它們大致可以分為幾個常見的類別。

最好的 Skills 通常能夠清晰地歸類到一個類別中，而那些更為復雜或難以理解的 Skills，則可能跨越多個類別。這并不是一個權威的分類列表，但它為你判斷在你的組織中是否缺少某些類型的 Skills 提供了一個很好的思路。

1. 庫與 API 參考

這些 Skills 解釋如何正確使用庫、CLI 或 SDK。這些 Skills 可以是針對內部庫，也可以是針對 Claude Code 在使用常見庫時遇到困難的庫。它們通常包含一組參考代碼片段，以及 Claude 在編寫腳本時應避免的一些常見問題。

示例：

• billing-lib — 你的內部賬單庫：邊緣情況、常見陷阱等
• internal-platform-cli — 你內部 CLI 包裝器的每個子命令，并提供何時使用它們的示例
• frontend-design — 使 Claude 更好地理解你的設計系統

2. 產品驗證

這些 Skills 描述了如何測試或驗證代碼是否正常工作。它們通常與外部工具（如 Playwright、tmux 等）配合使用，以進行驗證。

驗證 Skills 對確保 Claude 輸出正確非常有用。可能值得讓工程師花一周時間，專注于提高驗證 Skills 的質量。

考慮使用技術，例如讓 Claude 記錄它的輸出視頻，這樣你就可以準確看到它測試了什么，或者在每個步驟上強制進行狀態的程序化斷言。這些通常通過在 Skills 中包含各種腳本來實現。

示例：

• signup-flow-driver — 在無頭瀏覽器中運行注冊 → 郵件驗證 → 入職流程，并在每個步驟上進行狀態斷言
• checkout-verifier — 使用 Stripe 測試卡驅動結賬界面，驗證發票是否真正落入正確的狀態
• tmux-cli-driver — 用于需要 TTY 的交互式 CLI 測試

3. 數據抓取與分析

這些 Skills 連接到你的數據和監控系統。這些 Skills 可能包括庫，用于通過憑證、特定的儀表盤 ID 等抓取數據，以及常見工作流或獲取數據的方式說明。

示例：

• funnel-query — "我需要哪些事件來查看注冊 → 激活 → 付費" 以及實際包含標準 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 與可組合的腳本結合使用。它們在你的腳手架有自然語言要求，而這些要求無法僅通過代碼覆蓋時尤為有用。

示例：

• new--workflow — 使用你的注釋腳手架一個新的服務 / 工作流 / 處理器
• new-migration — 你的遷移文件模板以及常見的坑
• create-app — 新的內部應用，預先配置你的認證、日志記錄和部署

6. 代碼質量與審核

這些 Skills 強制執行你組織中的代碼質量并幫助審查代碼。它們可以包括確定性的腳本或工具，以確保最大程度的穩健性。你可能希望將這些 Skills 自動運行，作為鉤子的一部分或 GitHub Actions 中的一部分。

示例：

• adversarial-review — 啟動一個新鮮眼光的子智能體進行批評，實施修復，迭代直到反饋降級為小瑕疵
• code-style — 強制執行代碼風格，特別是 Claude 默認處理不好的一些風格
• testing-practices — 關于如何編寫測試以及需要測試什么的說明

7. CI/CD 與部署

這些 Skills 幫助你在代碼庫內獲取、推送和部署代碼。這些 Skills 可能引用其他 Skills 以收集數據。

示例：

• babysit-pr — 監控 PR → 重試不穩定的 CI → 解決合并沖突 → 啟用自動合并
• deploy- — 構建 → 煙霧測試 → 漸進式流量發布與錯誤率比較 → 回滾回退
• cherry-pick-prod — 隔離工作樹 → 衍生選擇 → 沖突解決 → 帶模板的 PR

8. 運行手冊

這些 Skills 通過癥狀（如 Slack 線程、警報或錯誤簽名），進行多工具調查，并生成結構化報告。

示例：

• -debugging — 映射癥狀 → 工具 → 查詢模式，適用于你最高流量的服務
• oncall-runner — 獲取警報 → 檢查常見問題 → 格式化結果
• log-correlator — 給定請求 ID，從可能涉及的所有系統中提取匹配的日志

9. 基礎設施操作

這些 Skills 執行常規的維護和操作程序，其中一些涉及需要有防護措施的破壞性操作。它們使工程師更容易遵循最佳實踐，在關鍵操作中避免出錯。

示例：

• -orphans — 查找孤立的 pods/volumes → 發布到 Slack → 浸泡期 → 用戶確認 → 級聯清理
• dependency-management — 你組織的依賴審批工作流
• cost-investigation — "為什么我們的存儲 / 出站流量賬單突然飆升"，并提供具體的存儲桶和查詢模式

制作 Skills 的技巧

一旦你決定要制作某個 Skills，如何編寫它呢？以下是我們總結的一些最佳實踐、技巧和竅門。

我們最近還發布了 Skill Creator，使得在 Claude Code 中創建 Skills 變得更加容易。

相關鏈接：https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills

不要陳述顯而易見的內容

Claude Code 已經了解很多關于你的代碼庫的信息，也了解很多編碼的基礎知識，包括許多默認的觀點。如果你發布的 Skills 主要是關于知識的，嘗試專注于那些能夠讓 Claude 脫離正常思維方式的信息。

示例：

前端設計 Skills就是一個很好的例子 —— 它是由 Anthropic 的一位工程師通過與客戶反復迭代，旨在提升 Claude 的設計品味，避免使用經典的設計模式（例如 Inter 字體和紫色漸變）。

相關鏈接：https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md

構建陷阱部分

在任何 Skills 中，Gotchas（常見陷阱）部分是最有價值的內容。這些部分應該基于 Claude 在使用 Skills 時遇到的常見失敗點來構建。理想情況下，你應該隨著時間的推移更新你的 Skills，捕捉這些常見問題，以確保 Skills 的有效性和準確性。

使用文件系統和漸進式披露

正如我們之前提到的，Skills 是一個文件夾，而不僅僅是一個 Markdown 文件。你應該將整個文件系統視為一種上下文工程和漸進式披露的方式。告訴 Claude 你的 Skills 包含哪些文件，它將在適當的時候讀取它們。

漸進式披露的最簡單形式是指向其他 Markdown 文件供 Claude 使用。例如，你可以將詳細的函數簽名和使用示例分離到 references/api.md 中。

另一個例子：如果你的最終輸出是一個 Markdown 文件，你可以在 assets/ 文件夾中包括一個模板文件供 Claude 復制和使用。

你可以有多個文件夾來存儲參考資料、腳本、示例等，這些都有助于 Claude 更有效地工作。

避免「束縛」 Claude

Claude 通常會盡量遵循你的指示，然而由于 Skills 的高度可復用性，你需要小心不要讓指令過于具體。給予 Claude 必要的信息，同時也要留給它一定的靈活性以適應不同的情況。

例如：

思考 Skills 的設置

有些 Skills 可能需要用戶提供上下文信息來完成設置。例如，如果你在制作一個將站立會議內容發布到 Slack 的 Skills，你可能希望 Claude 詢問要發布到哪個 Slack 頻道。

一種良好的做法是將這些設置的信息存儲在 Skills 目錄中的 config.json 文件中，如上例所示。如果配置尚未設置，智能體可以提示用戶提供必要的信息。

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

描述字段是給模型的

當 Claude Code 啟動一個會話時，它會構建一個包含每個可用 Skills 及其描述的列表。這份列表是 Claude 用來決定「是否有 Skills 能解決這個請求？」的依據。因此，描述字段并不是 Skills 的總結，而是描述何時觸發這個 Skills 的場景。

記憶與存儲數據

有些 Skills 可以通過在其內部存儲數據來實現一定的記憶功能。你可以將數據存儲在簡單的附加文本日志文件、JSON 文件，或者更復雜的 SQLite 數據庫中。

例如：

一個 standup-post Skills 可能會保留一個 standups.log，記錄每次發布的內容。這意味著下次運行時，Claude 可以讀取自己的歷史記錄，并能夠檢測自昨天以來的變化。

需要注意的是，存儲在 Skills 目錄中的數據可能在 Skills 升級時被刪除，因此你應當將數據存儲在一個穩定的文件夾中。到目前為止，我們為每個插件提供了 ${CLAUDE_PLUGIN_DATA} 作為穩定存儲數據的文件夾。

存儲腳本與生成代碼

提供代碼是給 Claude 最強大的工具之一。將腳本和庫交給 Claude，可以讓它專注于組合和決策，而不是重新構建基礎代碼。

例如：

在你的數據科學 Skills 中，你可能有一組用于從事件源抓取數據的函數庫。為了讓 Claude 執行復雜的分析，你可以為它提供一套像這樣的幫助函數：

Claude 然后可以動態生成腳本，利用這些功能組合來執行更高級的分析，比如處理類似 「星期二發生了什么？」 這樣的提示。

按需鉤子（On Demand Hooks）

Skills 可以包括僅在 Skills 被調用時激活的鉤子，并且這些鉤子的作用僅持續到會話結束。這對于一些有強烈意見、但并不希望一直運行的鉤子特別有用，它們在某些情況下會非常有價值。

例如：

• /careful— 通過 Bash 中的PreToolUse匹配器阻止 rm -rf、DROP TABLE、force-push、kubectl delete 等危險操作。你只希望在知道自己正在操作生產環境時才啟用它，常開會讓你瘋狂。
• /freeze— 阻止在特定目錄外的任何編輯 / 寫入操作。非常有用，特別是當你想確保只有在特定文件夾中進行更改時才執行代碼時。
• 調試時：「我想加日志，但我總是無意中‘修復’無關的內容。」 使用按需鉤子，可以防止在不需要的情況下影響其他文件或代碼片段。

這些鉤子可以根據實際需要進行觸發，而不是始終保持啟用狀態，從而避免不必要的干擾，同時在需要時提供強有力的功能。

Skills 分發

Skills 的最大優勢之一是，你可以將它們與團隊中的其他成員共享。

你有兩種方式可以將 Skills 分享給別人：

1. 將 Skills 檢查到你的代碼庫中（在 ./.claude/skills 下）。

2. 創建插件并擁有一個Claude Code Plugin市場，用戶可以在其中上傳和安裝插件（有關更多信息，請參閱文檔 https://code.claude.com/docs/en/plugin-marketplaces）。

對于在相對較少的代碼庫中工作的較小團隊，將 Skills 檢查到代碼庫中是一個不錯的選擇。但每個被檢查進來的 Skills 都會增加一些模型的上下文。當團隊規模擴大時，內部插件市場可以幫助你分發 Skills，并讓團隊成員決定哪些 Skills 需要安裝。

管理市場

如何決定哪些 Skills 進入市場？人們如何提交它們？

我們沒有一個集中式的團隊來做決定；相反，我們嘗試通過自然的方式找到最有用的 Skills。如果你有一個 Skills 想讓大家嘗試，你可以將它上傳到 GitHub 的沙箱文件夾，并通過 Slack 或其他論壇將鏈接分享給大家。

當一個 Skills 獲得一定的關注度（由 Skills 擁有者決定）后，他們可以提交一個 PR，將其移入市場。

警告：創建不必要的或冗余的 Skills 是非常容易的，因此在發布之前，確保你有一個篩選和策劃的方法非常重要。

組合 Skills

你可能希望有一些 Skills 相互依賴。例如，你可能有一個文件上傳 Skills，它上傳文件；還有一個 CSV 生成 Skills，它生成 CSV 并上傳文件。這類依賴管理目前在市場或 Skills 中并沒有內建功能，但你可以直接通過名稱引用其他 Skills，如果它們已被安裝，模型會調用它們。

衡量 Skills 的效果

為了了解一個 Skills 的表現，我們使用了PreToolUse鉤子，允許我們記錄公司內 Skills 的使用情況（代碼鏈接：https://gist.github.com/ThariqS/24defad423d701746e23dc19aace4de5）。

這意味著我們可以發現哪些 Skills 比較受歡迎，哪些 Skills 的觸發率低于我們的預期。

結論

Skills 是極其強大且靈活的智能體工具，但目前仍處于早期階段，我們還在不斷摸索如何最好地使用它們。

可以將這篇文章看作是我們在使用過程中積累的一些有用提示，而非權威指南。理解 Skills 的最佳方式是開始實踐，進行實驗，看看什么最適合你。

我們的大多數 Skills 最初只是一行代碼和一個「Gotcha」，隨著 Claude 遇到新的邊界情況，大家會不斷進行完善。