使用 Skills

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
Skills	技能	可複用的能力包。
漸進披露	progressive	按需載入細節。
觸發	trigger	何時被呼叫。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你設計可複用的 Claude Code 技能，按需被正確呼叫。

你是 Claude Code 技能設計顧問。

【角色】
Claude Code 技能設計顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 要沉澱成技能的能力：___
- 觸發場景：___
- 依賴的工具：___
- 個人還是團隊：___
- 經驗水平：___

【工作流程】
1. 識別值得做成技能的能力
2. 用漸進披露組織內容
3. 設計觸發條件
4. 說明依賴和複用
5. 給驗證

【輸出規範】
▌一、值得沉澱的
▌二、漸進披露
▌三、觸發條件
▌四、依賴複用 + 驗證

【硬約束】
- 技能職責清晰可測
- 細節按需載入
- 觸發條件明確
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

Skill 是把“我又要對 Claude 解釋一遍”的內容，變成可複用能力。它不是全域規則，也不是許可權系統，而是按需載入的知識、流程和命令入口。——翔宇

這一章用 16 分鐘換什麼：上一章已經建立擴充套件地圖。現在專門講 Skills。讀完你應該能判斷什麼內容該做成 Skill、Skill 放哪裡、怎麼觸發、怎麼帶引數、怎麼注入動態上下文、怎麼預批准工具，以及什麼時候該改用 Hook、MCP 或 Subagent。

1. Skill 解決什麼問題

Claude Code 官方定義很直接：當你反覆把同一段說明、checklist 或多步流程粘進對話，或者 CLAUDE.md 某一段已經長成流程，而不再是事實，就應該考慮 Skill。

適合做成 Skill：

釋出流程。
PR review checklist。
除錯 playbook。
遷移步驟。
API 風格指南。
大段參考資料。
帶模板、示例、指令碼的工作流。
你想用 /name 直接呼叫的任務。

不適合做成 Skill：

每次會話都必須知道的專案規則。
必須確定性執行的動作。
外部系統連線。
許可權邊界。
一次性任務背景。
還沒有重複出現過的臨時提示詞。

第一性原理：CLAUDE.md 放 always-on 專案事實；Skill 放按需知識和流程；Hook 做確定性自動化；MCP 連線外部系統。

flowchart TD
    Input["一段說明或流程"]
    Always["每次會話都要知道？"]
    Repeat["是否反覆使用？"]
    Force["是否必須每次執行？"]
    External["是否需要外部系統？"]
    Long["是否很長或帶參考資料？"]

    ClaudeMd["CLAUDE.md"]
    Skill["Skill"]
    Hook["Hook"]
    MCP["MCP"]
    Chat["直接在對話裡說"]

    Input --> Always
    Always -->|是| ClaudeMd
    Always -->|否| Repeat
    Repeat -->|否| Chat
    Repeat -->|是| Force
    Force -->|是| Hook
    Force -->|否| External
    External -->|是| MCP
    External -->|否| Long
    Long -->|是| Skill
    Long -->|否| Skill

    style Skill fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style ClaudeMd fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Hook fill:#fee2e2,stroke:#ef4444,stroke-width:2px

2. Skill 和 command 的關係

Claude Code 現在把自定義 commands 合併進 Skills 機制。

也就是說：

.claude/commands/deploy.md 仍然可用。
.claude/skills/deploy/SKILL.md 也會建立 /deploy。
如果 skill 和 command 同名，skill 優先。
新寫內容優先用 Skill，因為它支援目錄結構、frontmatter、附屬檔案、自動載入和更細的呼叫控制。

內建命令和 bundled skills 要分開看：

/help、/compact、/mcp、/permissions 這類是 CLI 內建邏輯。
/debug、/simplify、/batch、/loop、/claude-api 這類是官方 bundled skills，屬於 prompt-based 工作流。

一句話判斷：你自己寫可複用 prompt 或流程，用 Skill；你要操作 Claude Code 客戶端狀態，用內建 command。

3. Skill 的最小結構

一個 Skill 至少是一個目錄和一個 SKILL.md：

summarize-changes/
  SKILL.md

最小 SKILL.md：

---
description: Summarizes uncommitted changes and flags risky edits. 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 diff in two or three bullets, then list risks such as missing tests, hardcoded values, or unclear error handling. If the diff is empty, say there are no uncommitted changes.

這個例子裡最重要的不是格式，而是三件事：

description 告訴 Claude 什麼時候該用它。
Markdown 正文告訴 Claude 怎麼執行。
! 動態上下文把目前 diff 注入 Skill 內容。

直接呼叫：

/summarize-changes

也可以讓 Claude 自動判斷：

What did I change?

description 是觸發器：寫 Skill 時不要只寫“幫助處理程式碼”。要寫清使用者會怎麼問、什麼時候該用。

4. Skill 放在哪裡

Skill 的路徑決定作用域。

Enterprise / managed：組織級下發，所有使用者可用。
Personal：~/.claude/skills/<skill-name>/SKILL.md，你的所有專案可用。
Project：.claude/skills/<skill-name>/SKILL.md，目前專案可用，可以提交到版本控制。
Plugin：<plugin>/skills/<skill-name>/SKILL.md，外掛啟用時可用。

同名優先順序：

Enterprise / managed
Personal
Project
Plugin namespaced skill

Plugin skill 會帶 namespace，例如：

/my-plugin:review

這樣它不會和個人或專案裡的 /review 衝突。

project Skill 要審查：儲存庫裡的 Skill 可能定義 allowed-tools 或動態 shell 注入。接受 workspace trust 前要先看 SKILL.md。

5. 自動發現和熱更新

Claude Code 會 watch skill 目錄。

這些位置裡的新增、修改、刪除通常會在目前會話裡生效，不需要重啟：

~/.claude/skills/
專案 .claude/skills/
--add-dir 目錄內的 .claude/skills/

但有一個例外：如果會話啟動時頂層 skills 目錄根本不存在，後來新建這個頂層目錄，通常需要重啟 Claude Code 才能 watch。

Monorepo 裡，Claude Code 還會自動發現巢狀目錄裡的 .claude/skills/。例如你編輯：

packages/frontend/src/App.tsx

Claude Code 會查詢類似：

packages/frontend/.claude/skills/

這適合讓每個 package 擁有自己的 Skill。

--add-dir 的特殊點：一般 .claude/ 設定不會從 added directory 自動發現，但 .claude/skills/ 是例外，會自動載入。

6. 推薦目錄結構

簡單 Skill 只要 SKILL.md。

複雜 Skill 可以拆檔案：

my-skill/
  SKILL.md
  reference.md
  examples.md
  templates/
    output.md
  scripts/
    helper.sh

分工建議：

SKILL.md：總入口、觸發說明、執行步驟、附屬檔案導航。
reference.md：長參考資料，需要時再讀。
examples.md：示例輸入輸出。
templates/：可複用模板。
scripts/：可執行輔助指令碼。

官方建議 SKILL.md 控制在 500 行以內。長參考資料要拆出去，並在 SKILL.md 裡說明什麼時候讀。

SKILL.md 不是資料堆放處：它應該像入口和操作手冊，長內容放附屬檔案。

7. 兩類 Skill：參考型和任務型

參考型 Skill 給 Claude 增加知識。

適合：

API 設計規範。
業務術語。
資料模型。
團隊風格。
框架約定。

它通常允許 Claude 自動載入，因為它沒有副作用。

任務型 Skill 讓 Claude 執行流程。

適合：

/deploy
/commit
/release
/review-pr
/migrate-component

任務型 Skill 可能有副作用，尤其涉及提交、釋出、通知、寫外部系統時，應該手動觸發。

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

Deploy $ARGUMENTS:

1. Run tests.
2. Build the application.
3. Push to the deployment target.
4. Verify the deployment.

高風險流程手動觸發：部署、提交、發訊息、刪資源，不要讓 Claude 自動決定什麼時候執行。

8. Frontmatter 欄位怎麼用

常用欄位：

name：顯示名。省略時使用目錄名。建議小寫、數字、連字元。
description：Skill 做什麼、什麼時候用。推薦必寫。
when_to_use：補充觸發場景和示例請求。
argument-hint：在 autocomplete 裡提示引數格式。
arguments：宣告命名位置引數。
disable-model-invocation：設為 true 後，Claude 不會自動呼叫，只能使用者手動呼叫。
user-invocable：設為 false 後，不顯示在 / 選單，適合背景知識。
allowed-tools：Skill 啟用時預批准哪些工具。
model：Skill 啟用時臨時指定模型。
effort：Skill 啟用時臨時指定 reasoning effort。
context：設為 fork 時，在 subagent 隔離上下文執行。
agent：context: fork 時指定使用哪個 subagent。
hooks：Skill 生命週期內的 scoped hooks。
paths：限制自動觸發時匹配哪些檔案路徑。
shell：動態 shell 注入使用的 shell，預設 bash，也可配 powershell。

新手只需要先記四個：description、disable-model-invocation、allowed-tools、context: fork。

9. description 要短、準、靠前

Claude 會在會話中看到 skill names 和 descriptions，用它們判斷什麼時候載入 Skill。

官方限制裡有兩個關鍵數字：

description + when_to_use 的組合文本，在 skill listing 中最多保留 1,536 字元。
如果 Skill 很多，總描述預算會動態縮短；預算按上下文視窗 1% 計算，fallback 是 8,000 characters。

所以 description 寫法要像檢索關鍵詞：

弱：

description: Helpful workflow for development tasks.

強：

description: Reviews a pull request diff for security, missing tests, risky migrations, and unclear error handling. Use when the user asks to review a PR or inspect uncommitted changes.

關鍵詞放前面：如果描述很長，後半段可能被截斷。觸發詞、任務型別、關鍵物件要放第一句。

10. Invocation 控制：誰能呼叫

預設，Skill 可以被兩類主體呼叫：

你手動輸入 /skill-name。
Claude 根據 description 自動呼叫。

兩個 frontmatter 欄位控制呼叫方式：

disable-model-invocation: true：Claude 不能自動呼叫；使用者仍可手動呼叫。
user-invocable: false：使用者選單隱藏；Claude 仍可自動呼叫。

適合 disable-model-invocation: true：

/commit
/deploy
/send-slack-message
/publish
/delete-resource

適合 user-invocable: false：

legacy system 背景資料。
只想讓 Claude 在相關任務裡自動載入的領域知識。
使用者直接呼叫沒有意義的參考內容。

user-invocable 不是許可權邊界：它只控制 / 選單可見性。要阻止 Claude 程式化呼叫，使用 disable-model-invocation: true 或 permissions。

11. Skill 內容生命週期

Skill 不是每回合都重新讀。

官方說明：

會話啟動時，Claude 看到 skill names 和 descriptions。
Skill 被呼叫時，渲染後的 SKILL.md 內容作為一條訊息進入對話。
進入對話後，它會在本會話裡保留。
後續回合 Claude Code 不會自動重新讀取 skill 檔案。

Compaction 後也有預算：

最近呼叫過的 Skill 會被重新附加到 summary 後。
每個 Skill 保留前 5,000 tokens。
所有重新附加的 Skills 共用 25,000 tokens 預算。
從最近呼叫的 Skill 開始填充預算，較早呼叫的可能被丟掉。

改了 Skill 後重新呼叫：如果你在會話中修改了 SKILL.md，舊呼叫內容已經在上下文裡。要讓新內容生效，重新呼叫 Skill。

12. 引數：`$ARGUMENTS`、`$0` 和命名引數

手動呼叫 Skill 時，可以傳引數：

/fix-issue 123

Skill 裡可以使用：

$ARGUMENTS：完整引數字串。
$ARGUMENTS[0]：第一個引數。
$0：第一個引數的短寫。
$name：命名引數。

例子：

---
name: migrate-component
description: Migrate a component from one framework to another.
arguments: [component, from, to]
---

Migrate `$component` from `$from` to `$to`.
Preserve behavior and tests.

呼叫：

/migrate-component SearchBar React Vue

如果 Skill 內容裡沒有 $ARGUMENTS，但使用者傳了引數，Claude Code 會在內容末尾追加 ARGUMENTS: <your input>，避免引數丟失。

命名引數適合複雜流程：比 $0、$1 更不容易讀錯。

13. 動態上下文注入：`!` 命令

Skill 可以在 Claude 看到內容前先執行 shell 命令。

Inline 形式：


## Pull request context

- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

多行形式：


## Environment

```!
node --version
npm --version
git status --short
```

執行順序：

Claude Code 先執行 ! 命令。
命令輸出替換佔位內容。
Claude 只看到渲染後的最終 Skill 內容。

這不是 Claude 自己決定執行命令，而是 Skill 載入前的預處理。

動態上下文有安全邊界：它能執行 shell 命令。對不可信 project / plugin Skill，要先審查 ! 命令。

14. 停用 Skill shell 注入

如果組織或專案不想允許 Skill 自動執行 shell 注入，可以在 settings 裡設定：

{
  "disableSkillShellExecution": true
}

效果：

使用者、專案、外掛、additional-directory 來源的 Skill 和 custom command 不再執行 ! 命令。
對應位置會被替換成 [shell command execution disabled by policy]。
Bundled skills 和 managed skills 不受這個欄位影響。
這個設定最適合放到 managed settings，因為使用者不能覆蓋。

不信任 Skill 時先關 shell 注入：尤其是團隊首次引入第三方 plugin 或陌生專案 Skill 時。

15. `allowed-tools`：預批准，不是限制

allowed-tools 的作用是：當 Skill 啟用時，列出的工具可以無需每次提示。

例子：

---
name: commit
description: Stage and commit the current changes.
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Commit the current changes following the project commit style.

關鍵邊界：

allowed-tools 是 allow，不是 deny。
它不會限制其他工具不可用。
其他工具仍受你的 permissions 管。
要阻止工具，要在 settings permissions 裡寫 deny。
Project Skill 的 allowed-tools 會在你接受 workspace trust 後生效。

不要用 allowed-tools 做安全沙盒：它只減少提示，不負責禁止。禁止能力要寫 permissions deny。

16. Skill 許可權規則

你可以在 permissions 裡控制 Claude 是否能呼叫 Skills。

停用所有 Skill tool：

Skill

允許精確 Skill：

Skill(commit)

允許帶引數字首：

Skill(review-pr *)

拒絕某個 Skill：

Skill(deploy *)

規則語法：

Skill(name)：精確匹配。
Skill(name *)：匹配該 Skill 加任意引數。

高風險 Skill 雙保險：frontmatter 寫 disable-model-invocation: true，permissions 再對危險 Skill 做 ask 或 deny。

17. `context: fork`：在 subagent 裡執行 Skill

有些 Skill 會讀大量檔案、跑長分析、查很多資料。它們不適合汙染主會話。

這時可以加：

context: fork
agent: Explore

完整例子：

---
name: deep-research
description: Research a codebase topic thoroughly and return concise findings.
context: fork
agent: Explore
---

Research `$ARGUMENTS` thoroughly:

1. Find relevant files.
2. Read and analyze the code.
3. Summarize findings with specific file references.

執行時：

建立隔離上下文。
Skill 內容成為 subagent 的任務。
agent 決定執行環境、工具和許可權。
最後只把摘要返回主會話。

如果不寫 agent，預設使用 general-purpose。

context: fork 需要任務，不是資料：如果 Skill 只是“這些是 API 規範”，forked subagent 收到後沒有具體任務，通常不會產生有用結果。

18. Subagent 裡使用 Skills 的另一種方向

Skill 和 Subagent 有兩個方向：

Skill 設定 context: fork：Skill 自己啟動一個 subagent，Skill 內容就是任務。
Subagent frontmatter 設定 skills：subagent 啟動時預載入指定 Skills，把它們當參考資料。

區別：

前者適合 /deep-research topic 這種可呼叫任務。
後者適合定義一個專門 agent，例如 security reviewer，並讓它常駐載入 security skill。

任務驅動用 context: fork；角色驅動用 subagent + skills。

19. `paths`：限制自動觸發範圍

Skill 也可以設定 paths：

paths:
  - "src/api/**/*.ts"
  - "tests/**/*.test.ts"

這樣 Claude 只會在處理匹配檔案時自動考慮這個 Skill。

適合：

API style skill 只在 API 檔案生效。
React migration skill 只在前端目錄生效。
Test writing skill 只在測試檔案生效。
Docs writing skill 只在 docs/** 生效。

路徑觸發能降噪：如果 Skill 只服務某類檔案，不要讓它在所有任務裡競爭觸發。

20. 指令碼和視覺輸出

Skill 可以包含指令碼，不限語言。Claude 負責理解任務和編排，指令碼負責確定性執行。

常見用途：

生成 HTML 報告。
視覺化程式碼結構。
統計測試覆蓋。
生成依賴圖。
校驗輸出檔案。
批次轉換格式。

指令碼里引用 Skill 路徑時，用：

${CLAUDE_SKILL_DIR}

這樣無論 Skill 在 personal、project 還是 plugin 作用域，都能找到自己的附屬檔案。

指令碼要可審查、可復跑：高頻 Skill 不要把關鍵邏輯藏在不可讀指令碼里。指令碼應該有清楚輸入、輸出和失敗行為。

21. 分享 Skill 的三種方式

Skill 可以按受眾分發：

Project Skill：提交 .claude/skills/ 到儲存庫，服務目前專案團隊。
Plugin Skill：放進 plugin 的 skills/ 目錄，適合跨儲存庫或外部分發。
Managed Skill：組織級下發，適合企業標準能力。

選擇建議：

只服務一個儲存庫：Project。
你自己所有專案都用：Personal。
多儲存庫團隊複用：Plugin。
組織強制統一：Managed。

別把還沒穩定的 Skill 做成 Plugin：先在專案裡跑順，再分發。Plugin 化會放大維護成本。

22. 寫一個好 Skill 的結構

23. 常見故障：Skill 沒觸發

按這個順序查：

問 Claude：What skills are available?
確認目錄是 <skill-name>/SKILL.md。
檢查 description 是否包含使用者自然會說的關鍵詞。
檢查是否寫了 disable-model-invocation: true。
檢查是否寫了 paths，但目前檔案不匹配。
手動呼叫 /skill-name 測試。
如果是新建頂層 skills 目錄，重啟 Claude Code。
如果 descriptions 很多，檢查是否被預算截斷。

先手動呼叫：如果 /skill-name 可以執行，問題通常在 description、paths 或自動觸發條件。

24. 常見故障：Skill 觸發太頻繁

常見原因：

description 太泛。
關鍵詞覆蓋太多工。
參考型 Skill 寫成了“所有開發任務都適用”。
沒有 paths 限制。
高風險任務沒設 disable-model-invocation: true。

修法：

把 description 改具體。
增加 when_to_use 和反例。
對檔案型 Skill 加 paths。
對手動任務加 disable-model-invocation: true。
必要時用 permissions 限制 Skill(name *)。

觸發太頻繁比不觸發更危險：它會汙染上下文，還可能讓 Claude 在錯誤場景套用流程。

25. 常見故障：Skill 不再影響行為

可能原因：

Skill 已呼叫，但後續任務方向變了。
Skill 太長，compaction 後只保留前 5,000 tokens。
一次會話呼叫了太多 Skills，舊 Skill 被預算擠掉。
Skill 指令不夠具體，Claude 選擇了其他工具或路徑。
你修改了檔案，但目前會話裡的舊 Skill 內容還在。

處理方式：

重新呼叫 Skill。
把關鍵規則放在 Skill 前半部分。
縮短 SKILL.md，把長參考拆到附屬檔案。
把必須執行的動作改成 Hook。
把安全邊界放到 permissions。

Skill 不是永遠常駐的絕對指令：它進入上下文，但仍受上下文壓縮、任務變化和模型判斷影響。

26. 自檢清單

學完這一章，你應該能做到：

我能判斷一段內容該進 CLAUDE.md 還是 Skill。
我知道 Skill body 只在使用時載入，description 會參與觸發判斷。
我知道 custom commands 已併入 Skills，舊 .claude/commands/ 仍可用。
我知道 personal、project、plugin、managed Skill 的作用域和優先順序。
我能寫出一個最小 SKILL.md。
我知道 disable-model-invocation 和 user-invocable 的區別。
我知道 allowed-tools 是預批准，不是限制。
我知道怎樣用 permissions 控制 Skill(name)。
我知道 ! 動態上下文會先執行 shell 命令。
我知道 context: fork 適合任務型 Skill，不適合純參考資料。
我知道 Skill 觸發失敗或觸發過多該怎麼排查。

27. 術語速查

Skill：Claude Code 的可複用知識、流程或命令入口。
SKILL.md：Skill 的主說明檔案。
description：Claude 判斷何時使用 Skill 的核心文本。
when_to_use：補充觸發場景和示例請求。
disable-model-invocation：禁止 Claude 自動呼叫 Skill。
user-invocable：控制 Skill 是否顯示在使用者 / 選單。
allowed-tools：Skill 啟用時預批准的工具。
context: fork：讓 Skill 在隔離 subagent 上下文執行。
agent：context: fork 時使用的 subagent 型別。
paths：限制 Skill 自動觸發的檔案路徑。
! dynamic context：Skill 載入前執行命令並把輸出注入內容。
${CLAUDE_SKILL_DIR}：Skill 所在目錄路徑。
$ARGUMENTS：使用者呼叫 Skill 時傳入的完整引數。
Skill(name)：permissions 裡控制 Skill 呼叫的規則語法。