Claude Code Skills 完整指南 - 创建 / 管理 / 共享 AI 工作流

Skills 扩展了 Claude 能做的事情。创建一个 SKILL.md 文件，其中包含说明，Claude 会将其添加到其工具包中。Claude 在相关时使用 skills，或者你可以使用 /skill-name 直接调用一个。

当你不断将相同的说明、检查清单或多步骤程序粘贴到聊天中时，或者当 CLAUDE.md 的一部分已经演变成程序而不是事实时，创建一个 skill。与 CLAUDE.md 内容不同，skill 的正文仅在使用时加载，因此长参考资料在你需要它之前几乎不花费任何成本。

ℹ️ 自定义命令已合并到 skills 中。.claude/commands/deploy.md 中的文件和 .claude/skills/deploy/SKILL.md 中的 skill 都会创建 /deploy 并以相同的方式工作。你现有的 .claude/commands/ 文件继续工作。Skills 添加了可选功能：支持文件的目录、控制你或 Claude 是否调用它们的 frontmatter，以及 Claude 在相关时自动加载它们的能力。

Claude Code skills 遵循 Agent Skills 开放标准。Claude Code 使用额外功能扩展了该标准，如调用控制、subagent 执行和动态上下文注入。

捆绑 skills

Claude Code 包括一组捆绑 skills，在每个会话中都可用，包括 /simplify、/batch、/debug、/loop 和 /claude-api。与大多数内置命令不同，内置命令直接执行固定逻辑，捆绑 skills 是基于提示的：它们为 Claude 提供详细的说明，让它使用其工具来编排工作。你调用捆绑 skills 的方式与调用任何其他 skill 相同，输入 / 后跟 skill 名称。

入门

创建你的第一个 skill

此示例创建一个 skill，用于总结你的 git 仓库中未提交的更改，并标记任何风险的内容。

步骤 1：创建 skill 目录

在你的个人 skills 文件夹中为 skill 创建一个目录。个人 skills 在你的所有项目中都可用。

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

步骤 2：编写 SKILL.md

每个 skill 都需要一个 SKILL.md 文件，包含两部分：YAML frontmatter（在 --- 标记之间）告诉 Claude 何时使用该 skill，以及包含 Claude 在调用该 skill 时遵循的说明的 markdown 内容。目录名称变成你输入的命令，description 帮助 Claude 决定何时自动加载该 skill。

将此保存到 ~/.claude/skills/summarize-changes/SKILL.md：

---
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.

!`git diff HEAD` 这一行使用动态上下文注入：Claude Code 运行该命令，并在 Claude 看到 skill 内容之前将该行替换为其输出，因此说明会随着当前 diff 已内联而到达。

步骤 3：测试 skill

打开一个 git 项目，对任何文件进行小的编辑，并通过运行 claude 启动 Claude Code。你可以通过两种方式测试该 skill。

让 Claude 自动调用它，通过询问与描述匹配的内容：

What did I change?

或直接使用 skill 名称调用它：

/summarize-changes

无论哪种方式，Claude 都应该用你的编辑的简短摘要和风险列表来响应。

Skills 的位置

你存储 skill 的位置决定了谁可以使用它：

位置	路径	适用于
企业	请参阅托管设置	你的组织中的所有用户
个人	~/.claude/skills/<skill-name>/SKILL.md	你的所有项目
项目	.claude/skills/<skill-name>/SKILL.md	仅此项目
插件	<plugin>/skills/<skill-name>/SKILL.md	启用插件的位置

当 skills 在各个级别共享相同的名称时，企业覆盖个人，个人覆盖项目。插件 skills 使用 plugin-name:skill-name 命名空间，因此它们不能与其他级别冲突。如果你在 .claude/commands/ 中有文件，它们的工作方式相同，但如果 skill 和命令共享相同的名称，skill 优先。

实时变更检测

Claude Code 监视 skill 目录的文件变更。在 ~/.claude/skills/、项目 .claude/skills/ 或 --add-dir 目录内的 .claude/skills/ 中添加、编辑或删除 skill 会在当前会话中生效，无需重新启动。

从嵌套目录自动发现

当你在子目录中处理文件时，Claude Code 会自动从嵌套的 .claude/skills/ 目录中发现 skills。例如，如果你正在编辑 packages/frontend/ 中的文件，Claude Code 也会在 packages/frontend/.claude/skills/ 中查找 skills。

每个 skill 都是一个以 SKILL.md 作为入口点的目录：

my-skill/
├── SKILL.md           # 主要说明（必需）
├── template.md        # Claude 要填写的模板
├── examples/
│   └── sample.md      # 显示预期格式的示例输出
└── scripts/
    └── validate.sh    # Claude 可以执行的脚本

SKILL.md 包含主要说明，是必需的。其他文件是可选的。

配置 skills

Skills 通过 SKILL.md 顶部的 YAML frontmatter 和随后的 markdown 内容进行配置。

Skill 内容的类型

Skill 文件可以包含任何说明，但思考你想如何调用它们有助于指导要包含的内容：

参考内容添加 Claude 应用于你当前工作的知识。约定、模式、风格指南、领域知识。此内容内联运行，以便 Claude 可以将其与你的对话上下文一起使用。

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

任务内容为 Claude 提供特定操作的分步说明，如部署、提交或代码生成。这些通常是你想使用 /skill-name 直接调用的操作，而不是让 Claude 决定何时运行它们。添加 disable-model-invocation: true 以防止 Claude 自动触发它。

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

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

保持主体本身简洁。一旦 skill 加载，其内容在整个会话中保持在上下文中，因此每一行都是一个重复的令牌成本。

Frontmatter 参考

除了 markdown 内容外，你可以使用 SKILL.md 文件顶部 --- 标记之间的 YAML frontmatter 字段来配置 skill 行为：

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

所有字段都是可选的。建议使用 description，以便 Claude 知道何时使用该 skill。

字段	必需	描述
name	否	Skill 的显示名称。如果省略，使用目录名称。仅小写字母、数字和连字符（最多 64 个字符）。
description	推荐	Skill 的功能以及何时使用它。组合的 description 和 when_to_use 文本在技能列表中被截断为 1,536 个字符以减少上下文使用。
when_to_use	否	关于 Claude 何时应该调用该 skill 的额外上下文。
argument-hint	否	自动完成期间显示的提示，指示预期的参数。示例：[issue-number]。
arguments	否	用于 skill 内容中 $name 替换的命名位置参数。
disable-model-invocation	否	设置为 true 以防止 Claude 自动加载此 skill。默认值：false。
user-invocable	否	设置为 false 以从 / 菜单中隐藏。默认值：true。
allowed-tools	否	当此 skill 处于活动状态时，Claude 可以使用而无需请求权限的工具。
model	否	当此 skill 处于活动状态时要使用的模型。
effort	否	当此 skill 处于活动状态时的工作量级别。选项：low、medium、high、xhigh、max。
context	否	设置为 fork 以在分叉的 subagent 上下文中运行。
agent	否	当设置 context: fork 时要使用的 subagent 类型。
hooks	否	限定于此 skill 生命周期的 hooks。
paths	否	Glob 模式，限制何时激活此 skill。
shell	否	用于此 skill 中 !`command` 和 ```! 块的 shell。接受 bash（默认）或 powershell。

可用的字符串替换

Skills 支持 skill 内容中动态值的字符串替换：

变量	描述
$ARGUMENTS	调用 skill 时传递的所有参数。
$ARGUMENTS[N]	按 0 基索引访问特定参数，如 $ARGUMENTS[0] 表示第一个参数。
$N	$ARGUMENTS[N] 的简写，如 $0 表示第一个参数。
$name	在 arguments frontmatter 列表中声明的命名参数。
${CLAUDE_SESSION_ID}	当前会话 ID。
${CLAUDE_EFFORT}	当前工作量级别：low、medium、high、xhigh 或 max。
${CLAUDE_SKILL_DIR}	包含 skill 的 SKILL.md 文件的目录。

使用替换的示例：

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

添加支持文件

Skills 可以在其目录中包含多个文件。这使 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 行以下。将详细的参考资料移到单独的文件中。

控制谁调用 skill

默认情况下，你和 Claude 都可以调用任何 skill。你可以输入 /skill-name 直接调用它，Claude 可以在与你的对话相关时自动加载它。两个 frontmatter 字段让你限制这一点：

• disable-model-invocation: true：只有你可以调用该 skill。
• user-invocable: false：只有 Claude 可以调用该 skill。

此示例创建一个只有你可以触发的部署 skill：

---
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

以下是两个字段如何影响调用和上下文加载：

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

Skill 内容生命周期

当你或 Claude 调用一个 skill 时，呈现的 SKILL.md 内容作为单个消息进入对话，并在会话的其余部分保持在那里。Claude Code 不会在后续轮次重新读取 skill 文件。

自动压缩在令牌预算内转发调用的 skills。当对话被总结以释放上下文时，Claude Code 在总结后重新附加每个 skill 的最新调用，保留前 5,000 个令牌。重新附加的 skills 共享 25,000 个令牌的组合预算。

为 skill 预先批准工具

allowed-tools 字段在 skill 处于活动状态时授予对列出的工具的权限，因此 Claude 可以使用它们而无需提示你获得批准。

此 skill 让 Claude 在你调用它时运行 git 命令而无需每次使用批准：

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

将参数传递给 skills

你和 Claude 都可以在调用 skill 时传递参数。参数可通过 $ARGUMENTS 占位符获得。

---
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：

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

运行 /migrate-component SearchBar React Vue 会将 $0 替换为 SearchBar，$1 替换为 React，$2 替换为 Vue。

高级模式

注入动态上下文

!`<command>` 语法在将 skill 内容发送给 Claude 之前运行 shell 命令。命令输出替换占位符，因此 Claude 接收实际数据，而不是命令本身。

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

当此 skill 运行时：

1. 每个 !`<command>` 立即执行（在 Claude 看到任何内容之前）
2. 输出替换 skill 内容中的占位符
3. Claude 接收带有实际 PR 数据的完全呈现的提示

对于多行命令，使用以 ```! 开头的围栏代码块而不是内联形式：

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

要禁用来自用户、项目、插件或其他目录源的 skills 和自定义命令的此行为，请在设置中设置 "disableSkillShellExecution": true。

💡 要在 skill 运行时请求更深入的推理，在 skill 内容中的任何地方包含 ultrathink。

在 subagent 中运行 skills

当你想让 skill 在隔离中运行时，在你的 frontmatter 中添加 context: fork。skill 内容变成驱动 subagent 的提示。它将无法访问你的对话历史。

⚠️ context: fork 仅对具有明确说明的 skills 有意义。

Skills 和 subagents 以两个方向协同工作：

方法	系统提示	任务	也加载
带有 context: fork 的 Skill	来自代理类型（Explore、Plan 等）	SKILL.md 内容	CLAUDE.md
带有 skills 字段的 Subagent	Subagent 的 markdown 正文	Claude 的委派消息	预加载的 skills + CLAUDE.md

示例：使用 Explore 代理的研究 skill

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

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

当此 skill 运行时：

1. 创建一个新的隔离上下文
2. Subagent 接收 skill 内容作为其提示
3. agent 字段确定执行环境（模型、工具和权限）
4. 结果被总结并返回到你的主对话

限制 Claude 的 skill 访问

默认情况下，Claude 可以调用任何没有设置 disable-model-invocation: true 的 skill。

控制 Claude 可以调用哪些 skills 的三种方式：

通过在 /permissions 中拒绝 Skill 工具来禁用所有 skills：

# Add to deny rules:
Skill

使用权限规则允许或拒绝特定 skills：

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

权限语法：Skill(name) 用于精确匹配，Skill(name *) 用于带有任何参数的前缀匹配。

通过在其 frontmatter 中添加 disable-model-invocation: true 来隐藏单个 skills。这会从 Claude 的上下文中完全删除该 skill。

从设置覆盖 skill 可见性

skillOverrides 设置从你的设置控制 skill 可见性，而不是从 skill 自己的 frontmatter。/skills 菜单为你编写它：突出显示一个 skill 并按 Space 循环切换状态，然后按 Enter 保存到 .claude/settings.local.json。

值	列出给 Claude	在 / 菜单中
"on"	名称和描述	是
"name-only"	仅名称	是
"user-invocable-only"	隐藏	是
"off"	隐藏	隐藏

skillOverrides 中不存在的 skill 被视为 "on"：

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

共享 skills

Skills 可以根据你的受众在不同范围内分发：

• 项目 skills：将 .claude/skills/ 提交到版本控制
• 插件：在你的插件中创建 skills/ 目录
• 托管：通过托管设置部署组织范围内

故障排除

Skill 未触发

如果 Claude 在预期时不使用你的 skill：

1. 检查描述是否包含用户会自然说的关键字
2. 验证 skill 是否出现在 What skills are available? 中
3. 尝试重新表述你的请求以更接近描述
4. 如果 skill 是用户可调用的，使用 /skill-name 直接调用它

Skill 触发过于频繁

如果 Claude 在你不想要时使用你的 skill：

1. 使描述更具体
2. 如果你只想手动调用，添加 disable-model-invocation: true

Skill 描述被截断

Skill 描述被加载到上下文中，以便 Claude 知道什么可用。所有 skill 名称始终包括，但如果你有许多 skills，描述会被缩短以适应字符预算。

要提高限制，设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量。要为其他 skills 释放预算，在 skillOverrides 中将低优先级条目设置为 "name-only"。

相关资源

• Subagents：将任务委派给专门的代理
• Memory：管理 CLAUDE.md 文件以获得持久上下文

---

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。