使用 Skills

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 呼叫的規則語法。