用法

Claude Code Skills 使用教程：SKILL.md 怎麼寫、放哪裡、怎麼觸發

釋出於 2026 年 10 月 30 日 · 最後核對 2026 年 10 月 30 日

skill 是一個帶說明的 SKILL.md 檔案：Claude 覺得相關時會自己用它，你也可以用 /skill-name 直接呼叫。這一頁按 Anthropic 的 Extend Claude with skills 文件，中文整理怎麼建立第一個 skill、skill 放在哪裡、frontmatter 怎麼寫、怎麼控制誰來呼叫，以及不觸發時怎麼排查。文件於 2026 年 10 月 30 日核對。

什麼時候該寫 skill

文件給的判斷標準：你一直在往對話裡貼上同樣的說明、清單或多步流程，或者 CLAUDE.md 裡有一段已經從“事實”變成了“流程”，就適合寫成 skill。和 CLAUDE.md 的內容不同，skill 的正文只在被用到時才載入，所以很長的參考資料在用到之前幾乎不占上下文。CLAUDE.md 的寫法見 CLAUDE.md 怎麼寫。

文件還說明，自定義命令已經合併進 skill：.claude/commands/deploy.md 處的檔案和 .claude/skills/deploy/SKILL.md 處的 skill 都會建立 /deploy，工作方式相同，已有的 .claude/commands/ 檔案繼續可用。skill 多出來的是：存放輔助檔案的目錄、控制由你還是 Claude 呼叫的 frontmatter，以及讓 Claude 在相關時自動載入的能力。

建立第一個 skill

下面這個例子來自文件：總結 git 倉庫裡未提交的改動，並標出有風險的地方。第一步，在個人 skills 目錄裡建一個資料夾，個人 skill 在你所有的專案裡都可用：

mkdir -p ~/.claude/skills/summarize-changes

第二步，寫 SKILL.md。每個 skill 都需要這個檔案，由兩部分組成：--- 標記之間的 YAML frontmatter，告訴 Claude 什麼時候用這個 skill；後面的 markdown 正文，是 skill 執行時 Claude 要遵循的說明。

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

目錄名（設定了 frontmatter name 時用 name）就是你輸入的命令，description 幫助 Claude 判斷什麼時候自動載入。!`git diff HEAD` 這一行是文件說的動態上下文注入：Claude Code 先執行這條命令，用輸出替換這一行，Claude 看到的 skill 內容裡已經帶著當前的 diff。

第三步，測試。開啟一個 git 專案，隨便改一個檔案，執行 claude，兩種方式都可以：

What did I change?     # 問一句和 description 匹配的話，讓 Claude 自動呼叫
/summarize-changes     # 或者用 skill 名直接呼叫

兩種方式下，Claude 都應該給出對改動的簡短總結和風險列表。

skill 放在哪裡

儲存的位置決定哪些工作階段會載入它：放在 home 目錄下，所有專案都有；提交到倉庫，在這個倉庫裡工作的人都有；也可以透過 plugin 或託管設定分發給整個團隊。

重名時的規則（文件原表的節選）：

• 企業、個人、專案裡有兩個同名：企業優先於個人，個人優先於專案。~/.claude/skills/ 和專案的 .claude/skills/ 裡都有 deploy 時，/deploy 執行個人的那個。
• skill 和 .claude/commands/ 裡的檔案同名：skill 優先。
• plugin skill 和上面任一位置的 skill 同名：兩個都會載入，因為 plugin skill 的名稱空間是 /plugin-name:skill-name。

另外，.claude/skills/ 在你啟動目錄的下層子目錄裡時，啟動時不會載入，要等 Claude 第一次讀取或編輯那個子目錄裡的檔案才會載入；在那之前，它們不出現在 / 選單裡，也不能按名字呼叫。

改動 skill 不需要重啟。Claude Code 會監視 skill 目錄，在 ~/.claude/skills/、專案的 .claude/skills/ 下新增、編輯或刪除 skill，當前工作階段內就會生效。如果你建立的是工作階段啟動時還不存在的頂層 skills 目錄，執行 /reload-skills。

最常用的 frontmatter 欄位

所有欄位都是可選的，只有 description 是推薦的。欄位名必須和表裡完全一致，連字元也一樣：Claude Code 會忽略不認識的欄位，而且不報錯。布林欄位除了 true 和 false，還接受 yes、no、on、off、1 和 0（字母大小寫均可）。

文件裡還有 model、effort、agent、background、hooks、shell、metadata、license、compatibility 等欄位，這裡不展開。有一條要注意：Claude Code 只在開頭的 --- 是檔案第一行時才讀 frontmatter，否則把整個檔案（包括 ---）當作 skill 內容。

自己呼叫，還是讓 Claude 決定

預設情況下，你和 Claude 都可以呼叫任何 skill：你輸入 /skill-name 直接呼叫，Claude 覺得和對話相關時自動載入。兩個 frontmatter 欄位可以限制：

• disable-model-invocation: true：Claude 不能自己呼叫。用於有副作用、或者你想自己控制時機的流程，比如 /commit、/deploy、/send-slack-message，你不希望 Claude 因為程式碼看起來好了就決定去部署。
• user-invocable: false：只有 Claude 能呼叫。用於不適合當命令用的背景知識，比如解釋舊系統怎麼運作的 legacy-system-context。

文件的 deploy 示例：

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

如果 Claude 仍然想用，Claude Code 會攔下這次呼叫，並告訴它不要用別的方式重現部署步驟，所以預期 Claude 會建議你自己執行 /deploy。

要直接執行 skill，把名字放在訊息開頭：/deploy staging 由 Claude Code 直接執行。如果名字出現在普通文字之後，例如 go ahead and /deploy to staging，不會直接執行；這個名字算作你對這條訊息的許可，Claude 回覆時可以執行這個 skill，並根據你的措辭判斷你是不是要它執行。只想談論這個 skill 而不允許執行，就去掉斜槓。

傳引數和輔助檔案

你和 Claude 呼叫 skill 時都可以傳引數，引數透過 $ARGUMENTS 佔位符取用，它會被替換成 skill 名後面的內容：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

執行 /fix-issue 123 時，Claude 收到的是 “Fix GitHub issue 123 following our coding standards...”。想按位置取單個引數，用 $ARGUMENTS[N] 或更短的 $N。如果呼叫時帶了引數，但內容裡沒有任何佔位符接收它，Claude Code 會在 skill 內容末尾追加 ARGUMENTS: <your input>，讓 Claude 仍然看到你輸入的內容。

skill 目錄裡可以放多個檔案。這樣 SKILL.md 只寫要點，詳細的參考資料讓 Claude 需要時再讀：

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

要在 SKILL.md 裡引用這些檔案，讓 Claude 知道每個檔案裡有什麼、什麼時候該載入：

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

文件的提示：SKILL.md 保持在 500 行以內，把詳細的參考材料移到單獨的檔案裡。

怎麼寫好 description

• 寫使用者自然會說的關鍵詞。文件的排查第一條就是檢查 description 裡有沒有使用者會自然說出的詞。上面的例子把“什麼時候用”直接寫進去：“Use when the user asks what changed, wants a commit message, or asks to review their diff.”
• 把最主要的用途放在最前面。description 和 when_to_use 合起來在 skill 列表裡最多保留 1,536 個字元，超出的部分會被截斷。
• 如果描述太寬，就寫具體。skill 觸發得太頻繁時，文件的第一條建議是讓 description 更具體。
• 尖括號會被轉義。description 和 when_to_use 裡的 < 和 > 會顯示成 < 和 >。要顯示 <branch> 這樣的佔位符，改用方括號 [branch]，或者把它挪到單獨的 argument-hint 行。
• 正文要簡短。skill 一旦載入，內容會在後續輪次一直留在上下文裡，每一行都是持續的 token 成本；寫“做什麼”，而不是敘述“怎麼做”或“為什麼”。

常見問題排查

skill 沒有觸發

• 檢查 description 裡有沒有使用者會自然說出的關鍵詞。
• 確認 skill 出現在 What skills are available? 的回答裡。
• 換個說法，讓請求更貼近 description。
• 如果 skill 允許使用者呼叫，直接用 /skill-name 呼叫。
• 如果 /skill-name 也不被識別，檢查 Claude Code 是不是拒絕了這個 skill 的名字（零寬空格、控制字元、< 或 > 等字元會導致被拒）。
• 如果 skill 設定了 paths，檢查 Claude 讀取、編輯或寫入的檔案是否在當前工作目錄之內；在目錄之外的檔案（例如同級 git worktree 裡的檔案，即使用 /add-dir 加進來）不會啟用這個 skill。

如果 frontmatter 的 YAML 格式有誤，Claude Code 會以空後設資料載入 skill 正文：/skill-name 仍然能用，但 Claude 沒法按 description 匹配。用 --debug 執行可以看到解析錯誤。查詢 frontmatter 解析失敗的 SKILL.md，可以對 skills 目錄執行 claude plugin validate，例如 claude plugin validate .claude/skills 或 claude plugin validate ~/.claude/skills（需要 Claude Code v2.1.233 或更高版本）。

skill 觸發太頻繁

讓 description 更具體；如果只想手動呼叫，加上 disable-model-invocation: true。

Claude 中途不再遵循 skill

skill 被呼叫時，Claude Code 把它的內容加進對話，之後的輪次不會重新讀取檔案，所以對整個任務都適用的指引，要寫成“每次編輯後執行測試”，而不是“執行測試”。對話被壓縮後，Claude Code 只能保留已呼叫 skill 的開頭，所以把最重要的說明放在 SKILL.md 靠前的位置，必要時重新呼叫一次 skill 來恢復完整內容。必須每次都成立的規則，文件建議移到 hook 裡。

description 被截斷

skill 很多時，Claude Code 會為了符合列表的字元預算而丟掉一部分 description，Claude 匹配請求需要的關鍵詞也就沒了；預算是模型上下文視窗的 1%，從你最少呼叫的 skill 開始丟。執行 /doctor 可以估算列表佔用的上下文，並看到佔用最多的項。

常見問題

來源

• Claude Code：Extend Claude with skills（skill 位置、重名規則、frontmatter 欄位、呼叫控制、引數、輔助檔案、排查）