本文根據 Agent Skills 官方指南《Optimizing skill descriptions》和 Claude Code 官方文檔的 Troubleshooting 一節整理，資料核對於 2026-10-11。排查命令以 Claude Code 為例，其他工具的思路相同、命令不同。
適用於誰
- 搜「skill 不觸發」「如何觸發 skill」「skill 觸發詞」的人；
- Skill 明明裝好了，說了相關的話 Claude 卻不用它的人；
- 反過來，Skill 在不相干的任務裏亂跳出來的人；
- 看到「skill descriptions were shortened to fit the skills context budget」這類提示不知道什麼意思的人。
結論先說
- 觸發只看 description。智能體啟動時只加載每個 Skill 的名稱和描述，任務和描述對得上才會去讀正文。正文寫得再好，描述沒寫清「什麼時候用」也不會被調用。
- 簡單任務本來就不一定觸發。官方說明：智能體一般只在自己搞不定的任務上才去查 Skill，「讀一下這個 PDF」這種一步就能完成的請求，即使描述完全匹配也可能不觸發。
- 不觸發先做四件事：確認 Skill 被發現了、檢查 YAML 有沒有寫錯、看描述有沒有被截斷、把描述改成「Use this skill when...」的寫法。
- 亂觸發就把描述寫窄，或者關掉自動調用、只留手動調用。
- 想認真調，就做測試集：約 20 條問句，一半該觸發一半不該觸發，每條跑 3 次算觸發率。
一、觸發是怎麼發生的
三步：
- 啟動時，智能體讀入所有 Skill 的
name和description； - 你提出任務，智能體把任務和這些描述做匹配；
- 匹配上了，才把對應的
SKILL.md全文讀進上下文並照着做。
官方的說法是：description 承擔了觸發的全部責任。
二、description 的四條寫法
來自《Optimizing skill descriptions》：
| 原則 | 說明 |
|---|---|
| 用祈使句 | 寫「Use this skill when...」，而不是「This skill does...」。智能體在判斷要不要行動，就直接告訴它何時行動 |
| 寫用戶意圖，不寫實現 | 描述用戶想達成什麼，而不是 Skill 內部用了什麼庫、分幾步 |
| 寧可主動一點 | 明確列出適用場景，包括用戶沒有直接說出領域名稱的情況 |
| 保持簡短 | 幾句話到一小段；規範的硬上限是 1024 字符 |
官方給的修改前後對比：
yaml
# 修改前
description: Process CSV files.
# 修改後
description: >
Analyze CSV and tabular data files — compute summary statistics,
add derived columns, generate charts, and clean messy data. Use this
skill when the user has a CSV, TSV, or Excel file and wants to
explore, transform, or visualize the data, even if they don't
explicitly mention "CSV" or "analysis."改後的版本對「做什麼」更具體（統計、派生列、圖表、清洗），對「什麼時候用」更寬（CSV、TSV、Excel，沒提關鍵詞也算）。
三、Claude Code 裏的排查步驟
1. Skill 有沒有被發現
官方列的檢查順序：
- 描述裏有沒有用戶自然會說的關鍵詞；
- 問一句
What skills are available?，看它在不在列表裏（或者輸入/skills查看）； - 換一種更貼近描述的說法再試；
- 直接輸入
/技能名手動調用，確認 Skill 本身能工作。
如果手動調用正常、自動不觸發，問題就在描述或下面兩項。
2. YAML 有沒有寫錯
官方說明：frontmatter 的 YAML 格式不對時，Claude Code 仍會加載正文，但元數據是空的，於是 /技能名 能用，Claude 卻沒有描述可以匹配。
- 加
--debug啟動可以看到解析錯誤； - 批量檢查可以運行
claude plugin validate .claude/skills（項目 Skill）或claude plugin validate ~/.claude/skills（個人 Skill）。官方註明這個用法需要較新的版本。
3. 描述是不是被截斷了
Skill 裝得多時會出現這個問題。官方文檔的說明：
- Claude Code 把所有 Skill 的名稱和描述組成一份清單放進上下文。清單始終包含每個 Skill 的名稱，但總量超出預算時會丟掉一部分描述，被丟掉描述的 Skill 就失去了用來匹配的關鍵詞；
- 預算按模型上下文窗口的 1% 計算；
- 超出時，從你最少調用的 Skill 開始丟，常用的保留完整描述；
- 每個 Skill 的
description加when_to_use合計最多顯示 1,536 個字符，超出部分截掉。
怎麼查、怎麼辦：
| 目的 | 做法 |
|---|---|
| 看清單佔了多少上下文、誰佔得最多 | 運行 /doctor |
| 找出裝了卻從沒用過的 Skill | 運行 /skill-doctor |
| 調大預算 | 設定 skillListingBudgetFraction（例如 0.02 即 2%），或用環境變量 SLASH_COMMAND_TOOL_CHAR_BUDGET 指定固定字符數 |
| 給其他 Skill 騰地方 | 在 skillOverrides 裏把優先級低的設為 "name-only"，只列名稱不列描述 |
| 從源頭壓縮 | 精簡描述，把最關鍵的使用場景寫在最前面 |
4. 是不是被設成了只能手動調用
frontmatter 裏有 disable-model-invocation: true 的 Skill，描述不會進入上下文，Claude 不會自動調用，只能你輸入 /技能名。從別處拿來的 Skill 不觸發時，記得看一眼這個字段。
四、亂觸發怎麼辦
官方給的兩條：
- 把描述寫得更具體。可以寫明這個 Skill 不做什麼，或者說清它和相鄰能力的邊界；
- 只想手動調用，就加
disable-model-invocation: true。有副作用的 Skill（部署、發消息）官方本來就建議這樣設。
五、一開始照着做、後來不照做了
這是另一類問題，官方按原因分了三種：
| 現象 | 原因與辦法 |
|---|---|
| 跳過了一條必須每次都遵守的規則 | Skill 裏的話是「請求」，不是保證。把規則改成 Hook，由 Claude Code 在每次事件發生時強制執行 |
| 跳過了一條需要判斷着用的建議 | Skill 內容只在調用時加載一次，之後不會重讀。把措辭改成覆蓋整個任務的說法，例如「每次修改後都運行測試」而不是「運行測試」 |
| 對話被壓縮過 | 壓縮後每個 Skill 只保留開頭的一部分。重新調用一次即可恢復，並把最重要的說明放在 SKILL.md 靠前的位置 |
六、認真調：做一套觸發測試
官方推薦的方法，適合要發佈給別人用的 Skill。
1. 準備約 20 條問句，8–10 條應該觸發、8–10 條不應該觸發：
json
[
{ "query": "I've got a spreadsheet in ~/data/q4_results.xlsx with revenue in col C and expenses in col D — can you add a profit margin column and highlight anything under 10%?", "should_trigger": true },
{ "query": "whats the quickest way to convert this json file to yaml", "should_trigger": false }
]- 應該觸發的：說法要多樣，有正式有隨意，有的直接點名領域、有的只描述需求；最有價值的是「Skill 能幫上忙，但從字面看不明顯」的問句；
- 不應該觸發的：要選擦肩而過的。和 Skill 共用關鍵詞、實際需要的卻是別的東西。「今天天氣怎麼樣」這種毫不相干的問句測不出任何東西；
- 寫得像真人：帶文件路徑、帶背景（「領導讓我……」）、帶口語和偶爾的錯別字。
2. 每條跑 3 次，算觸發率。 模型的行為不是確定的，同一句話這次觸發下次可能不觸發。觸發率高於 0.5 算觸發。
3. 留出驗證集。 約 60% 用來發現問題、指導修改，約 40% 只用來檢驗修改是否真的通用，避免把描述調成只對這幾句話有效。
4. 循環修改，官方的提醒：
- 該觸發的沒觸發：描述太窄，擴大範圍；
- 不該觸發的觸發了：描述太寬，加上邊界；
- 不要把失敗問句裏的詞直接塞進描述，那是過擬合，要找出這些問句代表的那一類情況；
- 改了幾輪沒進展，就換一種句式結構重寫，而不是繼續小修小補；
- 一般五輪足夠。再不行，問題可能在測試問句本身。
5. 選驗證集通過率最高的那一版，不一定是最後一版。
官方提到，Anthropic 的 skill-creator 技能可以把這套流程自動跑完；Skill 放在插件裏時，Claude Code 還可以用 claude plugin eval 配合 tool_used: Skill 評分器批量測試。
常見問題
Q：有沒有「觸發詞」這種東西？
沒有固定的觸發詞機制。智能體是拿任務和描述做語義匹配，描述裏出現用戶常說的詞會有幫助，但不是命中某個詞就一定觸發。
Q：description 用中文寫可以嗎？
規範沒有語言限制。按你平時提需求的語言來寫，更容易對得上。
Q：其他工具也是這樣嗎？
基於 SKILL.md 的工具觸發原理相同：先看描述，再讀正文。具體的查看命令和截斷規則各家不同，例如 Codex 的文檔寫的是清單最多佔上下文窗口的 2%，裝得多時先縮短描述。
Q：個人 Skill 文件夾不見了？
Claude Code 文檔有專門一節：先看 ~/.claude/skills/.trash/ 裏有沒有，把文件夾移回 ~/.claude/skills/ 即可恢復；回收目錄裏的內容預設 30 天后清理。
參考資料
- Optimizing skill descriptions（Agent Skills 官方）：https://agentskills.io/skill-creation/optimizing-descriptions
- Extend Claude with skills · Troubleshooting（Claude Code 官方）：https://code.claude.com/docs/en/skills
- Extend Claude Code（Claude Code 官方）：https://code.claude.com/docs/en/features-overview
0 條評論
還沒有評論，來搶沙發～