你的 Claude Skill 為什麼沒被叫出來？解碼 Anthropic 官方 33 頁指南：勝負在 description 那一行

Anthropic 出了一份 33 頁的官方指南，《The Complete Guide to Building Skills for Claude》，把 Agent Skills（代理技能）怎麼做講了一輪。

我讀完的第一個動作不是抄重點，是去翻它的日期。

內文寫著「Current distribution model (January 2026)」。這份東西是今年一月的狀態。我拿八月的現行官方文件逐條對過一遍，有四條已經不一樣了。

大家拿到官方指南的預設動作是「照抄」。但照抄有兩個洞：一來是格式規則有保存期限，二來是幾乎所有人都跳過了最該讀的那一章。

那一章叫 Testing and iteration，講的不是怎麼寫 skill，是怎麼驗收 skill。

只有一行字是「永遠」被讀到的

指南裡最關鍵的機制叫 progressive disclosure（漸進式揭露），分三層：

★ 第一層 YAML frontmatter（檔案開頭的設定區塊）：永遠載入 Claude 的系統提示 ★ 第二層 SKILL.md 本文：Claude 判斷這件事跟你的 skill 有關，才會載入 ★ 第三層 references/ 裡的檔案：真的需要時才去讀

看懂這三層，你就會發現一件很不舒服的事。

你在 SKILL.md 裡寫得再用力、規則列得再細，全都躺在第二層。第一層只有兩個欄位：name 和 description。而 description 上限 1,024 個字元。

換句話說，你的 skill 會不會被叫出來，跟你寫得多好完全無關，只跟那一行 description 有關。

這就像投廣告。SKILL.md 是素材，description 是投放設定。素材做到得獎等級，投放沒設對，曝光是零。觸發率是曝光，內容品質是轉換率，順序不能顛倒。

指南說 description 必須同時包含兩件事：做什麼，以及什麼時候用。失敗的案例，大多只寫了前半段。

想像你把公司的退換貨話術做成一個 skill，description 寫「處理客服訊息」。

這只交代了做什麼。什麼時候用？沒寫。於是客服同事在後台問「這張單客人說鞋子穿了兩天要退，怎麼回」，Claude 根本不知道該把你那份話術叫出來，就自己掰了一段。

指南裡還藏了一招除錯神技，我覺得比任何檢查清單都好用：

直接問 Claude：「你什麼時候會用 [skill 名稱] 這個 skill？」

它會把 description 背回來給你。它漏掉的、講不出來的，就是你該補的。

看兩種病：

► 不觸發（undertriggering）：該用卻沒載入、你得手動叫它。解法是補細節跟關鍵字，特別是使用者實際會講的詞。 ► 觸發太頻繁（overtriggering）：不相關的問題它也跳出來。解法是加負面觸發詞，明白寫「不要用在什麼情況」，並且界定範圍。

技能不是越多越強，這件事我在之前談 Matt Pocock「技能地獄」那篇講過。但那是品味問題，今天這個是機制問題。

官方自己承認：現在還有一部分是憑感覺

指南第 9 頁有一段話，我相信 99% 的人讀過就滑掉了。

Anthropic 在講「怎麼定義 skill 成功」的時候，自己補了一句：這些只是 aspirational targets（理想目標）和 rough benchmarks（粗略基準）。

原文寫「aim for rigor but accept that there will be an element of vibes-based assessment」：要求嚴謹，但要接受評估帶有憑感覺的成分。他們當時說，更嚴謹的量測工具正在開發。

官方蓋章：現在判斷一個 skill 好不好，還有一部分靠感覺。

那它給的可量測標準是什麼？

skill 應該在 90% 的相關查詢上被觸發。（注意，這是指南自己說的理想目標，不是保證，也不是官方 SLA。）

量法很土炮，但有效：跑 10 到 20 個「應該觸發」的查詢，記得放幾句換句話說的版本，數它自動載入幾次、幾次要你手動叫。再補一組「不應該觸發」的不相關問題，看它會不會亂跳。

再來是對照組。同一個任務跑兩次，一次開 skill、一次關 skill，比四個數字：來回幾次、呼叫幾次工具、失敗幾次、總共吃掉多少 token。

指南裡舉的例子是 12,000 token 降到 6,000。這是說明概念的示意數字，不是實測基準，別拿去當簡報效益。Anthropic 的工程部落格全文沒有任何量化數據。

然後是這篇的重點查證。

那句「正在開發量測工具」，八個月後兌現了嗎？我在 2026 年 8 月底去翻現行官方文件，上面仍然寫著：目前沒有內建的方式執行這些評測，使用者可以自建評測系統。

工具還沒到。所以你想量，只能自己土炮。

還有一件很容易誤判的事。一個 skill 裝在那裡，卻從來沒被叫出來過，第一時間通常會被當成內容寫得不夠好。

零使用率不是內容爛，是觸發失敗。這跟公司裡那份四十頁沒人照做的客服 SOP，是同一種死法。

對照 Anthropic 現行文件，有四條已經變了

這四條在 PDF 裡要不是完全沒寫，就是寫得不一樣，是我對照八月官方文件抓出來的：

1. description 必須用第三人稱。 官方原文警告：description 會被注入系統提示，人稱不一致會造成 discovery（發現）問題。好的寫法是「Processes Excel files and generates reports」，要避免的是「I can help you...」跟「You can use this to...」。順著中文語感寫成「我可以幫你…」的都該改掉。

2. SKILL.md 本文控制在 500 行以內。 PDF 寫的是 5,000 words（英文字數）。單位跟數字都不一樣，我不打算幫它們換算，以現行官方文件為準就好。

3. 你打算用哪幾個模型，就要每個都測一遍。 Haiku 會不會覺得不夠明確、Sonnet 讀起來清不清楚、Opus 會不會嫌你過度解釋。PDF 完全沒提模型差異。

4. 先寫評測，再寫文件。 這條最狠：先不帶 skill 跑一次代表性任務、記下它爛在哪，接著建三個測試情境，量出沒有 skill 的基準線，然後只寫剛好夠用的指令，最後跑評測跟基準線比。

以前大家的做法是「寫完 skill 再想怎麼測」。現在官方把順序倒過來：先建評測、先量基準線，再寫文件。講白一點就是，沒有基準線就不要動筆。

這週先測你的 description 觸發率

台灣電商團隊先別急著重寫整包 skill。手上那三份文件：客服應對 SOP、上架文案規範、檔期活動 checklist，拿來當觸發測試的素材就夠了（SOP 怎麼變技能，Andrew Ng 課程那篇談過）。每一份都重複、都有規則、都常常沒人照做。

但動手前，先做那件所有人都跳過的事：

► 先跑基準線。 不帶 skill，讓 AI 做一次上架文案，把爛結果原封不動存下來。這就是你的對照組。這跟做促銷檔期一樣，台灣電商最常見的錯就是看到營收漲就當有效，沒留對照組，永遠不知道是折扣有效還是節慶有效。 ► description 寫兩段。 前半寫做什麼，後半寫「當使用者提到退貨、上架文案、檔期 checklist 時使用」。把你團隊真的會講的詞塞進去。寫完問 Claude 一句「你什麼時候會用它」，看它背得出來嗎。 ► 列 10 個測試句。 5 句該觸發（其中 2 句故意換句話說），5 句不該觸發。跑一輪，數命中率。沒到九成就回去改 description，不要改 SKILL.md。

想再進一步的，可以把驗證流程本身也寫成 skill，我在Claude Code skill 驗證迴圈那篇拆過做法。另外，skill 裝多了會撞到天花板，Stripe 內部 AI 助理那篇有實測數字可參考。

如果你問我，這份 33 頁指南最有價值的不是那些格式規則。

格式會過期，我對照八個月就抓到四條。

但「先量基準線、再寫東西」這個順序不會過期。它在 A/B 測試是這樣，在廣告投放是這樣，在 skill 也是這樣。

常見問題 FAQ

Q1：SKILL.md 的 description 到底該寫什麼？

兩件事缺一不可：這個 skill 做什麼，以及什麼時候該用它（觸發條件）。上限 1,024 字元，用第三人稱寫，把使用者實際會講的詞放進去，有涉及特定檔案類型也要寫明。

Q2：為什麼我的 skill 從來不會自動觸發？

這叫 undertriggering（觸發不足）。八成是 description 太籠統，或只寫了「做什麼」沒寫「什麼時候用」。除錯方法：問 Claude「你什麼時候會用這個 skill」，看它背回來缺什麼，就補什麼。特別是技術名詞跟你團隊的慣用語，一定要寫進去。

Q3：skill 觸發太頻繁怎麼辦？

這叫 overtriggering（過度觸發），解法是加 negative trigger（負面觸發詞）。在 description 裡明白寫出不該用它的情境，例如「不要用於單純的資料瀏覽」。同時把描述寫得更具體、界定清楚適用範圍。

Q4：SKILL.md 該寫多長？

Anthropic 現行文件建議 SKILL.md 本文控制在 500 行以內。超過就把細節拆到 references/ 資料夾，讓 Claude 需要時才去讀。這正是漸進式揭露的用意。

Q5：怎麼知道我的 skill 到底有沒有用？

先測觸發率：跑 10 到 20 個查詢，指南的理想目標是命中 90%。再跑對照組，同一任務開關 skill 各做一次，比四個數字：來回次數、工具呼叫次數、失敗次數、總 token。Anthropic 目前沒有提供內建的評測執行工具，這套流程要自己搭。

協作聲明與免責

這篇文章由王董與 AI 一起整理製作完成。文中引用的第三方資料、研究或工具都會標註來源名稱；若原始出處有公開連結，會以 [來源名稱](URL) 形式附上，方便你進一步查找。若文中內容與原始出處有任何出入，請以原文為準。

內容僅供參考與學習交流，不構成任何專業、商業或投資建議，請依自身情況判斷並自行承擔行動風險。文中提及的工具功能、數據與平台政策可能隨時間異動，請以各官方最新公告為準。