註冊
Claude

Claude Code 寫一個會自動觸發的 Skill：從需求到觸發，用 description、when_to_use 和 paths 控制它什麼時候出場

寫好的 Skill 總是不觸發，或者什麼都觸發？本文按 Claude Code 官方「Extend Claude with skills」走一遍完整實例：把「改數據庫遷移前先檢查」寫成一個會自動出場的 Skill，包含 description、when_to_use、paths、附帶腳本、觸發測試和評估。

NNathaniel bigo··原創首發·AI 輔助撰寫
11 分鐘讀完
資料核對於 2026-11-05 · 依據官方文檔與公開資料整理 Pro 帳號
本文根據 Claude Code 官方文檔《Extend Claude with skills》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

  • 已經會寫最簡單的 Skill，但總遇到「它不自己出場」或「不該出場時亂出場」的人；
  • 想讓 Claude 在改某一類文件時自動套用團隊規矩，而不是每次手動輸入命令的人。

本站的 /guides/claude-code-custom-skill-slash-command-example 寫的是手動觸發的 /release-notes。本文反過來：寫一個主要靠自動觸發的 Skill，重點是怎麼讓它在對的時候出現。字段規範和目錄結構不重複，見 /guides/skill-md-format-spec-how-to-write。

結論先說

  1. 自動觸發靠的是 description。 官方說，普通會話裏所有技能的名字和描述會被放進上下文，Claude 據此判斷要不要加載；技能全文只在被調用時才進來。
  2. description 要把關鍵用途放最前面，寫進用戶會自然說的詞。 官方給了硬數字：description 和 when_to_use 合起來在技能列表裏最多保留 1,536 個字符，超出被截斷。
  3. 想把範圍收窄，用 paths。 設定後 Claude 只在處理匹配這些文件時才自動加載這個技能；匹配相對當前工作目錄。
  4. 「必須每次都做」的規則不要只靠 Skill。 官方說 Claude 可能後來不照着做，必須每次發生的要改用 Hook。
  5. 看到觸發不等於做對了。 官方建議拿幾條真實提示詞，分別在有技能和關掉技能的新會話裏各跑一次，對比結果。

讓 Skill 自動觸發的步驟

圖：本站根據 Claude Code 官方文檔：Skills 整理的示意圖

一、先把需求說清楚

好的 Skill 來自一個具體的重複問題。本例的需求：

團隊的數據庫遷移文件放在 migrations/ 下。每次讓 Claude 改遷移，我都要重複提醒：不要直接刪列，新增非空列必須帶預設值，改完要跑檢查腳本。

這是官方說的「總是把同一段指令粘貼進對話」的典型情形。它還有兩個特點：不需要你每次想起來才用（所以適合自動觸發），只和一類文件有關（所以適合 paths）。

二、建目錄和 SKILL.md

放項目裏，提交進倉庫全隊共用（官方的項目技能位置）：

bash
mkdir -p .claude/skills/migration-review/scripts

.claude/skills/migration-review/SKILL.md：

text
---
name: migration-review
description: 修改或新增數據庫遷移文件前後的檢查清單。當用戶要改 migrations、加表、加列、刪列、改字段類型時使用。
when_to_use: 用戶說「寫個遷移」「給表加個字段」「這個遷移安全嗎」，或者正在編輯 migrations 目錄下的 SQL 文件。
paths: migrations/**
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check.sh *)
---

處理遷移文件時，整個任務期間都遵守這些規則：

1. 不直接刪除列或表；需要刪除時，先拆成「停止使用」和「刪除」兩個遷移，並在回覆裏提醒我。
2. 新增 NOT NULL 列必須帶預設值，或者先加可空列再回填。
3. 改完每個遷移文件後，運行 `${CLAUDE_SKILL_DIR}/scripts/check.sh <遷移文件路徑>`，把輸出原樣告訴我。
4. 檢查不通過時，說明原因並修改，不要繞過腳本。
5. 命名規則和更多例子見 [conventions.md](conventions.md)，需要時再讀。

對照官方文檔逐項解釋：

  • description 加 when_to_use：官方說 when_to_use 用來補充「什麼時候該調用」，比如觸發短語或示例請求，會追加到 description 後面，一起計入 1,536 字符上限。所以兩個都別寫成長文。
  • paths：官方說明可以是逗號分隔的字符串或 YAML 列表，格式與路徑專屬規則相同。
  • allowed-tools：官方說它在調用這個技能的那一輪裏，讓列出的工具不再彈確認；下一條消息發出後失效。官方還給了同樣的寫法：用 ${CLAUDE_SKILL_DIR} 同時寫在正文和 allowed-tools 裏，規則就能精確匹配正文要求運行的命令，腳本不會彈窗。
  • 規則寫成整個任務期間都適用的口吻：官方說技能內容進入對話後不會被重新讀取，所以要寫成常駐指令，而不是一次性步驟。

三、加腳本和參考文件

官方說腳本是被執行的而不是被讀進上下文，適合把確定性的檢查交給程序。下面這個 scripts/check.sh 是本站為演示寫的，規則很簡單，請按自己的數據庫改：

bash
#!/usr/bin/env bash
# 演示腳本：檢查遷移文件裏的兩類高風險寫法
f="$1"
[ -f "$f" ] || { echo "文件不存在：$f"; exit 2; }
if grep -Eiq 'DROP[[:space:]]+(COLUMN|TABLE)' "$f"; then
  echo "發現 DROP COLUMN / DROP TABLE，請拆成兩個遷移"; exit 1
fi
if grep -Eiq 'ADD[[:space:]]+COLUMN.*NOT NULL' "$f" && ! grep -Eiq 'DEFAULT' "$f"; then
  echo "新增 NOT NULL 列沒有 DEFAULT"; exit 1
fi
echo "檢查通過：$f"

再建 conventions.md，寫命名規則和兩三個「好的 / 壞的」遷移示例。官方建議 SKILL.md 控制在 500 行以內，詳細內容挪到單獨文件，並且在 SKILL.md 裏寫明每個文件是什麼、什麼時候讀（上面第 5 條就是這樣做的）。

四、測試：它到底觸發了嗎

官方的驗證辦法有幾條，按順序做：

  1. 啟動 claude，問「What skills are available?」（用中文問「有哪些技能可用」也可以），確認 migration-review 在列表裏。
  2. 用自然語言提需求，不要用命令：
text
給 users 表加一個 phone 字段，非空，寫個遷移
  1. 如果沒有自動加載，用 /migration-review 直接調用，確認技能本身沒問題。
  2. 再用一句不相關的話（比如「幫我改一下首頁的按鈕顏色」），確認它沒有亂出場。

Skill 觸發不對時先查什麼

圖：本站根據官方「Troubleshooting」整理的示意圖

五、觸發不對怎麼辦（官方排查順序）

不觸發：

  1. 看 description 裏有沒有用戶自然會說的詞；
  2. 確認它出現在可用技能列表裏；
  3. 換一種更貼近 description 的說法再試；
  4. 用 /名字 直接調用；
  5. 如果設了 paths，檢查 Claude 讀、改、寫的文件是否在當前工作目錄之內。官方特意提到：兄弟 git worktree 裏的文件不會激活，即使用 /add-dir 添加過也一樣。要麼在那個目錄裏啟動，要麼用 /cd 把會話移過去。

另外官方提醒：YAML 寫錯時技能仍會加載，但元數據是空的，所以 /名字 能用、自動匹配卻不行。可以用 claude --debug 看解析錯誤，或運行 claude plugin validate .claude/skills。

觸發太頻繁： 讓 description 更具體，或者加 disable-model-invocation: true 改成只能手動觸發。

描述被截斷： 技能多了之後，官方說描述列表有預算（約為模型上下文窗口的 1%），超出時從最少使用的技能開始丟描述。運行 /doctor 能估算列表佔的上下文，/skill-doctor 能找出該關掉的技能。

後來不照着做： 見結論第 4 條。必須每次都做的，用 Hook；見 /guides/claude-code-hooks。官方還說對話被壓縮後可能只保留技能內容的開頭，所以最重要的規則放最前面。

六、讓 Claude 幫你調 description

提示詞：

text
我有一個技能 .claude/skills/migration-review/SKILL.md。請給出 8 句用戶可能會說的話，其中 4 句應該觸發它，4 句不應該；然後逐句判斷按現在的 description 和 when_to_use 會不會觸發，不會的給出修改建議。先不要改文件。

七、怎麼知道它真的有用

官方的說法是：觸發只說明 Claude 找到了它，不說明結果對。方法是收集幾條真實的提示詞，各在新會話裏跑兩遍，一遍開着技能、一遍關掉（項目技能可以在 skillOverrides 裏設為 "off"），比較結果；在新會話裏跑很重要，因為你寫技能時留下的上下文會掩蓋指令裏的漏洞。

要自動化這個流程，官方提到可以裝 skill-creator 插件：

text
/plugin install skill-creator@claude-plugins-official

裝好後讓 Claude「evaluate my migration-review skill with skill-creator」，它會生成測試用例、做有無技能的對比，並能測 description 的命中率。如果提示 marketplace 找不到，官方給的辦法是先 /plugin marketplace add anthropics/claude-plugins-official。插件系列見 /guides/claude-code-plugins-marketplace。

常見問題

Q：Skill 和 CLAUDE.md 怎麼分工？

事實和常駐約定放 CLAUDE.md；只在某類任務時才需要的流程放 Skill，平時只佔一行描述。選型對比見 /guides/skill-vs-mcp-vs-subagent-vs-hook。

Q：觸發不穩定，有沒有專門的排查文章？

見 /guides/skill-not-triggering-description-optimize。

Q：放哪個目錄、同名誰優先？

見 /guides/claude-code-skills-directory-location-priority。

訂閱和額度

Skill 的好處之一是正文按需加載，不會像長 CLAUDE.md 那樣每次都占上下文。需要 Claude Code 訂閱可看 /chongzhi/claude-code，價格和額度以官方頁面當前顯示為準。

相關教學

參考資料

  • Claude Code 文檔：Extend Claude with skills — https://code.claude.com/docs/en/skills

Nathaniel 的更多內容

  1. 01

    Claude Personal Finance 是什麼：連銀行帳戶問花銷、怎麼開、只讀權限、誰能用、怎麼解除

    Claude 的 Personal Finance（beta）通過 Plaid 只讀連接你的銀行、信用卡、貸款和投資帳戶，在一頁裏看餘額和花銷並用自然語言提問。本文按官方幫助頁講誰能用（僅美國、Pro/Max/Ultra）、連接與解除步驟、Claude 能看什麼，以及它做不到的事。

    Claude0
  2. 02

    Claude Code 離開一小時回來對話被「壓縮」了：Idle compaction 是什麼、條件、怎麼關

    Claude Code 的 idle compaction 會在你離開約一小時後，把 200K token 以上的長對話先壓縮成摘要，下一條消息就不用重新處理整段歷史。本文按官方文檔講觸發條件、看到什麼提示、用 /config 或 idleCompaction 關閉、調閾值，以及恢復舊對話的用量警告。

    Claude0
  3. 03

    ChatGPT Computer History 是什麼：Mac 桌面端的活動記憶怎麼開、怎麼暫停和清除、誰能用

    Computer History 是 ChatGPT macOS 桌面應用裏預設關閉的可選功能，把你在應用和網站裏的活動整理成記憶和時間線，供 ChatGPT 與 Codex 引用。本文按官方文檔講怎麼開、記錄什麼不記錄什麼、怎麼暫停與清除、數據存哪、誰能用，以及提示注入風險。

    ChatGPTCodex0
  4. 04

    Codex 輸入框出現灰色建議：Composer predictions 是什麼、Tab 接受、怎麼關、誰能用

    Codex 桌面 App 的 Composer predictions（beta）會在 Codex 回完後，根據當前對話在輸入框裏給出下一條消息的建議，按 Tab 接受、不會自動發送。本文按官方幫助頁講誰能用、哪些線程支持、怎麼關、算不算額度，以及沒出現時怎麼查。

    ChatGPTCodex0
  5. 05

    ChatGPT 私隱中心（Privacy Center）在哪裏：私隱設定入口、三大分類和哪些套餐有

    ChatGPT 的 Privacy Center 把記憶、廣告、位置、臨時對話、鎖定對話、兩步驗證、模型改進、數據導出和刪號等入口集中到一頁。本文按官方幫助頁講怎麼打開、三大分類各有什麼、哪些套餐有，以及它不會替你改任何設定。

    ChatGPT0
  6. 06

    Claude Code 處理大倉庫：怎麼讓它只看需要的目錄（子目錄 CLAUDE.md、claudeMdExcludes、deny 規則）

    倉庫太大，Claude Code 總在讀無關文件、讀進別的包的規則？本文按官方大倉庫指南講：從哪個目錄啟動、子目錄 CLAUDE.md、claudeMdExcludes、Read 的 deny 規則、worktree.sparsePaths、additionalDirectories，以及一份合併後的配置示例。

    Claude0

同產品的其他教學

  1. 01

    Claude Code 在 CI 裏跑：從本機 claude -p 到 GitHub Actions 的完整例子（自動審 PR、控成本）

    一條線走完 Claude Code 的 CI 用法：先在本機用 claude --bare -p 配 --json-schema 跑通，再寫進 GitHub Actions 用 claude-code-action@v1 自動審 PR，最後加上 --max-turns、超時、並發限制來控成本，並附上常見故障的排查順序。

    Claude0
  2. 02

    Claude Code 自定義 subagent 實例：測試員、調試員、只讀調研員、只讀數據庫員怎麼寫

    四個可直接改的 subagent 實例：跑測試的 test-runner、找根因的 debugger、只讀調研員、用 PreToolUse hook 限成只讀 SQL 的 db-reader；講 tools、disallowedTools、model、maxTurns 怎麼配，怎麼點名調用。

    Claude0
  3. 03

    Claude Code 的 CLAUDE.md 模板：前端、後端、數據分析各一份，附拆分與自檢方法

    直接拿去改的三份 CLAUDE.md 模板（前端、後端、數據分析），每份都控制在官方建議的 200 行以內；再講怎麼用 .claude/rules 的 paths 拆出專屬規則、用 @ 導入長文檔，以及用 /context all 和 /doctor prompt-audit 檢查是否生效。

    Claude0
  4. 04

    Claude Code 自己寫一個插件並發布到 marketplace：plugin.json、marketplace.json、validate 到團隊安裝的完整流程

    想把自己寫的 Skill、Hook 打包給團隊用？按 Claude Code 官方 Plugins 文檔，從目錄結構、plugin.json、claude plugin validate，到寫 marketplace.json、推到 Git、讓同事一條命令安裝，再到版本更新，走完一遍完整流程。

    Claude0
  5. 05

    Claude Code 配 Sentry MCP 排查線上報錯：添加命令、瀏覽器授權、貼 issue 連結修 bug 和插件子智能體

    線上報錯只能手動複製堆棧給 Claude Code？Sentry 官方提供 MCP 服務，可以讓它直接讀 issue、堆棧和 trace。本文按 Claude Code 官方 MCP 文檔和 Sentry MCP 官方說明，講添加命令、/mcp 授權、典型排查流程、插件方式和自託管注意事項。

    Claude0
  6. 06

    Claude Code 配 Context7 MCP 查最新文檔：兩種安裝方式、use context7 怎麼寫、指定庫和版本

    Claude Code 寫出來的代碼用了舊版 API？Context7 是一個把庫的最新文檔餵給編程助手的 MCP 服務。本文按 Context7 官方倉庫和文檔，講兩種安裝方式、在 Claude Code 裏的添加命令、use context7 與 library ID 的寫法，以及使用時的注意事項。

    Claude0

0 條評論

登入 後參與評論

還沒有評論，來搶沙發～