> ## Content Index
> Fetch the complete content index at: https://growthhackers.tw/llms.txt
> Use this file to discover other available public pages before exploring further.

# 你的 Claude Skill 為什麼沒被叫出來？解碼 Anthropic 官方 33 頁指南：勝負在 description 那一行
- URL: https://growthhackers.tw/blog/claude-skills-description-trigger-test/
- Published: 2026-09-06T13:00:00.000Z
- Updated: 2026-09-06T13:00:00.000Z
- Description: Anthropic 33 頁官方 Skills 指南自標 January 2026，我拿八個月後的現行文件對照，四條已經變了。但重點是：skill 會不會被叫出來，只看 frontmatter 那一行 description。這篇拆解漸進式揭露三層、觸發診斷，以及 90% 觸發率怎麼測。
- Author: Lewis wang
- Tags: Agent Skills, Claude Code, AI agent, AI 工作流, 提示工程

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

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

內文寫著「Current distribution model (January 2026)」。這份東西是今年一月的狀態。我拿八月的[現行官方文件](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices?ref=growthhackers.tw)逐條對過一遍，有四條已經不一樣了。

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

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

![漸進式揭露三層：YAML frontmatter 永遠載入系統提示，SKILL.md 本文相關時才載入，references/ 需要時才讀](https://growthhackers.tw/content/images/2026/09/inline-progressive-disclosure-v1.png)

漸進式揭露三層：YAML frontmatter 永遠載入系統提示，SKILL.md 本文相關時才載入，references/ 需要時才讀

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

指南裡最關鍵的機制叫 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「技能地獄」那篇](https://growthhackers.tw/blog/writing-great-agent-skills/)講過。但那是品味問題，今天這個是機制問題。

![觸發診斷兩種病：不觸發要補關鍵字與細節，觸發太頻繁要加負面觸發詞並界定範圍](https://growthhackers.tw/content/images/2026/09/inline-trigger-diagnosis-v1.png)

觸發診斷兩種病：不觸發要補關鍵字與細節，觸發太頻繁要加負面觸發詞並界定範圍

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

指南第 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，是同一種死法。

![對照組要比的四個數字：來回次數、工具呼叫次數、失敗次數、總 token。此為概念示意，非實測基準](https://growthhackers.tw/content/images/2026/09/inline-baseline-comparison-v1.png)

對照組要比的四個數字：來回次數、工具呼叫次數、失敗次數、總 token。此為概念示意，非實測基準

## 對照 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 課程那篇](https://growthhackers.tw/blog/agent-skills-andrew-ng-course/)談過）。每一份都重複、都有規則、都常常沒人照做。

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

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

想再進一步的，可以把驗證流程本身也寫成 skill，我在[Claude Code skill 驗證迴圈那篇](https://growthhackers.tw/blog/claude-code-skill-verification-loop/)拆過做法。另外，skill 裝多了會撞到天花板，[Stripe 內部 AI 助理那篇](https://growthhackers.tw/blog/stripe-kai-agent-platform-governance/)有實測數字可參考。

如果你問我，這份 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)` 形式附上，方便你進一步查找。若文中內容與原始出處有任何出入，請以原文為準。

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