ClaudeCode官方教程,智能体技能入门

在 Claude Code 中构建、配置和共享技能——这些可复用的 Markdown 指令会在任务匹配时由 Claude 自动应用。内容涵盖从创建你的第一个技能到团队分发和故障排查的全过程。

什么是技能?

技能是一个markdown文件,它教会Claude如何做某件事一次 之后,Claude会在相关时自动应用这些知识。

技能是指令和资源的文件夹，Claude Code 可以发现并使用它们来更准确地处理任务。每个技能都存放在一个 SKILL.md 文件中，其前言中包含名称和描述。

在 Claude Code 中构建、配置和共享技能——这些可复用的 Markdown 指令会在任务匹配时由 Claude 自动应用。内容涵盖从创建你的第一个技能到团队分发和故障排查的全过程。

什么是技能?

技能是一个markdown文件,它教会Claude如何做某件事一次 之后,Claude会在相关时自动应用这些知识。

技能是指令和资源的文件夹，Claude Code 可以发现并使用它们来更准确地处理任务。每个技能都存放在一个 SKILL.md 文件中，其前言中包含名称和描述。

描述是 Claude 决定是否使用该技能的依据。当你要求 Claude 审查 PR 时，它会将你的请求与可用的技能描述进行匹配，并找到相关的那个。Claude 会读取你的请求，将其与所有可用的技能描述进行比较，并激活匹配的那些。以下是技能前言的样子：

  ---
  name: pr-review
  description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
  ---

在前言的下方,你编写实际的指令,你的审查清单、格式偏好、或者Claude在执行任务时需要知道的任何内容。

技能的存放位置

你可以根据谁需要它们,将技能存在不同的位置:

• 个人技能 存放在 ~/.claude/skills（你的主目录）中。这些技能会跟随你在所有项目中使用——你的提交信息风格、你的文档格式、你喜欢的代码解释方式。

• 项目技能 存放在仓库根目录内的 .claude/skills 中。任何克隆该仓库的人都会自动获得这些技能。团队标准就存放在这里，例如你公司的品牌指南、网页设计偏好的字体和颜色。

在 Windows 上，个人技能存放在 C:/Users/<your-user>/.claude/skills 中。

项目技能会与你的代码一起提交到版本控制中，因此整个团队都能共享它们。

技能vsCLAUD.mdvs斜杠指令

ClaudeCode中有多种方式来制定行为 技能的独特之处在于它们是自动且针对特定任务的。一下是它们的比较:

• CLAUDDE.md文件会加载到每次对话中。如果你希望Claude始终使用TypeScript严格模式,那应该将这个规约写在CLAUDE.md中。

• 技能 在匹配你的请求时按需加载 Claude最初只加载名称和描述,因此它们不会占满你的整个上下文窗口,比如当你在调试的时候,你的PR审查清单不需要出现在这些上下文中,而是在你实际请求审查的时候加载。

• 斜杠指令需要你显示的输入它们 技能不需要,Claude会在识别出相应情况时使用它们。

当Claude将某个技能与你当前的需求匹配上时,你可以在终端中看到它的加载情况。

何时使用技能

技能最适合应用于特定任务的专业知识：

• 你团队遵循的代码审查标准

• 你偏好的提交信息格式

• 你组织的品牌指南

• 特定类型文档的文档模板

• 特定框架的调试清单

经验法则很简单：如果你发现自己反复向 Claude 解释同一件事，那就说明有一个技能等待被编写出来。

创建你的第一个技能

我们将构建一个个人技能,教Claude如何以一致的格式编写PR描述。由于这是一个个人技能,所以我们可以将它放在你的主目录中,并且适用于你所有的项目。

首先,在skills文件夹中为你的技能创建一个目录 目录名称与你的技能名称匹配:

  mkdir -p ~/.claude/skills/pr-description

然后在该目录内创建一个SKILL.md文件。该文件有两部分，由frontmatter破折号分隔：

  ---
  name: pr-description
  description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
  ---
  
  When writing a PR description:
  
  1. Run `git diff main...HEAD` to see all changes on this branch
  2. Write a description following this format:
  
  ## What
  One sentence explaining what this PR does.
  
  ## Why
  Brief context on why this change is needed
  
  ## Changes
  - Bullet points of specific changes made
  - Group related changes together
  - Mention any files deleted or renamed

如果你还不知道什么是markdown,可以看看我的另一片上古教程 轻松上手Markdown,效率提升的必学标记语言,快速上手。

其中, name是你的技能标识,也即是技能名称。description告诉Claude何时使用它,这是决定着Claude可否能在识别到相关需求时候自动匹配到你的技能的很重要的字段。

第二组破折号之后的所有内容都是技能被激活时Claude遵循的指令。也就是技能主体内容部分。

测试你的技能

ClaudeCode在启动技能时加载技能,因此创建技能后请重启你的会话。你可以通过检查可用技能列表来验证它时候可用。

你应该能看到你的技能列在其中。要测试它，在某个分支上做一些更改，然后说类似"为我的更改写一个PR描述"这样的话。Claude会表明它正在使用PR描述技能，检查你的diff，并按照你的模板编写描述——每次格式都相同。

匹配技能的工作原理

当Claude Code启动时，它会扫描四个位置以查找技能，但只加载名称和描述——而不是完整内容。这是一个重要的细节。

当你发送请求时，Claude会将你的消息与所有可用技能的描述进行比较。例如，"解释这个函数的作用"会匹配一个描述为"用可视化图表解释代码"的技能，因为意图存在重叠。

一旦找到匹配项，Claude会要求你确认加载该技能。这个确认步骤让你了解Claude正在引入哪些上下文。确认后，Claude会读取完整的SKILL.md文件并遵循其中的指令。

技能优先级

如果你克隆了一个仓库，其中有一个与你的某个个人技能同名的技能，哪一个会胜出？这里有一个明确的优先级顺序：

1. Enterprise — 受管理的设置，最高优先级

2. Personal — 你的主目录（~/.claude/skills）

3. Project — 仓库内的.claude/skills目录

4. Plugins — 已安装的插件，最低优先级

这使得组织可以通过企业技能强制执行标准，同时仍允许个人定制。如果你的公司有一个企业级的"code-review"技能，而你创建了一个同名的个人"code-review"技能，企业版本将优先生效。

为避免冲突，请使用描述性的名称。不要只用"review"，而应使用类似"frontend-review"或"backend-review"这样的名称。

更新和删除技能

要更新技能，编辑其SKILL.md文件。要删除技能，删除其目录。任何更改后都需要重启Claude Code才能生效。

配置与多文件技能

一个基本的技能只需要名称和描述即可运作，但还有几种高级技巧可以让你的技能在 Claude Code 中更加有效。让我们来了解一下关键字段、描述的最佳实践、工具限制，以及如何构建更大的技能。

技能元数据字段

Agent Skills 开放标准在 SKILL.md 前置元数据中支持多个字段。其中两个是必填的，其余为可选：

• name（必填） — 标识你的技能。仅使用小写字母、数字和连字符。最多 64 个字符。应与你的目录名称匹配。

• description（必填） — 告诉 Claude 何时使用该技能。最多 1,024 个字符。这是最重要的字段，因为 Claude 使用它进行匹配。

• allowed-tools（可选） — 限制技能激活时 Claude 可以使用的工具。

• model（可选） — 指定该技能要使用的 Claude 模型。

编写有效的描述

对你的指令要明确。如果有人告诉你"你的工作是帮助处理文档"，你不会知道该做什么 — Claude 的思考方式也是一样的。

一个好的描述回答两个问题：

1. 该技能做什么？

2. Claude 应该在何时使用它？

如果你的技能没有按预期触发，请尝试添加更多与你实际表达请求方式相匹配的关键词。描述是 Claude 用来判断某个技能是否相关的依据，因此语言表达很重要。

使用 allowed-tools 限制工具

有时你希望某个技能只能读取文件，而不能修改它们。这对于安全敏感的工作流、只读任务，或任何你想要设置防护措施的情况都很有用。

在此示例中，allowed-tools 字段被设置为 Read, Grep, Glob, Bash。当此技能处于激活状态时，Claude 只能使用这些工具而无需请求许可 — 不能编辑，不能写入。

yaml

  ---
  name: codebase-onboarding
  description: Helps new developers understand the system works.
  allowed-tools: Read, Grep, Glob, Bash
  model: sonnet
  ---

如果你完全省略 allowed-tools，该技能不会限制任何内容。Claude 将使用其正常的权限模型。

渐进式披露

技能与你的对话共享 Claude 的上下文窗口。当 Claude 激活某个技能时，它会将该 SKILL.md 的内容加载到上下文中。但有时你需要该技能所依赖的参考资料、示例或实用脚本。

将所有内容塞进一个 2,000 行的文件中会带来两个问题：它会占用大量上下文窗口空间，而且维护起来也不轻松。

渐进式披露解决了这个问题。将基本指令保留在 SKILL.md 中，并将详细的参考材料放在单独的文件中，Claude 仅在需要时才读取这些文件。

该开放标准建议按以下方式组织你的技能目录：

• scripts/ — 可执行代码

• references/ — 附加文档

• assets/ — 图片、模板或其他数据文件

然后在 SKILL.md 中，链接到支持文件，并附上关于何时加载它们的明确说明：

在此示例中，Claude 只有在有人询问系统设计时才会读取 architecture-guide.md。如果他们询问的是在哪里添加组件，它就永远不会加载该文件。这就像在上下文窗口中拥有一份目录，而不是整份文档。

一个好的经验法则是：将 SKILL.md 保持在 500 行以内。如果超出了这个限制，请考虑是否应将内容拆分到单独的参考文件中。

高效使用脚本

你技能目录中的脚本可以在不将其内容加载到上下文中的情况下运行。脚本执行后，只有输出会消耗令牌。在你的 SKILL.md 中需要包含的关键指令是告诉 Claude 运行 该脚本，而不是 读取 它。

这对以下情况特别有用：

• 环境验证

• 需要保持一致性的数据转换

• 作为经过测试的代码比生成的代码更可靠的操作

技能与其他ClaudeCode功能的比较

CLAUDE.md 与 Skills 的比较

CLAUDE.md 会始终加载到每次对话中。如果你希望 Claude 在你的项目中使用 TypeScript 严格模式，请将其写入你的 CLAUDE.md 文件。

Skills 按需加载。当 Claude 将某个请求与某个 skill 匹配时，该 skill 的指令就会加入对话。当你在编写新代码时，你的 PR 审查清单并不需要出现在上下文中——它只在你请求审查时才会激活。

在以下情况使用 CLAUDE.md：

• 始终适用的项目级标准

• 诸如"永远不要修改数据库架构"之类的约束

• 框架偏好和编码风格

在以下情况使用 Skills：

• 特定任务的专业知识

• 只在某些情况下才相关的知识

• 会使每次对话都变得杂乱的详细流程

Skills 与 Subagents 的比较

Skills 会为你当前的对话添加知识。当某个 skill 激活时，其指令会加入现有的上下文。

Subagents 在独立的上下文中运行。它们接收一个任务，独立完成工作，然后返回结果。它们与主对话是隔离的。

在以下情况使用 Subagents：

• 你想将任务委派给一个独立的执行上下文

• 你需要与主对话不同的工具访问权限

• 你希望将委派的工作与主上下文隔离开来

在以下情况使用 Skills：

• 你想为当前任务增强 Claude 的知识

• 该专业知识适用于整个对话过程

Skills 与 Hooks 的比较

Hooks 在事件发生时触发。某个 hook 可能会在 Claude 每次保存文件时运行代码检查工具，或在特定工具调用之前验证输入。它们是事件驱动的。

Skills 是请求驱动的。它们根据你的请求内容激活。

在以下情况使用 Hooks：

• 应在每次文件保存时运行的操作

• 特定工具调用之前的验证

• Claude 操作的自动化副作用

在以下情况使用 Skills：

• 影响 Claude 处理请求方式的知识

• 影响 Claude 推理过程的指导原则

将它们整合在一起

一个典型的配置可能包括：

• CLAUDE.md —— 始终生效的项目标准

• Skills —— 按需加载的特定任务专业知识

• Hooks —— 由事件触发的自动化操作

• Subagents —— 用于委派工作的隔离执行上下文

• MCP servers —— 外部工具和集成

每种功能都各有专长。当其他选项更合适时，不要把所有事情都硬塞进 skills 中——而且你可以同时使用多种功能。Skills 提供自动化的特定任务专业知识，CLAUDE.md 用于始终生效的指令，subagents 在隔离的上下文中运行，hooks 在事件发生时触发，而 MCP 提供外部工具。

当你拥有应在相关主题出现时由 Claude 自动应用的知识时，请使用 skills，并将其与其他功能结合使用，以实现全面的自定义。

共享技能

将技能提交到你的仓库

最简单的共享方法是将技能直接提交到你的仓库。将它们放在 .claude/skills 中，任何克隆该仓库的人都会自动获得这些技能——无需额外安装。

当你推送更新时，每个人在下次拉取时都会获得这些更新。这种方法适用于：

• 团队编码标准

• 项目特定的工作流程

• 引用你代码库结构的技能

.claude 目录包含你的代理、钩子、技能和设置——所有内容都经过版本控制，并通过正常的 Git 工作流程与团队共享。

通过插件分发技能

插件是一种通过自定义功能扩展 Claude Code 的方式，旨在跨团队和项目共享。在你的插件项目中，创建一个遵循与 .claude 目录类似文件结构的 skills 目录——每个技能都有自己的文件夹，里面包含一个 SKILL.md 文件。

在你将插件分发到市场后，其他用户可以自行发现并将其安装到 Claude Code 中。

当你的技能不是过于特定于某个项目，并且对直接团队以外的社区成员也有用时，这种方法是最佳选择。

通过托管设置进行企业部署

管理员可以通过托管设置在整个组织范围内部署技能。企业技能具有最高优先级——它们会覆盖同名的个人、项目和插件技能。

托管设置文件支持诸如 strictKnownMarketplaces 之类的功能，用于控制可以从哪里安装插件：

json

  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]

对于必须在整个组织中保持一致的强制性标准、安全要求、合规工作流程和编码实践，这是正确的选择。这里的关键词是"必须"。

技能与子代理

有一件事会让人感到意外：子代理不会自动看到你的技能。当你将任务委派给子代理时，它会以全新、干净的上下文开始。

这里有一些需要理解的重要区别：

• 内置代理（如 Explorer、Plan 和 Verify）完全无法访问技能

• 你定义的自定义子代理可以使用技能，但只有在你明确列出它们时才可以

• 技能在子代理启动时加载，而不像在主对话中那样按需加载

要创建带有技能的自定义子代理，请在 .claude/agents 中添加一个代理 markdown 文件。你可以使用 Claude Code 中的 /agents 命令以交互方式创建一个：

生成的代理文件包含一个 skills 字段，列出要加载的技能。以下是前置元数据的样子：

  ---
  name: frontend-security-accessibility-reviewer
  description: "Use this agent when you need to review frontend code for accessibility..."
  tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
  model: sonnet
  color: blue
  skills: accessibility-audit, performance-check
  ---

当你委派给这个子代理时，它会加载这两项技能，并将它们应用于每次审查。首先确保这些技能存在于你的 .claude/skills 目录中，然后创建一个新的子代理，或将 skills 字段添加到现有代理的 markdown 文件中。

这种模式在以下情况下效果非常好：

• 你希望进行具有特定专业知识的隔离任务委派

• 不同的子代理需要不同的技能（前端审查者与后端审查者）

• 你希望在委派的工作中强制执行标准，而不依赖于提示

技能故障排查

使用技能验证器

首先应该尝试的是 agent skills verifier 命令。安装步骤因操作系统而异，但使用 uv 是最快捷的设置方式。

安装完成后，你可以导航到你的技能目录，或者从任意位置运行该命令。验证器会在你花时间调试其他问题之前，先捕获结构性问题。

技能无法触发

你的技能存在且通过了验证，但 Claude 在你期望的时候却没有使用它。原因几乎总是出在描述上。

Claude 使用语义匹配，因此你的请求需要与描述的含义有所重叠。如果重叠不足，就不会匹配。以下是你应该做的：

• 将你的描述与你实际表达请求的方式进行对照检查

• 添加用户实际会说出的触发短语

• 用各种变体进行测试，例如"帮我分析一下这个性能"、"为什么这个这么慢？"、"让这个更快一点"

• 如果任何变体未能触发，请将这些关键词添加到你的描述中

技能无法加载

如果你询问 Claude "有哪些可用技能"时，你的技能没有出现，请检查以下结构性要求：

• SKILL.md 文件必须位于一个命名目录内，而不是在技能根目录下

• 文件名必须恰好为 SKILL.md——"SKILL"全部大写，"md"小写

运行 claude --debug 查看加载错误。留意提及你技能名称的消息。有时仅凭这一点就能直接指向问题所在。

使用了错误的技能

如果 Claude 使用了错误的技能，或者在多个技能之间似乎感到困惑，那么你的描述很可能过于相似。让它们更具区分度。尽可能具体不仅有助于 Claude 决定何时使用你的技能——还能防止与其他听起来相似的技能发生冲突。

技能优先级冲突

如果你的个人技能被忽略，可能是因为存在一个同名的企业级或更高优先级的技能。

例如，如果存在一个企业级的"code-review"技能，而你也有一个个人的"code-review"技能，企业级的那个每次都会胜出。你的选择：

1. 将你的技能重命名为更具区分度的名称（这通常是更简单的方法）

2. 与你的管理员沟通该企业级技能的情况

插件技能未出现

安装了插件但看不到其技能？清除缓存，重启 Claude Code，然后重新安装。

如果之后技能仍未出现，可能是插件结构有问题。这正是验证器工具真正发挥作用的时候。

运行时错误

技能已加载，但在执行过程中失败。几个常见原因：

• 缺失依赖项： 如果你的技能使用了外部软件包，这些软件包必须已安装。在你的技能描述中添加依赖信息，以便 Claude 知道需要什么。

• 权限问题： 脚本需要执行权限。对你的技能所引用的任何脚本运行 chmod +x。

• 路径分隔符： 在所有地方都使用正斜杠，即使在 Windows 上也是如此。

快速故障排查清单

• 无法触发？ 改进你的描述并添加触发短语。

• 无法加载？ 检查你的路径、文件名和 YAML 语法。

• 使用了错误的技能？ 让各个描述之间更具区分度。

• 被遮蔽了？ 检查优先级层级结构，如有需要请重命名。

• 插件技能缺失？ 清除缓存并重新安装。

• 运行时失败？ 检查依赖项、权限和路径。

描述是 Claude 决定是否使用该技能的依据。当你要求 Claude 审查 PR 时，它会将你的请求与可用的技能描述进行匹配，并找到相关的那个。Claude 会读取你的请求，将其与所有可用的技能描述进行比较，并激活匹配的那些。 以下是技能前言的样子：

 ---
 name: pr-review
 description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
 ---

在前言的下方,你编写实际的指令,你的审查清单、格式偏好、或者Claude在执行任务时需要知道的任何内容。

技能的存放位置

你可以根据谁需要它们,将技能存在不同的位置:

• 个人技能 存放在 ~/.claude/skills（你的主目录）中。这些技能会跟随你在所有项目中使用——你的提交信息风格、你的文档格式、你喜欢的代码解释方式。

• 项目技能 存放在仓库根目录内的 .claude/skills 中。任何克隆该仓库的人都会自动获得这些技能。团队标准就存放在这里，例如你公司的品牌指南、网页设计偏好的字体和颜色。

在 Windows 上，个人技能存放在 C:/Users/<your-user>/.claude/skills 中。

项目技能会与你的代码一起提交到版本控制中，因此整个团队都能共享它们。

技能vsCLAUD.mdvs斜杠指令

ClaudeCode中有多种方式来制定行为 技能的独特之处在于它们是自动且针对特定任务的。一下是它们的比较:

• CLAUDDE.md文件会加载到每次对话中。如果你希望Claude始终使用TypeScript严格模式,那应该将这个规约写在CLAUDE.md中。

• 技能 在匹配你的请求时按需加载 Claude最初只加载名称和描述,因此它们不会占满你的整个上下文窗口,比如当你在调试的时候,你的PR审查清单不需要出现在这些上下文中,而是在你实际请求审查的时候加载。

• 斜杠指令需要你显示的输入它们 技能不需要,Claude会在识别出相应情况时使用它们。

当Claude将某个技能与你当前的需求匹配上时,你可以在终端中看到它的加载情况。

何时使用技能

技能最适合应用于特定任务的专业知识：

• 你团队遵循的代码审查标准

• 你偏好的提交信息格式

• 你组织的品牌指南

• 特定类型文档的文档模板

• 特定框架的调试清单

经验法则很简单：如果你发现自己反复向 Claude 解释同一件事，那就说明有一个技能等待被编写出来。

创建你的第一个技能

我们将构建一个个人技能,教Claude如何以一致的格式编写PR描述。由于这是一个个人技能,所以我们可以将它放在你的主目录中,并且适用于你所有的项目。

首先,在skills文件夹中为你的技能创建一个目录 目录名称与你的技能名称匹配:

 mkdir -p ~/.claude/skills/pr-description

然后在该目录内创建一个SKILL.md文件。该文件有两部分，由frontmatter破折号分隔：

 ---
 name: pr-description
 description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
 ---
 ​
 When writing a PR description:
 ​
 1. Run `git diff main...HEAD` to see all changes on this branch
 2. Write a description following this format:
 ​
 ## What
 One sentence explaining what this PR does.
 ​
 ## Why
 Brief context on why this change is needed
 ​
 ## Changes
 - Bullet points of specific changes made
 - Group related changes together
 - Mention any files deleted or renamed

如果你还不知道什么是markdown,可以看看我的另一片上古教程 轻松上手Markdown,效率提升的必学标记语言,快速上手。

其中, name是你的技能标识,也即是技能名称。description告诉Claude何时使用它,这是决定着Claude可否能在识别到相关需求时候自动匹配到你的技能的很重要的字段。

第二组破折号之后的所有内容都是技能被激活时Claude遵循的指令。也就是技能主体内容部分。

测试你的技能

ClaudeCode在启动技能时加载技能,因此创建技能后请重启你的会话。你可以通过检查可用技能列表来验证它时候可用。

你应该能看到你的技能列在其中。要测试它，在某个分支上做一些更改，然后说类似"为我的更改写一个PR描述"这样的话。Claude会表明它正在使用PR描述技能，检查你的diff，并按照你的模板编写描述——每次格式都相同。

匹配技能的工作原理

当Claude Code启动时，它会扫描四个位置以查找技能，但只加载名称和描述——而不是完整内容。这是一个重要的细节。

当你发送请求时，Claude会将你的消息与所有可用技能的描述进行比较。例如，"解释这个函数的作用"会匹配一个描述为"用可视化图表解释代码"的技能，因为意图存在重叠。

一旦找到匹配项，Claude会要求你确认加载该技能。这个确认步骤让你了解Claude正在引入哪些上下文。确认后，Claude会读取完整的SKILL.md文件并遵循其中的指令。

技能优先级

如果你克隆了一个仓库，其中有一个与你的某个个人技能同名的技能，哪一个会胜出？这里有一个明确的优先级顺序：

1. Enterprise — 受管理的设置，最高优先级

2. Personal — 你的主目录（~/.claude/skills）

3. Project — 仓库内的.claude/skills目录

4. Plugins — 已安装的插件，最低优先级

这使得组织可以通过企业技能强制执行标准，同时仍允许个人定制。如果你的公司有一个企业级的"code-review"技能，而你创建了一个同名的个人"code-review"技能，企业版本将优先生效。

为避免冲突，请使用描述性的名称。不要只用"review"，而应使用类似"frontend-review"或"backend-review"这样的名称。

更新和删除技能

要更新技能，编辑其SKILL.md文件。要删除技能，删除其目录。任何更改后都需要重启Claude Code才能生效。

配置与多文件技能

一个基本的技能只需要名称和描述即可运作，但还有几种高级技巧可以让你的技能在 Claude Code 中更加有效。让我们来了解一下关键字段、描述的最佳实践、工具限制，以及如何构建更大的技能。

技能元数据字段

Agent Skills 开放标准在 SKILL.md 前置元数据中支持多个字段。其中两个是必填的，其余为可选：

• name（必填） — 标识你的技能。仅使用小写字母、数字和连字符。最多 64 个字符。应与你的目录名称匹配。

• description（必填） — 告诉 Claude 何时使用该技能。最多 1,024 个字符。这是最重要的字段，因为 Claude 使用它进行匹配。

• allowed-tools（可选） — 限制技能激活时 Claude 可以使用的工具。

• model（可选） — 指定该技能要使用的 Claude 模型。

编写有效的描述

对你的指令要明确。如果有人告诉你"你的工作是帮助处理文档"，你不会知道该做什么 — Claude 的思考方式也是一样的。

一个好的描述回答两个问题：

1. 该技能做什么？

2. Claude 应该在何时使用它？

如果你的技能没有按预期触发，请尝试添加更多与你实际表达请求方式相匹配的关键词。描述是 Claude 用来判断某个技能是否相关的依据，因此语言表达很重要。

使用 allowed-tools 限制工具

有时你希望某个技能只能读取文件，而不能修改它们。这对于安全敏感的工作流、只读任务，或任何你想要设置防护措施的情况都很有用。

在此示例中，allowed-tools 字段被设置为 Read, Grep, Glob, Bash。当此技能处于激活状态时，Claude 只能使用这些工具而无需请求许可 — 不能编辑，不能写入。

yaml

 ---
 name: codebase-onboarding
 description: Helps new developers understand the system works.
 allowed-tools: Read, Grep, Glob, Bash
 model: sonnet
 ---

如果你完全省略 allowed-tools，该技能不会限制任何内容。Claude 将使用其正常的权限模型。

渐进式披露

技能与你的对话共享 Claude 的上下文窗口。当 Claude 激活某个技能时，它会将该 SKILL.md 的内容加载到上下文中。但有时你需要该技能所依赖的参考资料、示例或实用脚本。

将所有内容塞进一个 2,000 行的文件中会带来两个问题：它会占用大量上下文窗口空间，而且维护起来也不轻松。

渐进式披露解决了这个问题。将基本指令保留在 SKILL.md 中，并将详细的参考材料放在单独的文件中，Claude 仅在需要时才读取这些文件。

该开放标准建议按以下方式组织你的技能目录：

• scripts/ — 可执行代码

• references/ — 附加文档

• assets/ — 图片、模板或其他数据文件

然后在 SKILL.md 中，链接到支持文件，并附上关于何时加载它们的明确说明：

在此示例中，Claude 只有在有人询问系统设计时才会读取 architecture-guide.md。如果他们询问的是在哪里添加组件，它就永远不会加载该文件。这就像在上下文窗口中拥有一份目录，而不是整份文档。

一个好的经验法则是：将 SKILL.md 保持在 500 行以内。如果超出了这个限制，请考虑是否应将内容拆分到单独的参考文件中。

高效使用脚本

你技能目录中的脚本可以在不将其内容加载到上下文中的情况下运行。脚本执行后，只有输出会消耗令牌。在你的 SKILL.md 中需要包含的关键指令是告诉 Claude 运行 该脚本，而不是 读取 它。

这对以下情况特别有用：

• 环境验证

• 需要保持一致性的数据转换

• 作为经过测试的代码比生成的代码更可靠的操作

技能与其他ClaudeCode功能的比较

CLAUDE.md 与 Skills 的比较

CLAUDE.md 会始终加载到每次对话中。如果你希望 Claude 在你的项目中使用 TypeScript 严格模式，请将其写入你的 CLAUDE.md 文件。

Skills 按需加载。当 Claude 将某个请求与某个 skill 匹配时，该 skill 的指令就会加入对话。当你在编写新代码时，你的 PR 审查清单并不需要出现在上下文中——它只在你请求审查时才会激活。

在以下情况使用 CLAUDE.md：

• 始终适用的项目级标准

• 诸如"永远不要修改数据库架构"之类的约束

• 框架偏好和编码风格

在以下情况使用 Skills：

• 特定任务的专业知识

• 只在某些情况下才相关的知识

• 会使每次对话都变得杂乱的详细流程

Skills 与 Subagents 的比较

Skills 会为你当前的对话添加知识。当某个 skill 激活时，其指令会加入现有的上下文。

Subagents 在独立的上下文中运行。它们接收一个任务，独立完成工作，然后返回结果。它们与主对话是隔离的。

在以下情况使用 Subagents：

• 你想将任务委派给一个独立的执行上下文

• 你需要与主对话不同的工具访问权限

• 你希望将委派的工作与主上下文隔离开来

在以下情况使用 Skills：

• 你想为当前任务增强 Claude 的知识

• 该专业知识适用于整个对话过程

Skills 与 Hooks 的比较

Hooks 在事件发生时触发。某个 hook 可能会在 Claude 每次保存文件时运行代码检查工具，或在特定工具调用之前验证输入。它们是事件驱动的。

Skills 是请求驱动的。它们根据你的请求内容激活。

在以下情况使用 Hooks：

• 应在每次文件保存时运行的操作

• 特定工具调用之前的验证

• Claude 操作的自动化副作用

在以下情况使用 Skills：

• 影响 Claude 处理请求方式的知识

• 影响 Claude 推理过程的指导原则

将它们整合在一起

一个典型的配置可能包括：

• CLAUDE.md —— 始终生效的项目标准

• Skills —— 按需加载的特定任务专业知识

• Hooks —— 由事件触发的自动化操作

• Subagents —— 用于委派工作的隔离执行上下文

• MCP servers —— 外部工具和集成

每种功能都各有专长。当其他选项更合适时，不要把所有事情都硬塞进 skills 中——而且你可以同时使用多种功能。Skills 提供自动化的特定任务专业知识，CLAUDE.md 用于始终生效的指令，subagents 在隔离的上下文中运行，hooks 在事件发生时触发，而 MCP 提供外部工具。

当你拥有应在相关主题出现时由 Claude 自动应用的知识时，请使用 skills，并将其与其他功能结合使用，以实现全面的自定义。

共享技能

将技能提交到你的仓库

最简单的共享方法是将技能直接提交到你的仓库。将它们放在 .claude/skills 中，任何克隆该仓库的人都会自动获得这些技能——无需额外安装。

当你推送更新时，每个人在下次拉取时都会获得这些更新。这种方法适用于：

• 团队编码标准

• 项目特定的工作流程

• 引用你代码库结构的技能

.claude 目录包含你的代理、钩子、技能和设置——所有内容都经过版本控制，并通过正常的 Git 工作流程与团队共享。

通过插件分发技能

插件是一种通过自定义功能扩展 Claude Code 的方式，旨在跨团队和项目共享。在你的插件项目中，创建一个遵循与 .claude 目录类似文件结构的 skills 目录——每个技能都有自己的文件夹，里面包含一个 SKILL.md 文件。

在你将插件分发到市场后，其他用户可以自行发现并将其安装到 Claude Code 中。

当你的技能不是过于特定于某个项目，并且对直接团队以外的社区成员也有用时，这种方法是最佳选择。

通过托管设置进行企业部署

管理员可以通过托管设置在整个组织范围内部署技能。企业技能具有最高优先级——它们会覆盖同名的个人、项目和插件技能。

托管设置文件支持诸如 strictKnownMarketplaces 之类的功能，用于控制可以从哪里安装插件：

json

 "strictKnownMarketplaces": [
   {
     "source": "github",
     "repo": "acme-corp/approved-plugins"
   },
   {
     "source": "npm",
     "package": "@acme-corp/compliance-plugins"
   }
 ]

对于必须在整个组织中保持一致的强制性标准、安全要求、合规工作流程和编码实践，这是正确的选择。这里的关键词是"必须"。

技能与子代理

有一件事会让人感到意外：子代理不会自动看到你的技能。当你将任务委派给子代理时，它会以全新、干净的上下文开始。

这里有一些需要理解的重要区别：

• 内置代理（如 Explorer、Plan 和 Verify）完全无法访问技能

• 你定义的自定义子代理可以使用技能，但只有在你明确列出它们时才可以

• 技能在子代理启动时加载，而不像在主对话中那样按需加载

要创建带有技能的自定义子代理，请在 .claude/agents 中添加一个代理 markdown 文件。你可以使用 Claude Code 中的 /agents 命令以交互方式创建一个：

生成的代理文件包含一个 skills 字段，列出要加载的技能。以下是前置元数据的样子：

 ---
 name: frontend-security-accessibility-reviewer
 description: "Use this agent when you need to review frontend code for accessibility..."
 tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
 model: sonnet
 color: blue
 skills: accessibility-audit, performance-check
 ---

当你委派给这个子代理时，它会加载这两项技能，并将它们应用于每次审查。首先确保这些技能存在于你的 .claude/skills 目录中，然后创建一个新的子代理，或将 skills 字段添加到现有代理的 markdown 文件中。

这种模式在以下情况下效果非常好：

• 你希望进行具有特定专业知识的隔离任务委派

• 不同的子代理需要不同的技能（前端审查者与后端审查者）

• 你希望在委派的工作中强制执行标准，而不依赖于提示

技能故障排查

使用技能验证器

首先应该尝试的是 agent skills verifier 命令。安装步骤因操作系统而异，但使用 uv 是最快捷的设置方式。

安装完成后，你可以导航到你的技能目录，或者从任意位置运行该命令。验证器会在你花时间调试其他问题之前，先捕获结构性问题。

技能无法触发

你的技能存在且通过了验证，但 Claude 在你期望的时候却没有使用它。原因几乎总是出在描述上。

Claude 使用语义匹配，因此你的请求需要与描述的含义有所重叠。如果重叠不足，就不会匹配。以下是你应该做的：

• 将你的描述与你实际表达请求的方式进行对照检查

• 添加用户实际会说出的触发短语

• 用各种变体进行测试，例如"帮我分析一下这个性能"、"为什么这个这么慢？"、"让这个更快一点"

• 如果任何变体未能触发，请将这些关键词添加到你的描述中

技能无法加载

如果你询问 Claude "有哪些可用技能"时，你的技能没有出现，请检查以下结构性要求：

• SKILL.md 文件必须位于一个命名目录内，而不是在技能根目录下

• 文件名必须恰好为 SKILL.md——"SKILL"全部大写，"md"小写

运行 claude --debug 查看加载错误。留意提及你技能名称的消息。有时仅凭这一点就能直接指向问题所在。

使用了错误的技能

如果 Claude 使用了错误的技能，或者在多个技能之间似乎感到困惑，那么你的描述很可能过于相似。让它们更具区分度。尽可能具体不仅有助于 Claude 决定何时使用你的技能——还能防止与其他听起来相似的技能发生冲突。

技能优先级冲突

如果你的个人技能被忽略，可能是因为存在一个同名的企业级或更高优先级的技能。

例如，如果存在一个企业级的"code-review"技能，而你也有一个个人的"code-review"技能，企业级的那个每次都会胜出。你的选择：

1. 将你的技能重命名为更具区分度的名称（这通常是更简单的方法）

2. 与你的管理员沟通该企业级技能的情况

插件技能未出现

安装了插件但看不到其技能？清除缓存，重启 Claude Code，然后重新安装。

如果之后技能仍未出现，可能是插件结构有问题。这正是验证器工具真正发挥作用的时候。

运行时错误

技能已加载，但在执行过程中失败。几个常见原因：

• 缺失依赖项： 如果你的技能使用了外部软件包，这些软件包必须已安装。在你的技能描述中添加依赖信息，以便 Claude 知道需要什么。

• 权限问题： 脚本需要执行权限。对你的技能所引用的任何脚本运行 chmod +x。

• 路径分隔符： 在所有地方都使用正斜杠，即使在 Windows 上也是如此。

快速故障排查清单

• 无法触发？ 改进你的描述并添加触发短语。

• 无法加载？ 检查你的路径、文件名和 YAML 语法。

• 使用了错误的技能？ 让各个描述之间更具区分度。

• 被遮蔽了？ 检查优先级层级结构，如有需要请重命名。

• 插件技能缺失？ 清除缓存并重新安装。

• 运行时失败？ 检查依赖项、权限和路径。