Claude Code Skills: What They Are and How to Build, Share, and Troubleshoot

技能（skills）是什么？

💡 洞察与导读： 本质与通俗理解： 人们天生厌恶机械性的重复劳动，这是节省脑力（认知负荷）的本能。在 AI 时代，如果你发现自己每天都在对 AI 说同样的话（比如“请用中文回答”、“帮我检查代码格式”），这就是一种低效的消耗。“技能（Skill）”的本质，就是把 人们的某种特定“工作习惯”打包固化下来。 你只需要教 AI 一次，给它写一个小抄本（Markdown 文件）。以后只要遇到类似的场景，AI 就会按需自动把小抄拿出来照做。它不占日常内存，只在关键时刻发挥作用。

学习内容 https://anthropic.skilljar.com/introduction-to-agent-skills/434525 预计耗时：15分钟

在本课结束时，你将能够：

• 定义 Claude Code 技能（skill）的概念及其工作原理
• 说明技能的存放位置（个人目录与项目目录的区别）
• 区分技能、CLAUDE.md 与斜杠命令（slash commands）
• 识别适合使用技能进行定制的场景

什么是技能？

（3 分钟） 本视频介绍技能（skills）——可复用的 Markdown 文件，用于让 Claude Code 自动处理特定任务。你无需每次都重复指令，例如让 Claude 审查 PR 或编写提交说明，只需编写一次技能，Claude 在遇到相关任务时会自动应用。视频内容涵盖技能的定义、存放位置，以及它们与其他 Claude Code 个性化选项的区别。

关键要点

• 技能（skill）是包含指令的文件夹，Claude Code 可以自动发现并使用这些技能，从而更精准地处理任务。每个技能都存放在 SKILL.md 文件中，前置元数据（frontmatter）包含技能名称和描述（description）。
• Claude 会利用描述（description）进行语义匹配，将技能与请求关联。当你向 Claude 提出需求时，它会将你的请求与现有技能的描述进行比较，并自动激活匹配的技能。
• 个人技能存放在 ~/.claude/skills 目录下，可在所有项目中通用。项目技能则存放在代码仓库的 .claude/skills 目录中，任何克隆该仓库的人都能共享这些技能。
• 技能按需加载——不同于 CLAUDE.md（每次对话都会加载）或斜杠命令（slash commands，需要手动调用），技能会在 Claude 识别到相关场景时自动激活。

如果你发现自己总是在向 Claude 反复解释同一件事，那就是一个等待编写的技能。

每次你向 Claude 说明团队的编码规范时，都是在重复自己。每次 PR 审查，你都要重新描述反馈结构。每次提交说明（commit message），你都要提醒 Claude 你的格式偏好。技能可以解决这些重复问题。 技能（skill）是一个 Markdown 文件，用于一次性教会 Claude 执行某项任务。此后，Claude 会在相关场景中自动应用这部分知识。

技能（skill）是什么

技能是包含指令和资源的文件夹，Claude Code 能够自动发现并使用这些技能，从而更精准地完成任务。每个技能都位于名为 SKILL.md 的文件中，其前置元数据（frontmatter）中包含技能名称和描述（description）。

描述（description）是 Claude 判断是否使用某个技能（skill）的依据。当你让 Claude 审查 PR 时，它会将你的请求与所有可用技能的描述进行匹配，找到相关技能。Claude 会读取你的请求，逐一比对所有技能的描述，并激活那些匹配的技能。

技能（skill）的前置元数据（frontmatter）示例如下：

---
name: pr-review
description: 审查拉取请求（PR）的代码质量。适用于审查 PR 或检查代码变更时。
---

在前置元数据（frontmatter）下方，你可以编写具体指令——例如审查清单、格式偏好，或任何 Claude 在该任务中需要了解的信息。

技能存放位置

你可以根据使用需求，将技能（skill）存放在不同位置：

• **个人技能（skill）**存放在 ~/.claude/skills（你的主目录）。这些技能会在所有项目中伴随你使用，例如你的提交说明风格、文档格式，以及你偏好的代码讲解方式。
• **项目技能（skill）**存放在代码仓库（repo）根目录下的 .claude/skills。任何人克隆该仓库时都会自动获得这些技能。这是团队标准的集中地，比如公司品牌规范、网页设计中常用的字体和配色等。

在 Windows 系统上，个人技能存放路径为 C:/Users/<your-user>/.claude/skills。 项目技能会与代码一同提交到版本控制系统中，从而让整个团队共享这些技能。

技能（skill）与 CLAUDE.md 与斜杠命令（slash commands）

Claude Code 提供多种定制行为的方式。技能（skill）的独特之处在于它们会自动触发，并针对具体任务。以下是三者的对比：

• CLAUDE.md 文件会在每次对话中自动加载。如果你希望 Claude 始终使用 TypeScript 的严格模式，可以将相关内容写入 CLAUDE.md。
• **技能（skill）**会按需加载，只有在与你的请求匹配时才会触发。Claude 起初只会加载技能的名称和描述（description），不会占用整个上下文窗口。当你调试代码时，PR 审查清单无需常驻上下文——只有在你实际请求审查时才会加载。
• **斜杠命令（slash commands）**需要你手动输入，而技能无需手动触发。Claude 会在识别到合适场景时自动应用技能。

当 Claude 将某个技能与你的请求匹配时，你会在终端看到加载提示：

何时使用技能（skills）

技能（skills）最适合用于特定任务所需的专业知识：

• 团队遵循的代码审查标准
• 你偏好的提交说明（commit message）格式
• 组织的品牌规范
• 特定类型文档的模板
• 针对特定框架的调试清单

**经验法则很简单：**如果你发现自己总是在向 Claude 重复解释同一件事，那就说明这个技能（skill）值得编写。

课程思考/反思

• 回顾你最近与 Claude Code 的互动。哪些指令是你反复使用的？如果将它们编写成技能（skill），能为你节省多少时间？
• 再想想你团队的工作流程，哪些标准或流程最适合用技能来固化并自动化？

创建你的第一个技能（skill）

💡 洞察与导读： 本质与通俗理解：机器无法像人一样“察言观色”，它必须依赖严谨的物理路径和因果触发机制。创建一个技能，其实就是建立一个“档案袋”（文件夹）和一张“名片”（前置元数据）。 可以这样理解：你把干活的具体步骤写在一张纸上（Markdown），在纸的头部画两条线（—），在线里面写上这个技能的“名字”和“接客暗号（描述）”。以后 AI 听到你的命令，就会先核对所有名片上的暗号，对上了，它才会把下面的干活步骤拿出来执行。这就叫“语义匹配”。

学习内容 https://anthropic.skilljar.com/introduction-to-agent-skills/434527 预计耗时：20分钟

在本课结束时，你将能够：

• 从零开始创建一个技能（skill），并正确编写前置元数据（frontmatter）结构
• 测试并验证技能在 Claude Code 中能否正确加载
• 解释 Claude Code 如何将收到的请求与可用技能进行匹配
• 描述技能的优先级层级（企业 → 个人 → 项目 → 插件）

创建你的第一个技能

（4 分钟） 本视频将带你从零开始构建一个技能（skill）——一个可在所有项目中通用的个人 PR 描述技能。你将清晰了解如何规范编写 SKILL.md 文件、如何进行测试，以及 Claude Code 如何发现技能并通过语义匹配将其与请求关联。此外，视频还会讲解当技能名称冲突时，由优先级层级决定最终生效的技能版本。

关键要点

• 技能（skill）是一个包含 SKILL.md 文件的目录，SKILL.md 文件内包含前置元数据（frontmatter，包括名称和描述）以及下方的具体指令。
• Claude 启动时仅加载技能名称和描述，然后通过语义匹配（semantic matching）将收到的请求与这些描述进行比对。
• 在 Claude 将完整技能内容加载到上下文窗口前，你会收到确认提示。
• 当技能名称发生冲突时，优先级顺序为：企业 → 个人 → 项目 → 插件。
• 更新技能时，请编辑其 SKILL.md 文件；移除技能时，直接删除其目录。每次更改后都需重启 Claude Code 才能生效。
• 接下来，我们将从零开始创建一个技能，并深入了解 Claude Code 在后台是如何加载和匹配技能的。

创建技能（skill）

我们将创建一个个人技能，让 Claude 按统一格式撰写 PR 描述。作为个人技能，它位于你的主目录中，并可在所有项目中使用。

首先，在 skills 文件夹中为你的技能（skill）创建一个目录，并确保目录名称与技能名称完全一致：

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

然后在该目录下创建一个 SKILL.md 文件。该文件分为两部分，由前置元数据分隔线（frontmatter dashes）隔开：

---
name: pr-description
description: 编写拉取请求（PR）描述。用于创建 PR、撰写 PR，或在用户请求为拉取请求总结变更时使用。
---
撰写 PR 说明时：
1. 运行 `git diff main...HEAD` 查看此分支上的所有更改  
2. 按以下格式编写描述：
## 内容简介
用一句话说明此拉取请求（PR）的作用。
## 为什么
简要说明此更改的必要性
## 变更内容
- 以项目符号列出具体变更事项
- 将相关变更归类整理
- 说明任何已删除或重命名的文件

名称用于标识你的技能（skill），描述（description）用于告诉 Claude 何时使用该技能——这就是匹配的依据。第二组破折号之后的内容是技能被激活时 Claude 执行的具体指令。

测试技能（skill）

Claude Code 会在启动时加载技能（skill），因此创建新技能后需要重启会话。你可以通过查看可用技能列表来确认该技能是否已加载。

你应该能看到你的技能（skill）已列出。要测试它，可以在某个分支上进行一些修改，然后输入类似“为我的更改写一个 PR 描述”的请求。Claude 会提示正在使用 PR 描述技能，检查你的差异（diff），并按照你的模板撰写描述——每次的格式都保持一致。

技能（skill）匹配的工作原理

当 Claude Code 启动时，会扫描四个位置查找技能（skill），但只会加载技能的名称和描述（description），而不会加载完整内容。这一点至关重要。

当你发送请求时，Claude 会将你的消息与所有可用技能（skill）的描述（description）进行比对。例如，“解释这个函数的作用”可能会匹配到描述为“用可视化图表解释代码”的技能，因为两者的意图有重叠。

一旦找到匹配项，Claude 会提示你确认是否加载该技能（skill）。这一确认步骤可让你清楚了解 Claude 将引入的上下文内容。确认后，Claude 会读取完整的 SKILL.md 文件，并按照其中的指令执行。

技能优先级

如果你克隆了一个代码仓库（repo），其中包含与你的个人技能（skill）同名的技能，哪个版本会生效？优先级顺序如下：

1. 企业 — 企业托管设置，最高优先级
2. 个人 — 主目录（~/.claude/skills）
3. 项目 — 代码仓库中的 .claude/skills 目录
4. 插件 — 已安装的插件，最低优先级

这样，组织可以通过企业技能（skill）强制执行标准，同时仍允许个人自定义。如果公司有一个名为“code-review”的企业技能，而你又创建了一个同名的个人技能，则企业版本将优先生效。

为避免冲突，请使用具有描述性的名称。不要只用“review”，建议使用“frontend-review”或“backend-review”等更具体的命名。

更新和移除技能（skill）

要更新技能，请编辑其 SKILL.md 文件；要移除技能，请删除对应的目录。每次修改后，请重启 Claude Code 以使更改生效。

课程思考/反思

• 在你的日常工作流程中，有哪项任务可以立即转化为技能（skill）？你会如何撰写该技能的描述（description）？
• 优先级层级会如何影响团队的技能管理策略？你会更倾向于依赖个人技能还是项目级技能？

配置与多文件技能（skills）

💡 洞察与导读： 本质与通俗理解：系统的健壮性来自于“权限隔离”与“按需加载”。随着技能越来越复杂，把所有东西塞进一个文件会导致大模型死机并引发安全风险。 可以这样理解：不要给来家里打扫卫生的阿姨金库的钥匙（这就是用 allowed-tools 限制工具权限）；也不要一次性把家里十年的账本全扔给她看，而是列一个目录，她打扫到哪里，需要说明书时再去拿对应的参考资料（这就是“渐进式披露”和多文件拆分）。这既能防止 AI 干坏事，又能帮它省力气。

你将学习的内容 https://anthropic.skilljar.com/introduction-to-agent-skills/434526 预计耗时：20分钟

在本课结束时，你将能够：

• 配置高级技能（skill）前置元数据字段，包括 allowed-tools 和 model
• 编写高效的技能描述（description），确保能在正确请求时可靠触发
• 使用 allowed-tools 限制 Claude 在技能激活期间的操作范围
• 通过渐进式披露和多文件结构组织复杂技能

技能配置与多文件技能管理

（4 分钟） 本视频将讲解让技能（skill）更强大的高级技巧：完整的元数据字段、如何编写能够可靠触发的描述（description）、为安全敏感的工作流程限制工具访问，以及如何通过渐进式披露（progressive disclosure）将大型技能组织为多文件结构。你将学会如何在保持技能高效的同时，兼顾复杂的使用场景。

关键要点

• name 和 description 为必填项，allowed-tools 和 model 虽为可选，但能显著增强技能（skill）的能力
• 优秀的 description（描述）应回答两个问题：技能的作用是什么？Claude 应该在何时使用它？
• allowed-tools（允许的工具）用于限制技能激活时 Claude 可使用的工具——适用于只读或安全敏感的工作流
• 渐进式披露：保持 SKILL.md 不超过 500 行，并通过链接引用支持文件（参考资料、脚本、资源文件），Claude 仅在需要时读取这些内容
• 脚本执行时不会将其内容加载进上下文窗口——只有输出结果会消耗 tokens，从而保持上下文高效
• 基础技能只需 name 和 description 即可运行，但还有多种进阶技巧可让你的技能在 Claude Code 中更高效。接下来将介绍关键字段、描述撰写最佳实践、工具访问限制，以及大型技能的结构化方法。

技能元数据字段

智能体技能开放标准在 SKILL.md 的前置元数据（frontmatter）中支持多个字段，其中两个为必填项，其余为可选项：

• name（必填） — 用于标识你的技能（skill）。仅可使用小写字母、数字和连字符，最多 64 个字符。应与技能目录名称一致。
• description（必填） — 告诉 Claude 何时使用该技能（skill）。最多 1,024 个字符。这是最重要的字段，因为 Claude 会根据它进行匹配。
• allowed-tools（可选） — 限定技能（skill）激活时 Claude 可使用的工具。
• model（可选） — 指定该技能（skill）所使用的 Claude 模型。

撰写有效描述（description）

请清晰、具体地表达你的指令。如果有人只告诉你“你的工作是协助文档”，你也不会知道具体要做什么——Claude 也是如此。

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

1. 技能的作用是什么？
2. Claude 应该在什么情况下使用它？

如果技能没有按预期触发，尝试添加更多与实际请求表达方式相匹配的关键词。Claude 会根据描述（description）来判断技能是否相关，因此描述中的措辞至关重要。

使用 allowed-tools 限制工具权限

有时你可能希望某个技能（skill）只能读取文件，而不能修改文件。这在安全敏感的工作流程、只读任务，或任何需要设置防护措施的场景中都非常有用。

在此示例中，allowed-tools 字段设置为 Read, Grep, Glob, Bash。当该技能（skill）激活时，Claude 只能使用这些工具，无需额外授权——不能进行编辑或写入。

---
name: codebase-onboarding
description: 帮助新开发者理解系统的运行方式。
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

如果你完全省略 allowed-tools（允许的工具）字段，技能（skill）将不会施加任何限制。Claude 会使用其默认的权限模型。

渐进式披露

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

将所有内容塞进一个 2000 行的大文件有两个问题：一是占用了大量上下文窗口空间，二是维护起来很不方便。

渐进式披露能解决这个问题。将核心指令保存在 SKILL.md 中，把详细参考资料放在单独文件里，Claude 仅在需要时才会读取这些内容。

开放标准建议将你的技能（skill）目录组织为以下结构：

• scripts/ — 可执行代码
• references/ — 补充文档
• assets/ — 图片、模板或其他数据文件

然后在 SKILL.md 中，用清晰的说明指明何时加载这些支持文件： 在这个例子中，Claude 只有在有人询问系统设计相关问题时才会读取 architecture-guide.md。如果用户只是问该在哪里添加组件，这个文件根本不会被加载。这就像在上下文窗口中只放了目录，而不是整个文档。

**一个实用的经验法则：**将 SKILL.md 控制在 500 行以内。如果超过这个长度，请考虑将部分内容拆分到独立的参考文件中。

高效使用脚本

技能（skill）目录中的脚本可以在不将其内容加载到上下文窗口的情况下运行。脚本执行时，只有输出部分会消耗令牌（tokens）。在 SKILL.md 中需要包含的关键指令是让 Claude 执行脚本，而不是读取脚本内容。

这在以下情况中尤其有用：

• 环境验证
• 需要保持一致性的数据转换
• 作为经过测试的代码比生成代码更可靠的操作

课程思考/反思

• 想一想你想构建的一个涉及多个文件的技能（skill）。你会如何组织 SKILL.md 与配套的参考文件？
• 在你团队的工作流程中，在哪些情况下通过 allowed-tools（允许的工具）限制工具访问，可以增加重要的安全防护层？

技能（skill）与其他 Claude Code 功能的对比

💡 洞察与导读： 本质与通俗理解：不同的世界运行规律，需要不同的系统架构来应对。Claude 提供了很多功能，它们对应的触发原理完全不同。 给小白的硬核比喻：

• CLAUDE.md（全局守则）：这是贴在墙上的公司红线规章制度，时刻起作用（比如：绝不许删库）。
• 技能 Skill（锦囊妙计）：这是放你口袋里的小抄，只有你遇到特定问题主动求助时，才拿出来看。
• 钩子 Hook（肌肉记忆/条件反射）：这是防盗门警报器，只要发生特定动作（比如你点击“保存文件”），它就立刻响（自动检查代码），不需要你问。
• 子智能体 Subagent（外包小弟）：你把一个脏活累活丢到小黑屋让他自己干，干完把结果拿给你，不污染你现在的思路。
• MCP（外接工具柜）：比如扳手、螺丝刀（连通外部数据库或其他软件）。

学习内容 https://anthropic.skilljar.com/introduction-to-agent-skills/434528 预计耗时：15分钟

在本课结束时，你将能够：

• 比较技能（skills）与 CLAUDE.md、子智能体（subagents）、钩子（hooks）和 MCP 服务器
• 根据具体场景选择合适的 Claude Code 定制功能
• 设计高效结合多种功能的互补方案

技能与其他 Claude Code 功能对比

（3 分钟） Claude Code 提供多种自定义选项，选择不当可能会增加不必要的复杂性。本视频将深入解析在何时应使用技能（skill）、CLAUDE.md、子智能体（subagent）、钩子（hook）以及 MCP 服务器。你将掌握各选项之间的关键差异，并了解它们在典型开发环境中如何相互配合。

关键要点

• CLAUDE.md 会自动加载到每一次对话中，适用于始终启用的项目规范。技能（skill）按需加载，更适合任务专属的专业知识场景。
• 子智能体（subagent）在隔离的执行环境中运行——适用于委托处理的工作。技能则为当前对话增加知识支持。
• 钩子（hook）是事件驱动的（如保存文件、调用工具时触发），技能则是请求驱动的（根据你的提问激活）。
• MCP 服务器提供外部工具和集成——与技能完全属于不同类别。
• 每个功能都有自己的专长——建议组合使用，而不是强行将所有需求塞进一种方案。

Claude Code 提供多种自定义选项：技能（skill）、CLAUDE.md、子智能体（subagent）、钩子（hook）和 MCP 服务器。它们各自解决不同的问题，了解何时使用哪种功能，可以避免因误用而导致的开发偏差。下面我们将逐一解析这些功能。

CLAUDE.md 与技能（skills）的区别

CLAUDE.md 会在每次对话中自动加载，始终生效。如果你希望 Claude 在项目中使用 TypeScript 严格模式，只需将相关内容写入 CLAUDE.md 文件即可。

技能（skill）按需加载。当 Claude 将请求匹配到某个技能时，该技能的指令才会加入当前对话。例如，你的 PR 审查清单在编写新代码时无需加载到上下文中——只有当你请求进行代码审查时，它才会被激活。

CLAUDE.md 的适用场景：

• 项目范围内始终适用的标准
• 如“禁止修改数据库架构”等约束
• 框架偏好与编码风格

适合使用技能（skill）的场景：

• 任务专属的专业知识
• 仅在特定情况下才相关的知识
• 详细流程，如果每次都说明会让对话显得冗长

技能（skill）与子智能体（subagent）的区别

技能会为你当前的对话添加知识。当技能被激活时，其指令会并入现有的上下文。

子智能体（subagent）在独立的上下文中运行。它们接收任务，独立完成处理后返回结果，并与主会话完全隔离。

在以下情形下使用子智能体（subagent）：

• 你希望将任务委派到一个独立的执行上下文
• 你需要使用与主会话不同的工具访问权限
• 你希望委派的工作与主上下文相互隔离

在以下场景使用技能（skill）：

• 你希望为当前任务增强 Claude 的知识
• 该专业知识将在整个对话过程中生效

技能（skills）与钩子（hooks）的区别

钩子（hooks）会在特定事件发生时触发。例如，每当 Claude 保存文件时，钩子可以自动运行代码检查工具（linter），或在调用某些工具前验证输入。它们是事件驱动的。

技能（skills）是按请求驱动的，会根据你的需求自动激活。

钩子（hooks）的用途包括：

• 每次保存文件时应执行的操作
• 调用特定工具前的验证
• Claude 执行动作时的自动化副作用

技能（skills）可用于以下场景：

• 支撑 Claude 处理请求的知识
• 影响 Claude 推理的准则

整合运用

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

• CLAUDE.md — 持续生效的项目规范
• 技能（skills） — 按需加载的任务专用知识
• 钩子（hooks） — 由事件触发的自动化操作
• 子智能体（subagents） — 用于委派任务的隔离执行环境
• MCP 服务器 — 外部工具与集成

每种方式都有其专长。遇到更合适的选项时，不要勉强将所有内容都做成技能（skill）——并且你可以同时组合多种方式使用。技能（skills）会在任务相关时自动提供专用知识，CLAUDE.md 用于持续生效的指令，子智能体（subagents）在隔离环境中运行，钩子（hooks）响应事件触发，MCP 服务器则提供外部工具与支持。

当你掌握的知识需要在相关话题出现时由 Claude 自动应用时，请使用技能（skill），并结合其他功能，实现全面的定制化。

课程思考/反思

• 查看你当前的 CLAUDE.md 文件，其中是否有内容如果改为技能（skill），只在相关时加载会更合适？
• 思考一下你团队的开发流程。Claude Code 的哪些功能组合（技能、钩子、子智能体、MCP）能够解决你们最常遇到的痛点？

共享技能

💡 洞察与导读： 本质与通俗理解：在群体演化中，“网络效应”是决定工具价值的核心规律。一个人用叫“技巧”，一群人强制统一用就叫“标准”。 譬如：你写了一个特别好用的技能，怎么分发给其他人？

1. 放进代码仓库里，大家只要下载代码就自带了；
2. 扔到“应用商店（插件市场）”去，全世界的人都能下载；
3. 如果你是老板，可以通过“企业强制设置”把技能植入到所有员工的电脑里，这在强监管、高安全要求的公司特别有用。注意，“外包小弟（子智能体）”是白纸一张，如果要他干活，必须明确把技能绑定给他。

学习内容 https://anthropic.skilljar.com/introduction-to-agent-skills/434529 预计耗时：20分钟

在本课程结束时，你将能够：

• 将技能（skill）提交到 Git 代码仓库，与团队共享
• 通过插件和市场，将技能分发到各项目
• 使用企业托管设置，将技能部署到整个组织
• 配置自定义子智能体（subagent）以使用特定技能

技能共享

（4分钟） 当技能（skill）能在团队或整个组织中共享时，其价值将显著提升。本视频将介绍三种主要的分发方式——代码仓库（repo）提交、插件（plugins）以及企业托管设置（enterprise managed settings）——并讲解如何配置自定义子智能体（subagent）来使用技能。你将了解每种方法适用的场景，以及如何应对一个重要的注意事项：子智能体不会自动继承技能，需要手动指定。

主要要点

• 项目技能（skills）存放在 .claude/skills 目录中，会通过 Git 自动共享 —— 任何克隆该代码仓库（repo）的人都能直接获得这些技能
• 插件（plugins）可通过市场（marketplaces）将技能跨代码仓库分发，方便更广泛的社区使用
• 企业托管设置（enterprise managed settings）可在整个组织范围内部署技能，优先级最高，适用于强制标准和合规要求
• 子智能体（subagents）不会自动获取你的技能 —— 必须在自定义智能体的前置元数据（frontmatter）skills 字段中显式列出技能
• 内置智能体（Explorer、Plan、Verify）无法访问技能 —— 只有 .claude/agents 目录下定义的自定义子智能体可以使用技能

技能（skills）在共享后价值会显著提升。一个仅供你个人使用的 PR 审查技能固然有用，但将它共享给整个团队后，就能统一代码审查流程，为组织带来一致的体验。接下来我们将看看技能的不同分发方式。

将技能提交到你的代码仓库

最简单的共享方式是直接将技能（skill）提交到代码仓库。只需将技能放在 .claude/skills 目录中，任何克隆该仓库的人都会自动获得这些技能，无需额外安装。

当你推送更新后，所有人在下一次拉取（pull）时都会自动获取。这种方式非常适用于：

• 团队编码规范
• 项目专属工作流程
• 引用你代码库结构的技能（skill）

.claude 目录包含你的智能体（agent）、钩子（hook）、技能（skill）和设置——所有内容都通过常规 Git 工作流进行版本控制，并与团队共享。

通过插件分发技能（skills）

插件是一种扩展 Claude Code 的方式，可将自定义功能在团队和项目间共享。在你的插件项目中，创建一个 skills 目录，其文件结构应与 .claude 目录相同——每个技能（skill）都有独立的文件夹，并在其中放置一个 SKILL.md 文件。

当你将插件发布到插件市场后，其他用户可以自行在 Claude Code 中发现并安装它。 当你的技能（skill）并非高度依赖特定项目，并且能够为团队之外的社区成员提供价值时，这种方法最为适用。

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

管理员可通过托管设置在整个组织范围内部署技能（skill）。企业级技能优先级最高——同名技能将覆盖个人、项目和插件中的技能。

托管设置文件支持 strictKnownMarketplaces 等功能，用于控制插件的安装来源：

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

这是确保组织内部强制标准、安全要求、合规流程以及编码规范保持一致性的最佳选择。这里的关键词是“必须”。

技能（skills）与子智能体（subagents）

有一点常常让人意外：子智能体（subagent）并不会自动访问你的技能（skill）。当你将任务委派给子智能体时，它会在一个全新且干净的上下文中启动。

需要了解以下几个关键区别：

• 内置智能体（如 Explorer、Plan 和 Verify）无法访问技能（skill）
• 你定义的自定义子智能体（subagent）可以使用技能，但必须在配置中显式列出
• 技能会在子智能体启动时加载，而不是像主会话那样按需加载

要创建带技能的自定义子智能体，请在 .claude/agents 目录中添加一个智能体的 Markdown 文件。你可以在 Claude Code 中使用 /agents 命令进行交互式创建：

生成的智能体文件包含一个 skills（技能）字段，用于列出要加载的技能。前置元数据（frontmatter）如下所示：

---
name: frontend-security-accessibility-reviewer
description: "当你需要审查前端代码的可访问性时，请使用此智能体……"
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
model: sonnet
color: blue
skills: accessibility-audit, performance-check
---

当你将任务委托给该子智能体（subagent）时，它会加载上述两个技能（skill），并在每次审查中应用它们。请先确保这两个技能已存在于你的 .claude/skills 目录中，然后可新建一个子智能体，或在现有智能体的 markdown 文件中添加 skills 字段。

这种模式在以下情形下效果尤为显著：

• 你希望实现具备特定专业能力的隔离式任务委派
• 不同的子智能体（subagent）需要不同的技能（skill）（如前端评审与后端评审）
• 你希望在委派工作中强制执行标准，而不是依赖提示词

课程思考/反思

• 对于你计划构建的技能（skill），哪种分享方式最合适？（代码仓库（repo）、插件（plugin）、企业托管（enterprise））
• 在你的工作流程中，是否有通过定制子智能体（subagent）及专属技能（skill）来提升委派工作一致性的机会？

技能故障排查

💡 洞察与导读： 本质与通俗理解：系统工程有一个基本规律叫“熵增定律”，事情总会向混乱和出错的方向发展。排错（Debug）的核心思维是“控制变量”和“精准定位”。 对小白而言：技能不生效，通常只有三个原因：

1. 它没听懂暗号（未触发）：你在 description 里写的接客暗号是“帮我分析性能”，但你实际说的是“这玩意怎么这么慢”，它对不上号。所以要多写同义词。
2. 它根本找不到文件（未加载）：机器死板，大小写、文件夹名字哪怕错一个标点符号，它都会当做不存在。
3. 它没权限干活（运行时错误）：比如你要它执行一个脚本，但你没给那个文件赋予“可执行”的权限。通过官方给的检查器（validator），可以在执行前就把这些低级错误扫出来。

https://anthropic.skilljar.com/introduction-to-agent-skills/434530 课程内容 预计耗时：15分钟

在本课结束时，你将能够：

• 在调试前使用技能验证器（validator）捕捉结构性问题
• 诊断并修复常见的技能触发与加载故障
• 解决企业、个人、项目及插件技能之间的优先级冲突
• 调试运行时错误，包括依赖缺失、权限不足和路径异常

技能故障排查

（4分钟） 当技能（skill）未按预期运行时，问题通常归结为几个常见类别。本视频将逐一讲解这些情况——从技能未被触发、优先级冲突到运行时失败——并为你提供系统化的排查方法。你还将学习如何使用技能验证器工具（skills validator）以及 claude --debug 命令来诊断加载问题。

关键要点

• 优先使用技能验证器工具（skills validator），它能在你投入调试之前发现结构性问题。
• 如果技能（skill）无法触发，原因几乎总是描述（description）不匹配——请添加与你实际请求表达方式一致的触发短语（trigger phrases）。
• 如果技能无法加载，请检查 SKILL.md 是否位于命名目录内（而不是 skills 根目录），且文件名必须严格为 SKILL.md。
• 如果错误的技能被调用，说明你的描述过于相似——请让各技能描述更具区分度。
• 出现运行时错误时，请检查依赖项、文件权限（chmod +x）以及路径分隔符（始终使用正斜杠）。
• 当技能无法正常工作时，问题通常属于以下几类：技能无法触发、无法加载、存在冲突或运行时失败。好消息是，大多数修复方法都相当简单直接。

使用技能验证器

首先建议尝试运行智能体技能验证命令。不同操作系统的安装步骤有所差异，但使用 uv 工具是最快捷的安装方式。

安装完成后，您可以进入技能（skill）目录，也可以在任意位置运行该命令。验证器会在您开始调试其他问题之前先检测出结构性错误。

技能未触发

你的技能（skill）已存在并通过验证，但 Claude 并未在你预期的时机使用它。几乎所有情况下，原因都在于描述（description）。

Claude 使用语义匹配，因此你的请求必须与技能描述（description）的含义有一定重叠。若重叠不足，则无法匹配。建议你这样做：

• 检查你的描述（description）是否与实际请求的表达方式一致
• 添加用户真正会说的触发短语（trigger phrases）
• 用不同表达方式进行测试，例如：“帮我分析性能”、“为什么这么慢？”，“让它更快”
• 如果某种表达未能触发技能（skill），请将这些关键词补充到描述中

技能未加载

如果你在询问 Claude “有哪些可用技能”时没有看到你的技能，请检查以下结构要求：

• SKILL.md 文件必须放在有名称的目录中，不能直接置于 skills 根目录。
• 文件名必须严格为 SKILL.md ——“SKILL”全大写，“md”小写。
• 运行 claude --debug 命令可查看加载错误，留意包含你的技能（skill）名称的提示信息，有时这些提示就能直接定位问题。

错误技能被调用

如果 Claude 调用了错误的技能（skill）或在多个技能之间出现混淆，通常是因为你的描述（description）过于相似。请确保每个技能的描述有明显差异。尽量具体不仅能帮助 Claude 判断何时使用你的技能，还能有效避免与其他名称或内容相近的技能发生冲突。

技能优先级冲突

如果你的个人技能（skill）未被使用，可能是因为企业或更高优先级的技能存在同名情况。

例如，如果有一个企业级的“code-review”技能（skill），而你也拥有一个个人的“code-review”技能，那么每次都会优先使用企业级技能。你的选择包括：

• 将你的技能（skill）重命名为更具辨识度的名称（通常这是更简单的解决方案）
• 与管理员沟通企业技能（enterprise skill）相关事宜

插件技能未显示

已安装插件但看不到其技能？请清除缓存，重启 Claude Code，并重新安装插件。

如果技能（skill）依然未出现，可能是插件结构有误。这时，验证器（validator）工具就能发挥真正的作用了。

运行时错误

技能已成功加载，但在执行过程中出现失败。常见原因包括：

• 缺少依赖项：如果你的技能（skill）依赖外部包，必须提前安装。请在技能描述（description）中添加依赖信息，让 Claude 明确所需环境。
• 权限问题：脚本需要执行权限。对技能引用的所有脚本运行 chmod +x。
• 路径分隔符：无论操作系统，始终使用正斜杠（/）。

快速故障排查清单

1. 未触发？ 优化描述（description），并添加触发短语（trigger phrases）。
2. 未加载？ 检查路径、文件名和 YAML 语法。
3. 使用了错误技能？ 让各技能描述更具区分度。
4. 被覆盖（shadowed）？ 检查优先级层级（priority hierarchy），必要时重命名。
5. 插件技能丢失？ 清除缓存并重新安装。
6. 运行时失败？ 检查依赖项、权限和路径。

课程思考/反思

• 你在实际工作中遇到过上述故障排查场景吗？哪种修复方法能为你节省最多时间？
• 你会如何建立流程，在将技能分享给团队前进行验证？