來源：市場資訊

（來源：macrozheng）

不知道你有沒有這種體驗，興沖沖給 Claude Code 裝了一堆 skill，或者自己照著教程寫了幾個，結果用了一個月，Claude 壓根沒主動調用過幾次。

skill 就這么安靜地躺在目錄里，像極了你收藏夾里那些「以后一定看」的文章。

問題出在哪？是 skill 這個機制不行嗎？

還真不是。

Anthropic 內部光是活躍使用的 skill 就有幾百個，他們前幾天剛發了一篇博客，把這幾百個 skill 沉淀下來的經驗一次性全交代了：什么樣的 skill 值得做、怎么寫 Claude 才會用、團隊怎么共享、甚至怎么給 skill 做數據埋點。

我把這篇博客整篇扒了一遍，整理成 7 個問題：

• Q1：「skill 不就是一份 markdown 嗎？」這可能是最大的誤解

• Q2：Anthropic 內部幾百個 skill，最后只歸成了 9 類

• Q3：為什么你寫的 skill Claude 從來不觸發？

• Q4：一個 skill 里含金量最高的部分，是「坑點清單」

• Q5：skill 還能有記憶、帶腳本、掛臨時 hook？

• Q6：skill 怎么從你的本地走向全團隊？

• Q7：怎么知道一個 skill 到底有沒有人用？

我們一個一個來說。

Q1：「skill 不就是一份 markdown 嗎？」這可能是最大的誤解

先拋個問題：如果讓你現在描述一下什么是 skill，你會怎么說？

我猜不少人的答案是：「就是一個寫了操作步驟的 markdown 文件，Claude 需要的時候會去讀?！?/p>

Anthropic 在博客里點名說了，這是他們聽到的關于 skill 最常見的誤解。

那 skill 到底是什么？官方的定義是：一個文件夾。里面除了那份 SKILL.md，還可以放腳本、參考資料、數據文件、輸出模板，Claude 能自己發現、探索和使用這些東西。

一個五臟俱全的 skill 長什么樣？拿一個部署服務的 skill 舉例，典型的目錄結構是這樣的：

deploy-service/├── SKILL.md               # 唯一必需：何時用我 + 操作指引 + 坑點清單├── references/            # 參考資料，正文放不下的細節放這里│   ├── api.md             # 部署平臺 API 的詳細參數和示例│   └── troubleshooting.md # 部署失敗時的排查手冊├── scripts/               # 現成的可執行腳本│   ├── smoke_test.sh      # 冒煙測試│   └── rollback.sh        # 一鍵回滾└── assets/                # 輸出模板    └── release_note.md    # 發布報告的固定格式

整個文件夾里只有 SKILL.md 是必需的：文件開頭一段 frontmatter 寫名字和 description，正文寫操作指引。references/、scripts/、assets/ 都是可選的，連名字都不是強制的，按你的需要隨便加。

更妙的是，這些子文件不會一股腦塞給 Claude，而是它干活干到哪一步、需要什么材料，才自己去文件夾里翻什么。這個機制 Q3 會專門拆。

skill 文件夾結構示意圖

打個比方。markdown 文件版的 skill，相當于你給新同事發了一條微信：「部署流程是先這樣再那樣」。而文件夾版的 skill，相當于你給他一個工位：桌上有操作手冊，抽屜里有現成的工具，墻上還貼著前任留下的「這臺打印機會卡紙，要先按兩下」的便利貼。

哪個更能讓新同事快速干活，不用我多說了吧。

而且在 Claude Code 里，skill 還有一堆配置項可以玩，比如綁定特定的觸發條件、注冊只在 skill 運行期間生效的動態 hook（這個 Q5 細說）。

官方觀察下來，內部效果最好的那批 skill，恰恰都是把文件夾結構和配置項用足了的。只寫一份 markdown 的 skill，相當于只用了這個機制十分之一的能力。

微信消息 vs 完整工位對比圖

所以從今天起，請把對 skill 的認知從「一份說明文檔」升級成「一個裝備齊全的工具箱」。后面 6 個問題，全部建立在這個認知之上。

skill 是文件夾，不是文件。這是用好它的第一步。

Q2：Anthropic 內部幾百個 skill，最后只歸成了 9 類

認知擺正了，下一個問題馬上就來：到底什么樣的事值得做成 skill？

這個問題特別實際。skill 寫起來不難，難的是不知道往哪個方向使勁，寫了一堆沒用的，真正高頻的痛點反而沒覆蓋。

Anthropic 干了一件很值錢的事：他們把內部幾百個 skill 全部拉出來做了一次歸類，發現這些 skill 自然聚成了 9 類。

類別

干什么的

例子

庫和 API 參考

教 Claude 正確使用某個內部庫或 CLI

內部計費庫的邊界情況和坑

產品驗證

教 Claude 怎么測試自己寫的代碼

用無頭瀏覽器跑通注冊流程并逐步斷言

數據查詢分析

連接數據和監控系統

該 join 哪些表才能看到轉化漏斗

業務流程自動化

把重復工作流壓成一條命令

自動聚合工單和 PR 生成站會日報

代碼腳手架

按團隊規范生成樣板代碼

新建一個預接好鑒權和日志的內部應用

代碼質量與審查

在組織內強制執行代碼質量

派一個全新視角的子 agent 做對抗式審查

CI/CD 與部署

拉取、推送、部署代碼

盯著 PR 重試不穩定的 CI、解決沖突

Runbook 排障手冊

從一個報警癥狀出發做多工具排查

給一個請求 ID，把所有系統的相關日志拉齊

基礎設施運維

帶護欄的例行維護操作

清理孤兒資源前先發 Slack 等人工確認

九大類 skill 全景圖

這張分類表怎么用？官方給了一個判斷標準：最好的 skill 干干凈凈落在某一類里；那些想一次干太多事、橫跨好幾類的 skill，反而會把 agent 搞糊涂。

你可以拿自己的 skill 庫對著這 9 類掃一遍，馬上能看出兩件事：哪些 skill 越界了該拆，哪些類別還是空白該補。

那如果 9 類只能先做一類，從哪類下手？

官方在這里給出了全文最擲地有聲的一個結論：驗證類 skill 是內部實測對 Claude 輸出質量提升最明顯的一類。原話甚至說到這個程度：值得專門讓一個工程師花一整周，什么都不干，就把驗證類 skill 打磨到極致。

九大類價值排序示意圖

為什么是驗證類？

你想啊，Claude 寫代碼的能力已經夠強了，真正拉開差距的是它有沒有辦法確認自己寫的東西是對的。沒有驗證手段，它就只能「我覺得應該沒問題」；有了驗證 skill，它能開個無頭瀏覽器把注冊、郵箱驗證、引導頁一步步跑完，每一步都斷言狀態，甚至錄一段視頻給你看它到底測了什么。

一個會自己驗收的 Claude 和一個只會交作業的 Claude，干活質量完全是兩個物種。

先別急著寫一堆 skill，把「讓 Claude 自己驗證工作成果」這一件事做好，回報最大。

Q3：為什么你寫的 skill Claude 從來不觸發？

好，分類清楚了，skill 也寫了，新問題來了：為什么 Claude 就是不用？

要回答這個問題，得先搞清楚一件事：Claude 是怎么知道「現在該用哪個 skill」的？

肯定有不少人以為，Claude 每次都會把所有 skill 的全文讀一遍，然后挑一個合適的。要真是這樣，裝 50 個 skill，context 當場就被吃光了。

實際的機制聰明得多。我們先講原理，再看源碼。

會話啟動的時候，Claude Code 會把所有可用 skill 收集起來，但只取每個 skill 的名字和 description，拼成一張清單注入 context。Claude 平時看到的就只有這張「目錄頁」。等它判斷某個任務匹配上了某個 skill，才會發起調用，這時候 SKILL.md 的全文才被加載進對話。

這套機制有個專門的名字，叫漸進式披露（Progressive Disclosure）：平時只給目錄，用到了才給正文。

漸進式披露圖書館類比圖

明白了這個機制，「為什么不觸發」的答案就浮出來了：Claude 決定用不用你的 skill，唯一的依據就是那一行 description。

它沒讀過你的正文，不知道你內容寫得多用心。description 沒寫好，正文寫出花來也是白搭。

這就是官方在博客里專門強調的一條：description 不是寫給人看的摘要，是寫給模型看的觸發條件?！笌椭幚頂祿煜嚓P工作」這種寫法就是典型的人類視角摘要；模型視角的寫法是「當用戶要寫數據庫遷移、修改表結構、或者遇到 migration 報錯時使用」。

description 好壞對比圖

講完原理，我去源碼里取了證，結果發現真實情況比博客說的還要苛刻。

skill 清單注入 context 是有預算的，而且預算緊得嚇人：

export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01export const MAX_LISTING_DESC_CHARS = 250

這段代碼在 src/tools/SkillTool/prompt.ts，兩個常量翻譯成人話：整張 skill 清單只允許占用 context 窗口的 1%；單個 skill 在清單里的描述最多 250 個字符。

250 個字符之后會發生什么？源碼里寫得明明白白：

return desc.length > MAX_LISTING_DESC_CHARS  ? desc.slice(0, MAX_LISTING_DESC_CHARS - 1) + '…'  : desc

同樣在 src/tools/SkillTool/prompt.ts 里，超出 250 字符的部分直接被砍掉，換成一個省略號。你在 description 第 300 個字符處寫的精妙觸發條件，模型從頭到尾就沒見過。

更狠的還在后面。如果你裝的 skill 太多，把那 1% 的預算擠爆了，Claude Code 會先按比例壓縮所有 description；要是還裝不下，就直接降級成只顯示名字、一個字描述都不留的模式。

skill 清單預算擠壓示意圖

這下「裝了一堆 skill 反而都不觸發」這個怪現象就完全說通了：裝得越多，每個 skill 能留在 Claude 眼前的信息就越少，最后大家一起變成一排只有名字的啞巴。

skill 不是收藏品，貴精不貴多。

那調用之后，全文是怎么加載的？源碼里這個加載動作是「懶加載」的，只有 skill 真被調用時才執行，而且會在正文前面拼一行很關鍵的信息：

async getPromptForCommand(args, toolUseContext) {  let finalContent = baseDir    ? `Base directory for this skill: ${baseDir}\n\n${markdownContent}`    : markdownContent

這段在 src/skills/loadSkillsDir.ts，它在 SKILL.md 全文的最前面加了一句「這個 skill 的根目錄在哪里」。

為什么要加這句？這正好解釋了 Q1 說的文件夾機制怎么落地：references/、scripts/ 這些文件夾里的東西，系統從頭到尾都不會自動加載，是 Claude 拿到根目錄地址之后，按 SKILL.md 里的指引，自己用讀文件的工具一個個去取的。

skill 全文加載時序圖

所以漸進式披露其實有三層：平時只有 description，調用時才有 SKILL.md 全文，正文里提到的參考文件等 Claude 真需要了才會去讀。一層比一層深，每一層都只在必要時打開。

漸進式披露三層結構圖

description 的前 250 個字符，決定了你的 skill 是工具還是擺設。

Q4：一個 skill 里含金量最高的部分，是「坑點清單」

觸發問題解決了，Claude 終于肯打開你的 skill 了。下一個問題：正文該寫什么？

先做個小測試。下面兩條內容，哪條更值得寫進 skill？

第一條：「寫完代碼后要運行測試，確保所有用例通過。」

第二條：「subscriptions 表是只追加不修改的，你要找的那行記錄是 version 最大的那條，不是 created_at 最新的那條。」

答案是第二條，而且不是「略好一點」，是一個天上一個地下。

第一條犯了官方點名的大忌：陳述顯而易見的事（don't state the obvious）。Claude 本來就會寫代碼、本來就會跑測試，你把它默認就會做的事再寫一遍，等于往 context 里灌純噪音，一點增量信息都沒有。

官方給的判斷標準很直接：如果你的 skill 主要是傳授知識，那就只寫能把 Claude 推離默認思路的信息。

顯而易見 vs 增量信息篩子示意圖

他們自己有個現成的例子：官方那個前端設計 skill，整篇沒教 Claude 怎么寫 CSS（它會），而是專門列了一堆「不要做」：不要張口就用 Inter 字體，不要動不動紫色漸變。全是沖著 Claude 的默認審美去糾偏的。

那第二條強在哪？它屬于官方說的整個 skill 里信號最強的內容：Gotchas，坑點清單。

什么樣的內容算坑點？除了上面那條 subscriptions 表的例子，博客里還給了兩個真實例子，感受一下：

「這個字段在 API 網關里叫 @request_id，在計費服務里叫 trace_id，它們是同一個值?！?/p>

「staging 環境就算 Stripe 的回調沒真正處理，也會返回 200，真實狀態要去 payment_events 表里查?！?/p>

發現共同點沒有？這些信息有一個共同特征：Claude 靠讀代碼永遠推斷不出來，只有踩過坑的人才知道。這正是它信號強的原因，每一條都在為 Claude 排掉一個它必然會踩的雷。

坑點清單價值示意圖

而且坑點清單不是一次寫完的，官方的玩法是持續攢：每次 Claude 用這個 skill 又栽進一個新坑，就回頭把這個坑補進去。skill 就這樣越用越準。

不過正文也不是寫得越細越好，這里有個度要把握。官方專門提醒了一個反方向的坑，叫別把 Claude 鎖死在軌道上（avoid railroading）。

Claude 對指令的服從度是很高的，你把步驟寫得太死，它遇到指令沒覆蓋的情況就容易僵在軌道上硬開，明明該隨機應變的地方也不敢變。正確的姿勢是：把它需要的信息給足，把怎么走的自由留給它。

鐵軌 vs 導航對比圖

skill 正文的黃金法則：只寫 Claude 推斷不出來的，刪掉它本來就會的。

Q5：skill 還能有記憶、帶腳本、掛臨時 hook？

把 Q4 的內功練好，你的 skill 已經能打了。這一節說三個高階玩法，全部來自 Anthropic 內部的實戰，一個比一個超出「skill 就是文檔」的想象。

玩法一：給 skill 裝記憶

先想一個場景：你做了一個自動寫站會日報的 skill，今天跑一次，明天跑一次。問題來了，它怎么知道哪些內容昨天已經匯報過了？

每次會話都是新開的，Claude 不記得上一次執行的任何事。難道每天的日報都從頭把所有進展再說一遍？

官方的解法很樸素：讓 skill 把執行結果存在自己的文件夾里。比如日報 skill 維護一個日志文件，每發一次日報就追加一條記錄。下次執行時，Claude 先讀自己的歷史，自然就知道「只匯報昨天之后的增量」。

簡單的場景用追加式的文本日志或 JSON 就夠了，復雜的甚至可以塞一個 SQLite 數據庫進去。

skill 記憶機制示意圖

那這些數據該存在哪？官方專門為這件事準備了一個穩定的數據目錄，在 skill 里通過環境變量 CLAUDE_PLUGIN_DATA 就能拿到。

這個目錄最大的特點是持久：plugin 升級換版本都不會被清掉，只有徹底卸載時才會刪除。也就是說，你的 skill 記憶可以放心地活得比 skill 版本更久。

兩個數據目錄生命周期對比圖

記憶這個思路還有個變種用法：存配置。

有些 skill 第一次用之前，需要先從用戶那里要點信息。還是拿日報 skill 舉例，它總得知道日報要發到哪個頻道吧？這種信息不該寫死在 SKILL.md 里（不然沒法分發給別人用），也不該每次執行都問一遍（煩死人）。

官方給的模式是：把這類信息存進 skill 目錄下的一個 config.json。Claude 每次執行先看配置在不在，在就直接用；不在就說明是第一次跑，主動找用戶把信息問齊、寫進配置，下次就不用再問了。

相當于給 skill 加了一個「首次使用引導」。要是想問得更體面，還可以在 skill 里指明讓 Claude 用選擇題的形式來收集，用戶點一下就配置完了。

skill 首次配置流程圖

玩法二：把腳本喂給 Claude，讓它只管編排

官方有一句話我特別認同：你能給 Claude 最有力的工具就是代碼。

什么意思？假設你的數據分析 skill 里什么都不放，Claude 每次分析都要現場手寫「怎么連數據源、怎么拼查詢、怎么算留存」這一整套樣板代碼，又慢又容易錯。

但如果 skill 里預先放好一個函數庫，取數、清洗、對比這些底層活全部封裝成現成的函數，Claude 的每一個回合就都花在刀刃上：思考接下來該組合哪幾個函數，而不是重新發明輪子。

你問一句「周二的數據怎么了」，它現場寫一段十幾行的小腳本，把你的函數庫組合起來跑出答案。

現場造輪子 vs 組合積木對比圖

玩法三：掛只在 skill 激活期間生效的 hook

這是三個玩法里最容易被忽略、但想象空間最大的一個：skill 可以自帶 hook，而且這種 hook 只在 skill 被調用時注冊，會話結束就失效。

為什么這個設計很妙？想想官方給的兩個例子。

一個叫 careful 的 skill：激活后自動阻斷 rm -rf、DROP TABLE、強制推送這類危險命令。這種攔截要是常駐開著，開發體驗能把人逼瘋；但在你明確知道「我現在要碰生產環境」的時刻，手動激活它，就是一道恰到好處的保險。

另一個叫 freeze 的 skill：激活后禁止修改指定目錄之外的任何文件。專治排查 bug 時的「我只是想加兩行日志，結果 Claude 順手把無關代碼也給修了」。

臨時 hook 開關示意圖

用法也很輕：這類 hook 直接在 skill 的 frontmatter 里聲明就行，skill 被調用時自動注冊，會話結束自動失效，不需要你去碰全局的 hook 配置。

skill 的上限不是一份好文檔，是一個帶記憶、帶工具、帶保險絲的小型工作系統。

Q6：skill 怎么從你的本地走向全團隊？

一個人把 skill 玩明白了，價值是 1；讓整個團隊都用上，價值才是 N。但一到團隊層面，馬上冒出三個新問題：怎么分發？誰來審批？質量怎么保證？

先說分發。官方給了兩條路。

第一條路：把 skill 直接提交進代碼倉庫，放在 .claude/skills 目錄下。團隊成員拉代碼的時候 skill 就跟著到位了，零成本同步。小團隊、倉庫不多的場景，這條路最省事。

但還記得 Q3 說的那個 1% 預算嗎？這條路有個隱性代價：倉庫里每多一個 skill，每個人每次會話的清單里就多一行，所有人無差別承擔這份 context 開銷，不管用不用得上。

所以規模一上來，官方推薦第二條路：做成 plugin，搭一個團隊內部的 plugin marketplace。skill 打包上架，誰需要誰安裝，context 成本回歸到「誰用誰付」。新人入職裝一遍團隊插件，立刻獲得和老員工一樣的裝備。

兩條分發路線對比圖

那 marketplace 誰說了算？哪些 skill 能上架？

Anthropic 內部的答案可能跟你想的不一樣：沒有一個中心化的團隊做審批。

他們的玩法是完全的自然演化：你寫了個 skill 想給大家試試，先扔進 GitHub 上的一個沙盒文件夾，在 Slack 里吆喝一聲。用的人多了、口碑起來了（火沒火由 skill 作者自己判斷），作者再提一個 PR 把它從沙盒挪進正式 marketplace。

像不像開源社區的運作方式？好東西靠口碑自己長出來，而不是靠委員會評出來。審批環節越重，愿意分享的人越少；門檻低到「扔進沙盒就行」，幾百個 skill 才攢得起來。

skill 自然演化漏斗圖

還有一個團隊場景下繞不開的小問題：skill 之間能不能互相依賴？比如一個生成 CSV 的 skill，最后一步要調用另一個文件上傳 skill。

官方很坦誠：依賴管理目前沒有原生支持。但解法意外地簡單，在 skill 正文里直接報另一個 skill 的名字就行，只要對方裝了，模型自己會去調用。畢竟執行者是一個能理解自然語言的 agent，「用 file-upload skill 把結果傳上去」這句話本身就是依賴聲明。

skill 自然語言依賴示意圖

好 skill 的團隊化路徑：沙盒里長出來，口碑里篩出來，marketplace 里沉淀下來。

Q7：怎么知道一個 skill 到底有沒有人用？

最后一個問題，也是大多數團隊壓根沒意識到要問的問題。

skill 攢了幾十個，marketplace 也搭起來了，然后呢？哪些 skill 天天被調用，哪些寫完就成了倉庫里的化石？沒有數據，你只能靠感覺。

靠感覺的結果通常是：大家繼續給沒人用的 skill 添磚加瓦，真正高頻的 skill 反而沒人維護。

Anthropic 的做法是給 skill 做埋點，思路相當巧妙：用一個 PreToolUse hook 監聽 skill 工具的每一次調用，把「誰在什么時候用了哪個 skill」記錄下來，匯總成公司內部的使用統計。

相當于給每個 skill 裝了個計數器，數據一拉出來，兩類問題立刻現形。

一類是「受歡迎的 skill」：調用量大，值得重點維護、優先打磨，Q2 說的「派工程師花一周打磨驗證 skill」這種投入，就該花在這類 skill 上。

另一類更有意思，叫觸發不足（undertriggering）：你預期它該被高頻使用，數據卻顯示幾乎沒人碰。這種 skill 八成是 Q3 的病，description 沒寫對，模型掃一眼清單根本想不起它。數據幫你把「該觸發卻沒觸發」的病人篩出來，再回頭去修 description，形成閉環。

skill 埋點度量閉環圖

這件事的成本低到沒有借口不做：一個 hook、一段日志腳本，官方連示例代碼都開源出來了。但它把 skill 建設從「憑感覺做」變成了「看數據做」，這是個質變。

不被度量的 skill 庫，遲早變成沒人敢動也沒人想用的雜物間。

最后

7 個問題說完了，按慣例濃縮成 3 句話送你：

全文總結圖

• 第一，skill 是文件夾不是文件，把腳本、坑點清單、記憶文件、臨時 hook 都用上，它才是一個完整的工作系統。

• 第二，決定 skill 命運的是 description 的前 250 個字符，寫成「什么場景下用我」的觸發條件，而不是給人看的摘要；裝太多 skill 會互相擠占清單預算，貴精不貴多。

• 第三，如果只做一件事，先做驗證類 skill，讓 Claude 能自己確認工作成果，這是 Anthropic 實測回報最大的投入。

博客的結尾有一句話我很喜歡，也送給準備動手的你：他們內部最好的那批 skill，幾乎都是從「幾行字加一個坑點」開始的，然后隨著 Claude 撞上一個個新的邊界情況，被人一點點喂大。