Anthropic 的 Thariq (Claude Code 團隊) 寫了一篇 Lessons from Building Claude Code: How We Use Skills，分享他們內部「上百個 Skills」的實戰心得。蠻有料的一篇，難得看到 Anthropic 自己人講怎麼用自家功能。

編按: 這篇最早是 Thariq 發在 X 上的貼文，後來 Anthropic 把它整理成官方 blog 文章，內容大致相同，官方版多補了幾個具體例子，本文已一併綜合進來。

文章一開頭就澄清一個常見誤解: Skill 不是「就只是一份 markdown 檔案」(just markdown files)。它是一個資料夾，裡面可以放腳本、資產、資料、甚至註冊 hooks。最有意思的 Skills 都是把這個資料夾結構玩出花樣來的。

9 種 Skills 類型

Anthropic 內部把所有 skills 整理過一輪後，發現它們會自然落入幾個固定類別。Thariq 強調: 「最好的 skills 都乾淨地落在某一類，會讓人困惑的那種通常是橫跨好幾類」。這個分類不是定論，但拿來檢查自己組織裡是不是有遺漏的場景蠻好用的。

1. 函式庫與 API 參考 (Library & API Reference)

教 Claude 怎麼正確使用一個函式庫、CLI 或 SDK。可以是內部專屬函式庫，也可以是 Claude 容易寫錯的常見開源套件。通常會附上一堆 reference 程式碼片段，加上一份「踩雷清單 (gotchas)」。

例子: billing-lib (內部計費函式庫的 edge cases)、internal-platform-cli (內部 CLI 的每個子指令範例)、sandbox-proxy (內部 sandbox 網路代理的用法)、frontend-design (讓 Claude 懂你的設計系統)。

2. 產品驗證 (Product Verification)

描述要怎麼測試和驗證程式碼真的有跑起來，通常會搭配 playwright、tmux 這類外部工具。Thariq 特別強調: 驗證類 skills 是 Anthropic 內部量測起來，對 Claude 輸出品質影響最明顯的一類，花一個工程師一週的時間把驗證 skill 做好都是值得的。

技巧包含: 讓 Claude 錄影 (這樣你能看到它到底測了什麼)、在每個步驟強制做程式化的 state 斷言。例子: signup-flow-driver、checkout-verifier、tmux-cli-driver。

3. 資料拉取與分析 (Data Fetching & Analysis)

連到你的資料和監控系統的 skills，會包含拉資料的函式庫、特定 dashboard ID、credentials 等。

例子: funnel-query (告訴 Claude 該 join 哪些事件來看 signup → activation → paid，以及哪張表才有真正的 user_id)、cohort-compare、grafana 和 datadog (datasource UID、cluster 名稱、symptom → dashboard 對照表)。

4. 業務流程與團隊自動化 (Business Process & Team Automation)

把重複工作流程包成一個指令。指令本身通常很單純，但可能依賴其他 skills 或 MCP。Thariq 建議: 把每次執行結果存進 log file，這樣模型可以讀自己的歷史，知道從昨天到今天有什麼變化。

例子: standup-post (彙整 ticket、GitHub 活動、Slack 對話 → 格式化的 standup 貼文，只列差異)、create-<ticket-system>-ticket、weekly-recap。

5. 程式碼鷹架與模板 (Code Scaffolding & Templates)

幫專案產生框架樣板程式。特別適合那種「樣板有自然語言要求、純程式無法完全覆蓋」的場景。

例子: new-<framework>-workflow、new-migration (你的 migration 模板加上常見踩雷點)、create-app (新內部 app 預先接好你的 auth、logging、deploy 設定)。

6. 程式碼品質與審查 (Code Quality & Review)

強制執行組織內的程式碼品質規則，可以包含確定性腳本或工具。可以掛在 hooks 或 GitHub Action 自動跑。

例子: adversarial-review (產生一個全新視角的 subagent 來批評，實作修正、反覆迭代直到只剩雞毛蒜皮的問題)、code-style、testing-practices。

編按: adversarial-review 這個設計小編覺得蠻巧的，用 subagent 強制創造「沒看過先前對話脈絡」的審查視角，避免 Claude 自己稽核自己時的盲點。

7. CI/CD 與部署 (CI/CD & Deployment)

幫忙抓取、推送、部署程式碼。

例子: babysit-pr (盯著 PR → 重試壞掉的 CI → 解 merge conflict → 開啟 auto-merge)、deploy-<service> (build → smoke test → 漸進流量 rollout 配上錯誤率比較 → 發現退化自動 rollback)、cherry-pick-prod。

8. 故障處理手冊 (Runbooks)

接收一個徵狀 (Slack 對話、警報、錯誤特徵)，走完一次跨工具的調查，最後產出結構化報告。

例子: <service>-debugging (把徵狀對應到工具和查詢模式)、oncall-runner (拉警報 → 檢查常見嫌疑犯 → 格式化發現)、log-correlator (給定 request ID，從每個可能碰過它的系統把對應 log 全拉出來)。

9. 基礎設施操作 (Infrastructure Operations)

執行例行維護和操作流程，有些涉及破壞性動作所以需要護欄。讓工程師遵循重要操作的最佳實務。

例子: <resource>-orphans (找孤兒 pod/volume → 貼到 Slack → 等待緩衝期 → 使用者確認 → 階梯式清理)、dependency-management、cost-investigation。

9 個寫 Skill 的關鍵技巧

決定要做哪個 skill 之後，怎麼寫好? Thariq 整理了九個重點:

1. 不要說廢話 (Don’t State the Obvious) Claude 對程式碼和你的專案已經有不少預設見解了。如果你要做的是知識類 skill，要聚焦在那些「會把 Claude 推離預設思路」的資訊。frontend-design 就是經典例子: 它是某位工程師跟客戶迭代出來的，避開像 Inter 字型、紫色漸層這種典型 AI 設計味道。

2. 一定要有 Gotchas 區塊 任何 skill 裡訊號量最高的內容，就是踩雷清單。要從 Claude 用你的 skill 時實際出錯的點累積出來，並隨時間更新。官方版給了三個很有畫面的例子:

  • 「subscriptions 表是 append-only 的，你要的是 version 最高的那一列，不是 created_at 最新的」
  • 「同一個東西在 API gateway 叫 @request_id，到了 billing service 卻叫 trace_id」
  • 「Staging 環境就算 Stripe webhook 沒有真的處理成功，也會回 200」

這種資訊 Claude 靠讀 code 猜不出來，只能靠人把踩過的雷寫下來。

3. 善用檔案系統做漸進揭露 (Progressive Disclosure) Skill 是資料夾不是 markdown，要把整個檔案系統當成 context engineering 的一種形式。最簡單的做法是在主 SKILL.md 裡指向其他檔案 (例如把詳細的 API 簽名拆到 references/api.md)，告訴 Claude 何時去讀。

4. 不要把 Claude 鐵軌化 (Don’t Railroad Claude) Claude 通常會努力遵循你的指令，但因為 skill 是要重複使用的，過度具體的指令會限制它的彈性。給 Claude 它需要的資訊，但留下適應情境的空間。

5. 設計好初次啟動 (Think through the Setup) 有些 skill 需要從使用者那邊拿初始設定。一個好做法是把這些設定存在 skill 目錄的 config.json，沒設好時就讓 agent 主動詢問。要結構化的選擇題，可以指示 Claude 用 AskUserQuestion 工具。

6. Description 欄位是寫給模型看的 這是小編覺得最關鍵的一點。Claude Code 開 session 時會掃所有 skill 的 description 來決定「這個請求需要哪個 skill?」所以 description 不是摘要，是觸發條件描述: 要寫的是「什麼時候該用這個 skill」，不是「這個 skill 在做什麼」。官方版還補了一個實用建議: 把觸發詞直接寫進 description，例如 babysit-pr 這個 skill 就把「babysit」這個詞放進去，使用者一說 babysit 就會觸發。

7. 記憶與資料儲存 Skill 可以有「記憶」: 用 append-only 的 log file、JSON 檔，甚至 SQLite 都行。例如 standup-post 可以維護一份 standups.log，下次 Claude 跑時會讀自己的歷史，判斷昨天到今天有什麼變化。但要存到 ${CLAUDE_PLUGIN_DATA} 這個跨升級的穩定路徑，不要存在 skill 目錄裡 (升級會被砍)。

8. 給 Claude 程式碼 (Store Scripts & Generate Code) 給 Claude 腳本和函式庫，能讓它把 turn 花在「組合」上，而不是重新造輪子。例如資料分析 skill 裡放一組 helper functions，Claude 就能即時生成腳本來組合成「星期二發生了什麼?」這種複雜分析。

9. 隨叫隨到的 Hooks (On-Demand Hooks) Skill 可以註冊 hooks，但只在 skill 被叫起來時才生效，session 結束就取消。這對「我想要強硬意見但不想一直開著」的場景很有用。例如:

  • /careful - 透過 PreToolUse 擋掉 rm -rf、DROP TABLE、force-push、kubectl delete，只在你動到 prod 時才需要
  • /freeze - 擋掉指定目錄外的 Edit/Write，debug 時很有用 (我只想加 log，不要順手「修好」其他不相關的東西)

散布 Skills: Plugin Marketplace 的玄機

Skill 的另一個強項是分享。文章提到兩種做法:

  1. 把 skills 直接 check-in 到 repo 的 .claude/skills/ (適合小團隊跨少數 repo)
  2. 做 plugin marketplace，讓使用者自己挑要裝什麼

關鍵在於: 每個 check-in 的 skill 都會佔模型一點點 context，當組織擴大時 marketplace 會比較合理。

至於 marketplace 怎麼策展? Anthropic 的做法是沒有中央委員會，讓有用的 skill 自然浮現。先丟到 GitHub sandbox 資料夾，Slack 推給人試，等社群有需求後才 PR 進 marketplace。Thariq 提醒一點: 「很容易做出爛或重複的 skill，所以發布前的策展機制很重要」。

還有兩個有趣的細節:

  • Skill 可以互相呼叫: 雖然目前沒有原生的依賴管理，但你可以直接在 skill 裡用名字 reference 另一個 skill，Claude 會在它有裝的情況下 invoke 它
  • 量測 skill 使用情況: Anthropic 用 PreToolUse hook 在公司內部記錄 skill 使用，這樣可以找出「熱門」或「觸發不足」的 skill

還有哪些 Skill 分類觀點?

Thariq 這篇是從 Claude Code 團隊內部使用的角度切九大類。小編順手用 exa 搜了一下，看看別的角度怎麼切。

Anthropic 官方指南 (Building Skills for Claude PDF) 從外部使用者切，分成三大類:

  • Category 1: 文件與資產生成 - 例如 frontend-design、docx、pptx、xlsx
  • Category 2: 工作流程自動化 - 例如 skill-creator
  • Category 3: MCP 增強 - 例如 sentry-code-review (透過 Sentry MCP 自動分析修 bug)

Claude Code 官方文件從內容性質切兩種:

  • Knowledge content - Claude 視情況自動 invoke 的背景知識
  • Task content - 給 Claude 一步步指令做特定動作 (commit、deploy 等)，通常你會用 disable-model-invocation: true 讓它只能手動觸發，避免 Claude 自己決定部署上線

PolySkill 從複雜度切四種: Prompt (純指令)、Tool (指令+函式定義)、Workflow (多步驟)、Composite (組合其他 skills)。

不同分類沒有絕對對錯，看你想解決什麼問題。Thariq 這套 9 類更接近「日常工程組織會碰到哪些重複場景」，對 internal tooling 團隊比較實用; 官方指南那套 3 類更貼近「skill 對外能做什麼」，對寫教材或產品定位比較順。

寫在最後

讀完這篇，最大的收穫不是那 9 個分類本身，而是 Thariq 在結語裡那句話:「我們大多數的 skills 都是從幾行字加一個 gotcha 開始，然後 Claude 撞到新的 edge case，就有人加進去，慢慢變好」。

這跟 ihower 一直在課程強調的「Skill 是活的、要持續迭代」蠻呼應的。不要一開始就追求做出史詩級巨作，先做一個簡單版本上線，讓它先撞牆撞個幾次，再把踩雷點寫進 Gotchas 區塊。Skill 的價值不在初版多完美，而在迭代的累積。

最後也想提醒一個和分類無關但很重要的洞察: skill 是資料夾，不只是 markdown。當你下次想做 skill 時，問自己一個問題:「我除了文字指令，能不能再給 Claude 一些腳本、一些資料、一些 hook?」答案通常是「可以，而且應該要」。