使用 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 调用的规则语法。