Anthropic 內部怎麼用 Claude Code Skills？讀完這篇我重新整理了自己的 skill

我在自己的 Next.js 專案裡有寫幾個 Claude Code skill——一個幫我 scaffold 新 component、一個跑 migration、一個做 code review。但說實話，寫法一直很隨意——需要什麼就加什麼，一個 SKILL.md 打天下，從來沒認真想過「什麼樣的 skill 才是好的 skill」。

直到看了 Anthropic 的 Thariq 寫的 Lessons from Building Claude Code: How We Use Skills。他們內部有幾百個 skill 在跑，這篇文章把這些經驗整理成了分類方式、寫作技巧、和分發策略。看完之後我才發現，自己根本只用到了 skill 能力的一小部分。

TL;DR

Skill 不是「一個 markdown 檔案」，是一個資料夾，可以放 script、資料、範例、template
Anthropic 內部把 skill 分成 9 大類，從 API reference 到 runbook 都有
寫 skill 最重要的部分是 Gotchas section——記錄 Claude 會踩的坑
不要把 Claude 已經知道的東西寫進去，專注在「讓它跳出預設思維」的資訊
Progressive disclosure 很重要——不要一口氣塞太多 context，讓 Claude 自己去讀需要的檔案

1. Skill 是資料夾，不是檔案

這是我看完之後印象最深的一點。

之前我寫 skill 就是一個 SKILL.md，裡面塞一大堆 instruction。但 Thariq 說的是，整個資料夾都是 skill 的一部分——你可以放 reference 文件、script、template、config，然後在 SKILL.md 裡面告訴 Claude 這些檔案在哪，它會在適當的時機自己去讀。

這其實就是 context engineering 的概念：與其一次把所有東西塞進 prompt，不如讓 agent 自己決定什麼時候需要什麼資訊。

比方說，我有一個幫忙做 database migration 的 skill，之前就是一個 SKILL.md 寫著「用 Drizzle ORM 跑 migration」。但其實可以做得更多——放一個 references/ 資料夾記錄常見的 schema change pattern、一個 scripts/ 資料夾放 migration 前後的 validation script、一個 templates/ 放 migration file 的 boilerplate。Claude 在跑 migration 的時候會根據需要自己去讀，而不是一開始就把所有東西塞進 context。

2. 九大類 Skill 分類

Thariq 把他們內部所有的 skill 分成了 9 類。我覺得這個分類本身就很有價值，因為它可以幫你想到「我的工作流裡還缺什麼 skill」：

(1) Library & API Reference

教 Claude 怎麼用你的內部 library 或 Claude 不太熟的 API。重點在 edge case 跟 gotchas。

(2) Product Verification

描述怎麼測試和驗證 code 是否正常。通常搭配 playwright、tmux 之類的工具。Thariq 甚至說「值得讓一個工程師花一整個禮拜專門做好 verification skill」。

(3) Data Fetching & Analysis

連接你的 data stack，放 credential、dashboard ID、常用 query pattern。

(4) Business Process & Team Automation

自動化重複性工作流——發 standup、建 ticket、寫 weekly recap。

(5) Code Scaffolding & Templates

生成 boilerplate。特別適合那種有很多 natural language 要求、純 code generator 搞不定的 scaffolding。

(6) Code Quality & Review

Code style、testing practice、adversarial review。可以搭配 hook 或 GitHub Action 自動跑。

(7) CI/CD & Deployment

Build、test、deploy、rollback 的自動化流程。

(8) Runbooks

從症狀開始（Slack thread、alert、error signature），走過完整的調查流程，產出結構化報告。

(9) Infrastructure Operations

維運操作——清理 orphaned resources、管理 dependency、調查費用暴增。

看完這 9 類之後我發現，自己目前有的 skill 主要集中在第 1 類（reference）跟第 5 類（scaffolding），其他類幾乎都沒有。特別是 Verification 和 Runbook 這兩類，感覺是能大幅提升開發效率但很容易被忽略的。

3. 寫 Skill 的實戰技巧

不要寫廢話

Claude 已經知道很多東西了。你不需要教它 React 的基本用法或 Git 的指令。Skill 應該專注在讓 Claude 跳出預設行為的資訊。

文章裡舉了 frontend design skill 的例子——它的目的不是教 Claude 寫 CSS，而是避免 Claude 預設會用的 Inter 字體和紫色漸層（如果你用過 Claude 生成 UI，你一定懂這個痛 (╯°□°)╯︵ ┻━┻）。

Gotchas Section 是靈魂

每個 skill 裡面最有價值的部分。記錄 Claude 使用這個 skill 時容易犯的錯，然後隨著時間不斷補充。

這跟我自己的經驗完全一致。比如我的 migration skill 後來就加了一條 gotcha：「Drizzle 的 push 指令在有 enum 變更的時候會 silently fail，要用 generate + migrate 才安全」。這種你不踩不會知道的東西，寫進 skill 之後 Claude 就不會再犯了。

Progressive Disclosure

不要把所有東西塞在一個 markdown 裡面。善用資料夾結構：

my-skill/
├── SKILL.md                    # 主要指令，概覽和流程
├── references/
│   ├── api.md                  # 詳細 API signature
│   └── common-patterns.md      # 常見使用模式
├── scripts/
│   └── validate.sh             # 驗證 script
├── templates/
│   └── component.tsx           # 範本檔案
└── examples/
    ├── good-example.md         # 好的範例
    └── bad-example.md          # 反面教材

在 SKILL.md 裡面告訴 Claude 這些檔案的用途，它會在需要的時候自己去讀。這比一口氣塞 5000 字的 instruction 好太多了。

不要 Railroading

給 Claude 足夠的資訊，但保留彈性讓它適應不同情境。如果你的指令太死，skill 的可重用性會大幅降低。

Description 是給 Model 看的

Skill 的 description 欄位不是給人看的摘要，是 Claude 用來決定「要不要觸發這個 skill」的 trigger。寫的時候要站在 model 的角度想：什麼樣的 user request 應該觸發這個 skill？

4. 我覺得最有啟發的幾個概念

Skill 裡面存資料

Skill 可以有自己的 memory。比如 standup skill 可以維護一個 standups.log，每次執行都 append，下次跑的時候 Claude 就可以讀到之前的歷史，知道什麼東西變了。

這讓我想到可以在 deploy skill 裡面存一個 deploy-history.json，記錄每次部署的版本、時間、有沒有 rollback。下次跑的時候 Claude 就知道上次部署出了什麼問題，可以提前警告你。不過要注意用 ${CLAUDE_PLUGIN_DATA} 存，不然更新 skill 的時候資料會被刪掉。

On-Demand Hooks

Skill 可以自帶 hook，只在 skill 被觸發的時候才生效。文章裡面舉了兩個很酷的例子：

/careful — 在碰 production 的時候才啟用，會擋掉 rm -rf、DROP TABLE、force-push、kubectl delete 這種危險操作
/freeze — 凍結特定目錄外的檔案修改，debug 的時候防止 Claude 亂改不相關的東西

這個我之前完全不知道可以這樣做，感覺超實用。

用 Script 擴展能力

與其讓 Claude 從頭寫所有的 code，不如在 skill 裡面放好 helper function 跟 script，讓 Claude 專注在組合而不是建構。文章裡的 data science 例子就是這樣——先寫好 fetch data 的 library，Claude 只要組合這些 function 就能做複雜分析。

5. 怎麼運用在日常開發中

看完之後我列了幾個自己想做的事情：

短期（這週就可以做）

改造 migration skill：加 references/ 放 schema change pattern、加 scripts/ 放 pre/post migration validation、加 gotchas section 記錄踩過的坑
寫一個 verification skill：目前改完 UI 都是手動跑 next dev 然後自己看，可以做一個 skill 讓 Claude 用 agent browser 自動檢查關鍵頁面——form submit 有沒有壞、responsive 有沒有跑版、console 有沒有 error

中期（有空的時候）

API endpoint scaffolding skill：每次加新的 API route 都要手動建檔案、寫 validation schema、加 error handling、寫 test，可以做成一個 new-api skill 一次搞定
PR review skill：提 PR 之前自動跑一輪——type check、lint、test coverage 有沒有掉、有沒有不小心 commit .env、有沒有忘記加 migration

長期思考

在工作專案導入 skill 文化：把 team 裡常見的 runbook 和 debugging 流程做成 skill。最有價值的是那些「有經驗的人才知道的」debugging 路徑——哪個 error 要去看哪個 dashboard、哪個 log 裡面什麼 pattern 代表什麼問題
建立內部 skill marketplace：Thariq 說他們用一個 sandbox folder 讓人先試用，有人用了覺得好才正式上架。這個 organic 的策略比由上而下強推好多了

結語

Skill 這個功能老實說不是什麼黑科技——就是 markdown + 資料夾結構 + 一些 config。但 Anthropic 內部幾百個 skill 的使用經驗告訴我們，最有效的 agent customization 往往不是什麼花俏的 prompt engineering，而是把你的 domain knowledge 結構化。

你的 team 裡一定有很多「只有資深工程師才知道」的東西——某個 API 的 quirk、某個 deploy 流程的順序、某個 error 的 root cause 其實不是表面看到的那樣。這些東西以前可能寫在 wiki 裡（然後沒人看），或者存在某個人的腦袋裡。

現在你可以把它們變成 skill，讓 Claude 幫你記住、幫你執行、幫你傳承。

我覺得這才是 skill 最大的價值——不是讓 AI 更聰明，而是讓 team 的 collective knowledge 可以被 AI 存取和運用 (´・ω・`)

原文：Lessons from Building Claude Code: How We Use Skills by Thariq (@trq212)