Skills：扩展 Claude 的能力

Claude Code Skills 通过 SKILL.md 文件为 Claude 添加可复用的知识和工作流。与始终加载的 CLAUDE.md 不同，Skills 按需加载——Claude 根据描述自动触发，或你用 /技能名 手动调用。一个 Skill 可以是参考资料（API 规范、代码约定），也可以是可执行的多步骤工作流（部署、提交、修复 Issue）。Claude Code 内置了 /simplify、/batch、/debug、/loop 等 bundled skills。自定义技能放在 .claude/skills/ 或 ~/.claude/skills/ 目录中，每个技能是一个包含 SKILL.md 的子目录。

Skills 是 Claude Code 的能力扩展机制。每个 Skill 是一个 SKILL.md 文件（加上可选的附属文件），告诉 Claude 什么时候该做什么、怎么做。Skills 只在被调用或匹配到相关请求时加载，不会浪费上下文空间。

Claude Code Skills 遵循 Agent Skills 开放标准，跨 AI 工具通用。Claude Code 在此基础上扩展了调用控制、子代理执行和动态上下文注入等功能。

内置技能（Bundled Skills）

Claude Code 内置了一批技能，每次会话都可使用：/simplify、/batch、/debug、/loop、/claude-api 等。与内置命令不同，这些技能基于 prompt 驱动，Claude 会调度其工具来完成工作。在命令参考中可以看到所有内置命令和技能，技能项在 Purpose 列标注 Skill。

技能存储位置

位置	路径	适用范围
企业托管	详见托管设置	组织所有用户
用户个人	~/.claude/skills/<skill-name>/SKILL.md	你的所有项目
项目级	.claude/skills/<skill-name>/SKILL.md	当前项目
插件	<plugin>/skills/<skill-name>/SKILL.md	插件启用处

同名技能，高优先级位置优先：企业 > 个人 > 项目。插件技能使用 plugin-name:skill-name 命名空间，避免冲突。

实时检测：Claude Code 自动监视技能目录的变化，添加、编辑或删除技能无需重启即可生效。但创建一个新的顶层技能目录需要重启 Claude Code 才会被监视。

monorepo 支持：在子目录中工作时，Claude Code 自动发现嵌套的 .claude/skills/ 目录（例如 packages/frontend/.claude/skills/）。

目录结构

每个技能是一个子目录，SKILL.md 是必需的入口文件：

my-skill/
├── SKILL.md          # 主指令文件（必需）
├── template.md       # 供 Claude 填写的模板
├── examples/
│   └── sample.md     # 示例输出
└── scripts/
    └── validate.sh   # Claude 可执行的脚本

创建技能

知识型技能（自动触发）

提供 Claude 在当前工作中需要的领域知识，例如 API 规范、代码约定：

---
name: api-conventions
description: 我们服务的 REST API 设计约定
---

写 API 接口时：
- URL 路径使用 kebab-case
- JSON 字段名使用 camelCase
- 列表接口必须包含分页
- 错误响应格式：{ "error": { "code": "...", "message": "..." } }

工作流型技能（手动触发）

打包可复用的多步骤流程，设置 disable-model-invocation: true 防止自动触发：

---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---

分析并修复 GitHub Issue：$ARGUMENTS

1. 用 `gh issue view $ARGUMENTS` 获取 issue 详情
2. 在代码库中搜索相关文件
3. 实现必要的修改
4. 编写并运行测试
5. 创建描述性的 commit
6. 推送并创建 PR

调用方式：/fix-issue 1234，$ARGUMENTS 替换为 1234。

Frontmatter 完整字段参考

所有字段均为可选，只有 description 是推荐必填项：

字段	说明
name	技能唯一标识符。小写字母、数字和连字符（最多 64 字符）。省略时使用目录名。
description	何时使用该技能。Claude 据此决定是否自动加载。建议填写，开头直接给出核心用途。
when_to_use	更多触发条件，追加到 description 之后，合计最多 1,536 字符。
argument-hint	自动补全时显示的参数提示。如 [issue-number] 或 [filename] [format]。
disable-model-invocation	true 则 Claude 不会自动加载，只能 /name 手动调用。默认 false。
user-invocable	false 则从 / 菜单隐藏，Claude 可自动调用，用户不能直接触发。默认 true。
allowed-tools	该技能激活时可免确认使用的工具。空格分隔的字符串或 YAML 列表。
model	该技能激活时使用的模型。
effort	该技能激活时的思考深度，覆盖会话级设置。选项：low、medium、high、max（仅 Opus 4.6）。
context	设为 fork 则在分叉的子代理上下文中运行。
agent	context: fork 时指定使用的子代理类型。
hooks	该技能生命周期 hooks，详见 Hooks 文档。
paths	Glob 路径模式，限定只在 Claude 处理匹配文件时自动触发。逗号分隔字符串或 YAML 列表。
shell	内联 shell 命令使用的 shell：bash（默认）或 powershell。

字符串替换变量

技能内容支持以下动态替换：

变量	说明
$ARGUMENTS	调用时传入的所有参数
$ARGUMENTS[N]	第 N 个参数（0 开始）
$N	$ARGUMENTS[N] 的简写，如 $0、$1
${CLAUDE_SESSION_ID}	当前会话 ID
${CLAUDE_SKILL_DIR}	当前技能的 SKILL.md 所在目录

多词参数用引号包裹：/my-skill "hello world" second 让 $0 为 hello world，$1 为 second。

控制调用方式

两个字段控制谁可以调用技能：

Frontmatter	你可以调用	Claude 可以调用	何时加载到上下文
（默认）	是	是	描述始终在上下文，内容在调用时加载
disable-model-invocation: true	是	否	描述不在上下文，内容在你调用时加载
user-invocable: false	否	是	描述始终在上下文，内容在调用时加载

使用 disable-model-invocation: true：部署、提交、发送消息等有副作用的工作流，你不想让 Claude 自己决定时机。

使用 user-invocable: false：背景知识类技能，如 legacy-system-context，Claude 需要知道，但用户直接 / 触发没有意义。

预批准工具权限

allowed-tools 字段让技能激活时可免确认使用指定工具：

---
name: commit
description: Stage 并提交当前改动
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

这只是预批准，不限制可用工具——所有工具仍可调用，allowed-tools 仅对列出的工具跳过确认提示。

传递参数

---
name: migrate-component
description: 把组件从一个框架迁移到另一个
---

把 $0 组件从 $1 迁移到 $2。
保留所有已有功能和测试。

运行 /migrate-component SearchBar React Vue：$0 = SearchBar，$1 = React，$2 = Vue。

动态上下文注入

用 !`<命令>` 语法在技能内容发送给 Claude 之前执行 shell 命令，输出替换占位符：

---
name: pr-summary
description: 总结 PR 改动
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull Request 上下文
- PR diff：!`gh pr diff`
- PR 评论：!`gh pr view --comments`
- 变更文件：!`gh pr diff --name-only`

## 你的任务
总结这个 pull request...

运行时，三个 !`gh ...` 命令先执行，输出插入到 Claude 看到的内容中。

在子代理中运行技能

设置 context: fork 让技能在独立子代理上下文中运行，不占用主对话的上下文：

---
name: audit
description: 对代码库做安全、性能和风格审查
context: fork
---

并行审查以下方面并汇报：
1. 安全漏洞
2. 性能问题
3. 代码风格

配合 agent 字段指定具体子代理类型（如 agent: Explore）。

添加附属文件

技能目录可以包含多个文件，SKILL.md 保持精简，详细内容按需加载：

my-skill/
├── SKILL.md          # 概览和导航（必需）
├── reference.md      # 详细 API 文档（按需加载）
└── scripts/
    └── helper.py     # 工具脚本（执行，不加载）

在 SKILL.md 中引用附属文件，告诉 Claude 有什么可以读：

## 附加资源

- 完整 API 细节：[reference.md](reference.md)

技能内容的生命周期

技能 SKILL.md 内容在调用后作为一条消息进入对话，并在整个会话中保留。Claude Code 不会在后续回合重新读取文件。

自动压缩（auto-compaction）时，Claude Code 会重新附加最近调用过的技能（保留前 5,000 token），所有技能共用 25,000 token 的预算，从最近调用的技能开始填充。如果技能在压缩后不再生效，重新用 /name 调用一次即可恢复。

Skills vs 其他功能

功能	加载时机	适合
CLAUDE.md	每次会话都加载	时刻需要的规则和约定
Skills	按需（自动或手动）	特定场景的知识和工作流
子代理	独立上下文	需要隔离的复杂任务
Hooks	生命周期事件	确定性自动化（每次都执行）

决策指南：

• 每个会话都需要遵守 → CLAUDE.md
• 偶尔需要的领域知识 → 知识型 Skill
• 可复用的多步骤流程 → 工作流型 Skill（设 disable-model-invocation: true）
• 必须自动执行的动作 → Hooks
• 需要独立探索不污染主上下文 → 子代理

在团队中共享技能

项目级技能（.claude/skills/）可以提交到 git 与团队共享：

git add .claude/skills/
git commit -m "add fix-issue and deploy-staging skills"

用户个人技能（~/.claude/skills/）是机器本地的，不会跨项目共享。

相关资源

• 最佳实践：何时用 Skills vs CLAUDE.md
• 子代理：更强大的代理委托机制
• Hooks：自动化生命周期事件
• 功能概览：所有扩展功能的整体对比

常见问题

Q: Skills 和 CLAUDE.md 有什么区别？

CLAUDE.md 每次会话开始时自动加载，适用于每次都需要的规则。Skills 按需加载，只在被匹配或调用时才进入上下文，节省 token。把反复重复的多步骤流程放 Skills，把"始终要做的事"放 CLAUDE.md。

Q: disable-model-invocation 和 user-invocable 分别适合什么场景？

disable-model-invocation: true 用于有副作用的工作流（部署、发 PR），确保只有你能触发。user-invocable: false 用于背景知识类技能，Claude 需要但用户不会直接用 / 调用。

Q: 技能加载多了会不会撑爆上下文？

技能描述在会话开始时加载，占用极少 token。完整内容只在调用时才加载。设置了 disable-model-invocation: true 的技能在调用前连描述都不加载，上下文开销为零。