播客听见世界的声音，看见思想的刻度

Claude Code 内置了若干子代理，而自定义子代理让你能针对特定任务接入专属行为。本教程从零开始创建一个代码审查子代理——演示 `/agents` 命令、工具选择、模型选取，以及决定 Claude 何时、如何进行任务委托的各个配置字段。 ## [00:03] 自定义子代理是什么 Claude Code 自带内置子代理，你也可以创建专注于特定任务的自定义子代理。自定义子代理本质上是一个带有 YAML frontmatter 的 Markdown 文件：frontmatter 告诉 Claude 何时路由到该代理以及它拥有哪些能力，Markdown 正文则是子代理运行时依赖的系统提示词。 > *"Custom sub aents are markdown files with YAML front matter. These markdown files contain configuration that helps claude understand when to use the sub aent and provides directions to the sub aent itself."* ## [00:28] 用 /agents 创建子代理 `/agents` 命令会打开代理管理面板。选择"创建新代理"后会依次询问两个问题：作用域（当前项目还是机器上所有项目共享）以及生成方式。推荐的做法是让 Claude 自动生成——教程中演示者用自然语言描述了一个"审查代码质量和安全问题"的需求，Claude 便会自动完成后续配置。 > *"Now, the easiest way to create a sub agent is with the / agents command. Next, you can create a sub agent manually, but we recommend using claw code to automatically generate it for you."* ## [00:56] 配置工具、模型与颜色 Claude 生成文件之前，你需要选择子代理可以使用哪些工具。代码审查代理其实不一定要开启编辑工具，但保留代码执行权限可以让它更方便地检视待提交的改动。工具选好之后，选择模型：haiku 主打速度，opus 追求深度，sonnet 居中。最后选一个颜色——它会显示在界面上，让你一眼认出是哪个子代理在运行。 > *"Now, given that our sub agent is only responsible for reviewing code, you might decide to disallow tools for editing, but I'll leave an execution to allow the sub agent to more easily identify pending changes."* ## [01:43] 读懂配置文件 生成的文件会保存到项目中，路径显示在摘要窗口里。有四个字段最为关键。`name` 是唯一标识符，在消息中输入 `@agent-code-quality-reviewer` 即可引用它。`description` 是 Claude 用来判断是否委托任务的依据，必须写在一行（转义的 `\n` 会被当作字面字符）。在描述里加上"proactively"，Claude 会更主动地调用该代理；加入示例对话则能让路由更准确。`tools` 与生成时授权的工具一致，但可以直接在文件里修改。 > *"If you want Claude to use the sub agent automatically more often, add in the word proactively to the description."* ## [02:41] 系统提示词与 Claude 的使用方式 `model` 字段接受 `haiku`、`sonnet`、`opus` 或 `inherit`——`inherit` 让子代理沿用父会话所用的模型。frontmatter 以下的所有内容就是系统提示词：它引导子代理完成任务，并告知它如何将结果返回给主代理。 > *"The system prompt will provide guidance to the sub agent, helping it understand how to complete its task and how it should return information back to the main agent."* ## [03:15] 测试你的子代理 保存配置后，修改几处代码，然后让 Claude 进行审查。如果子代理没有在预期的时机触发，`description` 字段是第一个排查点——加入更具体的示例，能帮助 Claude 更准确地判断何时进行委托。 > *"If the sub agent isn't being used when you expect, check your description. Adding more specific examples helps Claude understand when to delegate."* ## 实体 - **Anthropic Tutorial Narrator**（人物）：本集唯一主持人；在 Anthropic 官方 YouTube 频道主持 Claude Code 子代理系列教程 - **Claude Code**（软件）：Anthropic 的 AI 编程助手；同时支持内置子代理和用户自定义子代理 - **Custom subagent**（概念）：一个带有 YAML frontmatter 的 Markdown 文件，用于配置 Claude Code 将特定任务委托给专属代理实例 - **/agents command**（概念）：Claude Code 中创建和管理子代理的 UI 入口；支持项目级或全局作用域 - **System prompt**（概念）：子代理配置文件的 Markdown 正文；在运行时为子代理提供任务指引和输出格式说明 - **Anthropic**（组织）：Claude 和 Claude Code 平台的创建者

这是 Anthropic Claude Code 系列的教程，介绍四种让 subagent 稳定运行而不偏轨、卡死、误操作文件的核心模式。讲师以代码审查和网络搜索 subagent 为贯穿全程的示例，逐一拆解每个配置开关及其背后的原因。 ## [00:03] 通过名称和描述控制 subagent 行为 主上下文窗口 agent 收到的每条消息，都会在系统提示中附带已注册 subagent 的名称和描述。因此，描述承担双重职责：告诉 orchestrator *何时*启动 subagent，以及提供它在撰写输入提示时所依赖的模板。 教程以代码审查 subagent 为例。在原始配置中，orchestrator 只会写一个通用提示，让 subagent 自己去调用 `git diff`。把描述改成"你必须告诉 agent 精确指定要审查哪些文件"，文件选择的责任就转移到了 orchestrator 身上——下一次运行产生的输入提示明显更具体。同样的方法也适用于网络搜索 subagent：在描述中加上"返回可引用的来源"，主线程在委派任务时就会自动带上这条要求。 > *"If you want to better control when the main agent launches a sub agent automatically, you should modify the name and description."* ## [01:41] 定义输出格式 讲师指出，定义输出格式是所有改进中影响最大的一项。没有输出格式，subagent 就没有明确的完成信号——它会持续运行、不断积累上下文、消耗大量 token。 结构化的输出格式自然形成一个停止点：一旦必填字段都填满，subagent 就知道任务结束了。具体做法是在 subagent 的系统提示中直接加入明确的 schema——摘要块、发现列表、状态字段等。 > *"Without a defined output format, sub agents struggle to decide when enough research has been done and they tend to run much much longer than sub agents that are given an output format."* ## [02:04] 在摘要中上报阻碍 subagent 解决了某个问题——依赖冲突、需要额外参数的命令、环境异常——主线程如果得不到这些信息，下一步就会撞上同一堵墙。解决办法是在输出格式里就要求上报阻碍。 讲师列出了必须浮出水面的几类信息：遇到的阻碍、环境搭建问题、发现的变通方案、需要特殊参数或配置的命令、引发问题的依赖或 import。把这些信息写进必填 schema，主线程就能直接继承 subagent 的经验，而不必从头重新摸索。 > *"Otherwise, the main thread has to rediscover the same solutions, obstacles encountered, any setup issues, workarounds discovered or environment quirks, commands that needed special flags or configuration, dependencies or imports that cause problems."* ## [02:42] 按角色限制工具权限 工具权限不只是安全控制，也是一种清晰化工具。只有 `glob`、`grep`、`read` 的只读 subagent 不可能意外修改文件，任何人看到配置都能一眼明白它的职责。 讲师将三种权限层级对应到三种 subagent 角色：研究型 subagent 只需只读权限，因为探索代码库不需要写入；审查型 subagent 可以用 `bash` 跑 `git diff`，但仍无文件编辑权限；只有明确负责修改代码的 subagent——比如应用 CSS 更新的样式 agent——才授予 `edit` 和 `write`。当多个 subagent 并行运行时，工具列表就成了一份机器可读的职责说明书。 > *"Only give edit and write to sub agents that should actually change your code, like a styling agent applying CSS updates."* ## [03:27] 高效 subagent 的四种模式 教程以一句话收尾，回顾全部四种模式：结构化输出、阻碍上报、精准描述、限制工具权限。各模式相互加强——精准描述减少输入提示的歧义，输出格式创造停止点，阻碍上报在 agent 边界间传递上下文，最小工具权限防止副作用叠加、放大残余歧义。 > *"So effective sub agents use structured output report obstacles have specific descriptions and limit tool access."* ## 实体 - **Anthropic Tutorial Narrator**（人物）：Claude Code subagent 系列教程的主讲人，代表 Anthropic 出镜 - **Claude Code**（软件）：Anthropic 的 agentic 编程工具，负责编排 subagent 完成多步骤工程任务 - **Subagent**（概念）：由 orchestrator agent 启动的专用 Claude 实例，拥有独立的系统提示、工具权限和输入提示 - **输出格式**（概念）：在 subagent 系统提示中定义的必填 schema，形成停止条件，并将信息结构化地返回给主线程 - **阻碍上报**（概念）：要求 subagent 在输出中报告变通方案、依赖问题和环境异常，使 orchestrator 无需重新摸索 - **工具权限限制**（概念）：只给每个 subagent 分配其角色所需的工具——研究型只读、审查型可用 bash、需要修改文件的才给 edit/write - **Anthropic**（组织）：Claude 和 Claude Code agentic 编程平台的创建者

子智能体是 Claude Code 可以将任务委派给的专属助手——每个子智能体在独立的上下文窗口中运行，自主完成工作后，只将精炼的结果摘要返回主线程，中间过程的完整对话记录则被丢弃。这段来自 Anthropic 的两分钟教程介绍了隔离机制为何有助于保持主上下文窗口的可用性，通过代码探索场景直观呈现其中的权衡取舍，并列举了 Claude Code 目前内置的子智能体。 ## [00:03] 子智能体是什么 子智能体在独立的对话上下文窗口中运行，使用你自定义的系统提示初始化。父智能体（主线程中的 Claude Code）根据你的请求，向子智能体下发任务描述。子智能体自主完成任务后，将摘要结果返回主线程——所有中间步骤都在隔离环境中留存，不会进入主窗口。 > *"子智能体是专属助手，Claude 可以将任务委派给它们。"* 设计上的关键一点：子智能体完成任务后，其整个对话线程会被彻底丢弃，只有返回的摘要留存在主对话中。 ## [00:24] 管理上下文窗口 Claude 在主线程中的每次工具调用——读文件、搜索、函数追踪——都会在主上下文窗口中累积。长时间会话下，窗口很快就会被填满。子智能体存在的意义，正是将独立的调研或操作任务分流出去，避免这些开销落在主窗口里。 > *"每个子智能体在独立的对话上下文窗口中运行，使用你自定义的系统提示。"* 这里的权衡是明确的：主窗口获得了干净的上下文，但同时失去了对子智能体推理过程和中间发现的可见性。你得到的是答案，而不是完整的推理链路。 ## [01:13] 具体案例：支付系统 假设你在用 Claude Code 弄清楚一个陌生代码库中哪个服务负责处理退款。如果不用子智能体，Claude 可能需要读取 15 个文件、发起多次搜索、追踪多条函数调用链——这些内容全部会填入主上下文窗口，而你其实只需要一个结论。 > *"用子智能体，你只要答案，不需要经历整个探索过程。"* 子智能体探索代码库、找到答案后，只把精炼的摘要返回给主窗口，让主上下文保持整洁。代价是可见性的丧失：你看不到它读了哪些文件、追踪了哪些路径。 ## [02:00] Claude Code 内置子智能体 Claude Code 内置了三个开箱即用的子智能体： - **通用子智能体** — 适用于需要同时进行探索和操作的多步骤任务。 - **探索子智能体** — 快速搜索代码库，省去完整任务循环的开销。 - **规划子智能体** — 在规划模式下运行，先对代码库进行调研分析，再向你呈现规划方案。 > *"你也可以用自定义系统提示和工具权限创建自己的子智能体。"* 除这三个内置选项外，你还可以定义带有专属系统提示和工具访问列表的自定义子智能体，以适配特定工作流。 ## [02:30] 何时使用子智能体 当你有一个独立、边界清晰的问题或任务，且直接在主线程处理会产生大量中间上下文时，子智能体就能发挥价值。 > *"Claude Code 的子智能体将工作拆分成专注的小块，保持主上下文窗口整洁，只把你需要的内容带回来——无论是使用内置选项还是创建自己的子智能体。"* 在较长的 Claude Code 会话中，上下文窗口压力会持续累积，子智能体最能体现其价值——将子任务分流给子智能体，而不是让它在主线程中扩散，可以直接延长会话的有效时长。 ## 实体 - **Anthropic Tutorial Narrator**（人物）：Anthropic 出品的"Claude Code subagents"教程系列的旁白讲述者 - **Claude Code**（软件）：Anthropic 的智能编程助手；子智能体运行的宿主环境 - **Claude**（软件）：驱动 Claude Code 及其子智能体的底层 AI 模型 - **Sub-agent**（概念）：Claude Code 将任务委派给的专属助手，在独立上下文窗口中以自定义系统提示运行 - **Context window**（概念）：存放全部对话历史、工具调用及结果的有限 token 缓冲区；子智能体可防止中间工作将其填满 - **General-purpose sub-agent**（软件）：Claude Code 内置子智能体，适用于多步骤探索与操作任务 - **Explore sub-agent**（软件）：Claude Code 内置子智能体，针对代码库快速搜索优化 - **Plan sub-agent**（软件）：Claude Code 内置子智能体，在规划模式下对代码库进行调研后呈现规划方案 - **Anthropic**（组织）：Claude 和 Claude Code 的创建者；本教程系列的制作方

Claude Code skill 是可复用的 Markdown 文件，把专项知识写进去一次，Claude 就会在请求匹配时自动激活，无需用户重复说明，也不用手动输入斜杠命令。这个三分钟教程介绍 skill 是什么、存放在哪里、与 CLAUDE.md 有何区别，以及什么时候该动手写一个。 ## [00:03] Skill 解决的重复问题 每次向 Claude 解释团队的编码规范、重新描述你想要的 PR 反馈格式，或者提醒它你偏好的 commit message 风格——你都在重复自己。教程用三个连续的例子点出 skill 正是为了解决这个摩擦点而生。 > *"每次你向 Claude 解释团队的编码规范，你都在重复自己。"* ## [00:20] Skill 是什么，Claude 如何选中它 Skill 是一个 Markdown 文件，把某件事的做法一次性教给 Claude，之后遇到合适的场景就自动应用。在 Claude Code 里，这个文件叫做 SKILL.md。文件里的 description 字段是核心机制：当你让 Claude 审查某个 PR 时，它会把你的请求与所有可用 skill 的描述逐一比对，然后激活匹配的那个。 > *"Claude 读取你的请求，与所有可用 skill 的描述比对，然后激活匹配的。"* ## [01:05] Skill 的存放位置：个人与项目 Skill 有两个存放位置，取决于谁需要用到它。个人 skill 放在 `~/.claude/skills`，跨项目跟着你走：commit message 风格、文档格式、你希望代码怎么解释。项目 skill 放在仓库根目录下的 `.claude/skills`，任何克隆该仓库的人都自动获得。后者正是团队规范的归宿：品牌指南、网页设计惯用字体和颜色。 > *"任何克隆该仓库的人都能自动获得这些 skill。"* ## [01:42] Skill 与 CLAUDE.md：自动触发、节省上下文 Claude Code 有多个自定义层，skill 占据其中一个独特的位置。CLAUDE.md 无条件加载到每次对话中，适合"始终使用 TypeScript strict mode"这类规则。Skill 按需加载，仅在匹配当前请求时触发，且触发前只有名称和描述进入上下文，完整内容只在激活后才载入。这样一来，PR 审查清单在你调试时不会占用上下文，只在你真正发出审查请求时才被拉取。斜杠命令需要主动输入，skill 不需要。 > *"Skill 的独特之处在于：自动触发，任务专属。"* ## [02:27] 何时该写一个 skill Skill 最适合与特定任务绑定的专项知识：团队遵循的代码审查标准、commit message 格式、品牌指南。结尾的判断标准简单直接：如果你发现自己一遍遍向 Claude 解释同一件事，那就是一个等待被写下来的 skill。 > *"如果你发现自己一遍遍向 Claude 解释同一件事，那就是一个等待被写下来的 skill。"* ## 实体 - **Anthropic Tutorial Narrator**（人物）：Claude Code skills 教程系列的解说员和主持人 - **Claude Code**（软件）：Anthropic 的 AI 编程助手，skill 在其中被发现并应用的运行时环境 - **SKILL.md**（概念）：定义一个 skill 的 Markdown 文件，包含名称、描述和给 Claude 的指令 - **CLAUDE.md**（概念）：项目级或全局指令文件，无条件加载到每次 Claude Code 对话中，与 skill 形成对比 - **Anthropic**（组织）：Claude 和 Claude Code 的创造者

一个工程师用的 PR review 技能固然有用；同一技能推广到整个团队，就能统一代码审查标准，让组织内每次 review 体验一致。本教程介绍四种具体的分发方式——仓库提交、插件、企业托管设置和自定义子智能体——并说明各自的适用场景。子智能体部分有个容易踩坑的细节：子智能体不会自动继承技能，内置智能体更是完全无法访问技能。 ## [00:01] 共享为何能让技能价值倍增 技能留在一个开发者手里，只能发挥有限作用。推广到团队之后，标准得以固化，个人差异被消除，每次 review 的风格和结果都趋于一致。教程开篇用个体与团队规模的直接对比引入四种共享机制。 > *"A PR review skill that only you use is helpful. The same skill shared across your team standardizes code review and provides a consistent experience amongst your organization which is much better."* ## [00:18] 将技能提交到项目仓库 阻力最小的方式：把技能放进项目仓库的 `.claude/skills` 目录。任何克隆该仓库的人都能立即获得这些技能，无需额外安装步骤，也不依赖额外工具。更新随普通的 `git pull` 流程同步到位。适合团队编码规范、项目特定工作流，以及需要引用代码库自身结构的技能。 > *"Anyone who clones the repository gets these skills automatically. No extra installation, it's just what you're doing already."* ## [00:45] 通过插件分发技能 插件让 Claude Code 获得自定义功能，且可以突破单个项目的边界传播。在插件项目内，`skills/` 目录结构与 `.claude/` 一致——技能名称加 `SKILL.md`。发布到市场后，任何 Claude Code 用户都能下载并激活。通用性强、不局限于某个团队惯例的技能，走这条渠道最合适。 > *"Think of plugins as ways to extend Claude Code with custom functionality, but designed to be shared across teams and projects."* ## [01:26] 通过托管设置实现全企业部署 管理员可通过托管设置把技能推送给组织内每位开发者。企业技能的优先级最高，会覆盖同名的个人、项目和插件技能。适用场景是强制执行的标准——安全要求、合规流程、必须统一的编码规范。教程特意强调了"必须"二字：这些不是建议。 > *"This is for mandatory standards, security requirements, compliance workflows, or coding practices that must be consistent across the organization."* ## [01:52] 自定义子智能体与显式技能加载 子智能体不会继承主对话的技能。内置智能体（explorer、planner、verify）完全无法访问技能。只有通过 `.claude/agents` 中的 `agent.md` 文件定义的自定义子智能体才能使用技能，且仅限于该文件 `skills:` 字段中明确列出的那些。技能在子智能体启动时加载，而非按需加载，因此列表应保持精简——只放与该智能体任务始终相关的技能。教程演示了如何用 Claude Code 子智能体创建工具新建子智能体，并为现有 `agent.md` 附加技能。 > *"Built-in agents like the explorer, planner, and verify can't access skills at all. Only custom sub-agents you define can use them, and only when you explicitly list them."* ## [03:18] 总结：如何选择合适的分发方式 结尾对每种方式的适用场景做了归纳：项目目录对应团队访问，插件对应跨仓库共享，企业部署对应全组织强制标准，子智能体显式技能列表对应隔离的任务委托。最后再次点明子智能体的注意事项——只列出与该智能体任务始终相关的技能，因为技能在启动时加载，不会延迟加载。 > *"Share skills through project directories for team access, plugins for cross-repository distribution, or enterprise deployment for organization-wide standards."* ## 实体 - **Anthropic 教程讲解者** (人物)：Claude Code 技能教程系列的唯一主讲人 - **Claude Code** (软件)：Anthropic 开发的 AI 编程助手；技能的编写和部署运行环境 - **Skills（技能）** (概念)：放置于 `.claude/skills` 的可复用指令集，用于扩展 Claude Code 的行为 - **Plugins（插件）** (概念)：将技能打包、供团队和市场用户跨项目共享的可分发包 - **Managed settings（托管设置）** (概念)：企业管理员机制，以最高优先级在全组织范围内部署技能 - **Sub-agents（子智能体）** (概念)：通过 `.claude/agents` 中的 `agent.md` 定义的自定义 Claude Code 智能体；唯一能加载技能的智能体类型，且须显式列出 - **Anthropic** (组织)：Claude Code 的开发公司，也是 Claude Code 技能教程系列的出品方

这是 Claude Code skills 系列中一期四分钟的教程，聚焦于将基础 skill 打磨成可靠、上下文高效工具的高级配置字段。讲师逐一拆解 agentskills.io 的完整字段集——`name`、`description`、`allowed_tools`、`model`——并说明如何借助渐进式披露来组织大型 skill，让参考资料和脚本只在用户请求真正需要时才加载，而非每次调用都全量注入。 ## [00:02] 高级 skill 字段概览 agentskills.io 开放标准在必填的 `name` 和 `description` 之外还定义了若干字段。`name` 只能包含小写字母和连字符，上限 64 个字符，且必须与目录名一致。`description` 最多 1,024 个字符，是 Claude 进行 skill 匹配时最主要的参考信号。此外还有两个可选字段：`allowed_tools` 限制 skill 可调用的工具范围，`model` 则将 skill 锁定到指定的 Claude 版本。 > *"只需 name 和 description，一个基础 skill 就能跑起来——但这里还有一些高级技巧，能让你的 skill 在 Claude Code 里更加好用。"* ## [00:39] 如何写出有效的描述 描述含糊——比如"help with dogs"——只会让 Claude 猜测 skill 的适用范围和触发时机。好的描述只需回答两个问题：这个 skill 做什么？什么时候该用它？把关键词对齐到用户自然表达方式，是修复那些无法正确触发的 skill 最直接的手段。 > *"一个好的描述要回答两个问题：这个 skill 做什么？以及，什么时候该用它？"* ## [01:20] 用 allowed_tools 限制工具权限 `allowed_tools` 是把 skill 锁定到特定操作面的机制——比如为安全敏感的工作流实现只读访问。一旦设置该字段，Claude 只能调用其中列出的工具，无需额外申请权限；编辑、写入、Bash 命令一概不可用。不填该字段，Claude 的常规权限模型保持不变。 > *"当这个 skill 激活时，Claude 只能使用这些工具，无需申请权限。没有编辑、没有写入、没有 bash 命令。"* ## [01:49] 多文件 skill 的渐进式披露 skill 与对话共享 Claude 的上下文窗口。把所有内容塞进一个两万行的 `SKILL.md` 不仅每次调用都会撑爆上下文，维护起来也极其痛苦。解决方案：把核心指令放在 `SKILL.md`，把参考资料移入单独文件，只有用户请求确实涉及时才让 Claude 读取。标准建议设立三个辅助目录——`scripts/` 放可执行代码，`references/` 放文档，`assets/` 放图片和模板。`SKILL.md` 里的链接相当于目录条目；如果某个话题始终没被提到，对应文件就永远不会加载。 skill 目录里的脚本在执行时不会将源码加载进上下文——只有输出结果才消耗 token。讲师建议把 `SKILL.md` 控制在 500 行以内；超出这个数字，就该考虑把 skill 拆开了。 > *"这就像在上下文窗口里放了一张目录，而不是把整本书都塞进去。"* ## [03:18] 总结：skill 元数据与最佳实践 教程最后重申了完整的配置面：`name` 和 `description` 必填；`allowed_tools` 限制工具范围；`model` 锁定 Claude 版本。描述需要包含具体的动词和触发短语，才能可靠匹配。对于较大的 skill，渐进式披露能把 `SKILL.md` 控制在 500 行以内，把辅助文件推迟到真正需要时再加载。脚本执行时不加载源码，上下文保持精简。 > *"脚本可以在不加载其内容的情况下执行，让上下文保持高效。"* ## 实体 - **Anthropic 教程讲师** (人物): 该教程系列的独家主讲，负责讲解 Claude Code skill 配置。 - **Claude Code** (软件): Anthropic 开发的 CLI 工具，用于加载和执行基于 agentskills.io 标准的 skill。 - **agentskills.io** (组织): 定义 skill manifest 规范的开放标准，涵盖 `name`、`description`、`allowed_tools`、`model` 及目录约定。 - **SKILL.md** (概念): Claude Code skill 的主要 manifest 文件，建议保持在 500 行以内，并通过链接指向辅助文件。 - **allowed_tools** (概念): 可选 skill 字段，白名单指定 Claude 可用的工具，实现只读或沙箱化的 skill 模式。 - **渐进式披露** (概念): 多文件 skill 的组织策略，让参考文件和脚本仅在当前请求实际需要时才加载进上下文。 - **上下文窗口** (概念): 对话与 skill 文件共用的 token 配额；渐进式披露设计的核心目标就是节约这一资源。

这个 3 分钟教程从头演示如何构建一个 Claude Code 个人技能：创建包含 SKILL.md 的目录、确认技能在启动时加载、并观察 Claude 将其应用到真实请求。后半段深入拆解技能加载流程——四个扫描位置、仅加载名称的启动过程、确认门控机制，以及解决命名冲突的四层优先级顺序。 ## [00:03] 本教程要做什么 开篇直接点出目标：构建一个让 Claude 用视觉图示和类比来解释代码的技能。技能建好之后，教程还会追踪 Claude 内部接收并执行技能时的完整过程。 > *"This skill will teach Claude how we would like it to explain code using visual diagrams and analogies."* ## [00:18] 创建技能文件 个人技能放在主目录下（不在项目内部），所以第一步是在 `~/.claude/skills/` 里新建一个以技能名命名的目录，目录内只需放一个 SKILL.md 文件。文件中有三处关键：`name`（Claude 启动时存储的标识符）、`description`（Claude 判断是否触发该技能的匹配依据），以及第二个 `---` 分隔符之后的内容（技能触发后 Claude 实际执行的指令）。 > *"Take into consideration that we're creating a directory with the skill name inside of the skills directory."* ## [00:52] 加载并测试你的技能 Claude Code 在启动时扫描技能，而非按需扫描，因此创建文件后必须重启会话。运行 `/skills` 应能看到刚刚创建的技能名称。要测试它，切换到一个有改动的分支，然后用自然语言发出请求"Write a PR description for my changes"——Claude 会提示正在调用该技能，随后读取 diff 并按模板输出描述，每次格式完全一致。 > *"Claude will then show you that it's using the PR description skill."* ## [01:25] Claude 在幕后如何加载技能 启动时，Claude Code 扫描四个位置：企业托管设置、个人 `~/.claude/skills/`、项目 `.claude/` 目录、已安装的插件。它只加载 `name` 和 `description`，不加载完整内容。请求到来时，Claude 将其与已存储的描述进行对比——"explain what this function does"与"explain code with visual diagrams"有重叠，于是技能匹配成功。Claude 在读取完整 SKILL.md 前会请求用户确认，让用户始终清楚哪些上下文被注入进来。 > *"It loads only the name and description of each skill, not the full content. This is important later."* ## [02:02] 优先级规则与命名冲突 克隆一个内置技能的仓库可能引发命名冲突。Claude 用固定优先级来解决：企业（最高）→ 个人 → 项目 → 插件（最低）。企业的 `code-review` 技能始终覆盖同名的个人技能。实际的解决办法是使用描述性命名：用 `security-review` 或 `frontend-pr-review` 替代泛化的 `review`，从源头避免冲突。 > *"If your company has an enterprise code review skill and you create a personal code review skill, the enterprise version of that takes precedence."* ## [02:52] 更新与删除技能 更新技能只需直接编辑 SKILL.md，保存即可。删除技能则是删除整个目录。两种操作都需要重启 Claude Code 才能生效——技能列表在会话启动时一次性构建，不会实时监听文件变动。 > *"Edit the skill.md file to update a skill and restart Claude Code for changes to take effect."* ## 实体 - **Anthropic 教程讲解者** (人物): 主持 Claude Code 技能系列教程、逐步演示技能创建流程的唯一主讲人 - **Claude Code** (软件): Anthropic 的 Claude CLI；在启动时扫描技能，并在用户请求与技能描述匹配时自动应用 - **SKILL.md** (概念): 定义一个技能的唯一文件——包含 YAML frontmatter（name、description）以及第二个 `---` 分隔符后的自由格式指令文本 - **技能** (概念): 可复用的、有命名的指令集，教会 Claude 一种固定行为模式；以包含 SKILL.md 的目录形式存储 - **企业技能** (概念): 由组织统一管理的技能，处于四层优先级的顶端，覆盖个人、项目和插件技能 - **Anthropic** (组织): Claude 和 Claude Code 的创造者；在 claude.com/resources/courses 发布本系列教程

Claude Code 为开发者提供了五种不同的定制方式——Skills、CLAUDE.md、子代理、Hooks 和 MCP 服务器——每种都有其适用场景。这段三分钟教程将每个选项与正确的使用场景对应起来，让你不会在 CLAUDE.md 就能解决的情况下去写 Skills，也不会在需要子代理的地方错用 Hooks。 ## [00:02] 五种定制方式，一个选择难题 Claude Code 提供五种行为定制方式：Skills、CLAUDE.md、子代理、Hooks 和 MCP 服务器。讲解者快速列出这五种方式后，立即把问题从"这些是什么"转向"哪种适合这里"。 > *"它们各自解决不同的问题。知道什么时候用哪种，才能避免选错工具。"* 后续内容本质上都是围绕这一句话展开的。 ## [00:18] CLAUDE.md vs Skills：常驻 vs 按需加载 CLAUDE.md 是 Claude 每次对话开始时都会读取的文件，无需任何激活操作。项目级别的约束——框架选择、代码风格、数据库规则——这些必须时刻生效的内容放在这里最合适。Skills 则是按需加载：PR review 检查清单只在你真正发起 review 请求时才进入上下文，写新代码时不会干扰。 > *"Use Claude MD for project-wise standards that always apply constraints like never modify the database schema, framework preferences, and coding style."* 区分标准是持久性与相关性。如果某条规则对项目里的每个提示都必须生效，放 CLAUDE.md；如果只在特定场景才有用，放 Skills。 ## [01:03] Skills vs 子代理：共享上下文 vs 隔离执行 Skills 把知识注入当前对话——其指令会加入已有的上下文。子代理的运作方式不同：接到任务后在独立的执行上下文中运行，与主对话互不干扰，完成后返回结果。 > *"Use sub agents when you want to delegate a task to a separate execution context. You need different tool access that the main conversation does. You want isolation between delegated work and your main context."* 当专业知识需要贯穿整个对话时，用 Skills；当需要在主会话和委托任务之间划清边界——不同的工具权限、零污染——用子代理。 ## [01:42] Hooks vs Skills：事件驱动 vs 请求驱动 Hooks 在事件触发时自动运行——Claude 每次保存文件时跑 linter，或在特定工具调用前校验输入。它们的触发依据不是你的提问，而是 Claude 的行为。Skills 正好相反：由请求驱动，当查询与之匹配时才激活。 > *"A hook might run a llinter every time Claude saves a file or validate input before certain tool calls. They're all event driven, while skills, they're request driven. They activate based on what you're asking."* 如果某个行为必须在系统事件时无条件发生，用 Hooks；如果是希望在被询问时影响 Claude 的思路，用 Skills。 ## [02:15] 五种机制组合使用，实现全面定制 配置得当的 Claude Code 让每种工具发挥自己最擅长的作用：CLAUDE.md 承载始终生效的项目规范，Skills 提供不应污染每个提示的任务专项知识，Hooks 处理自动化副作用，子代理负责隔离的委托任务，MCP 服务器接入外部工具。它们不是相互替代的关系，而是可以自由组合。 > *"Don't force everything into skills when another option fits best. You can use multiple at a time."* Skills 在话题相关时自动激活；CLAUDE.md 始终存在；子代理在隔离环境中运行；Hooks 在事件触发时执行；MCP 提供外部工具接入。针对每个关切选对层，然后自由组合。 ## 实体 - **Anthropic 教程讲解者** (人物)：本 Claude Code skills 教程系列的主持人，代表 Anthropic 发布内容。 - **Claude Code** (软件)：Anthropic 推出的 AI 编程助手；本教程系列的主题。 - **Skills** (概念)：按需激活的知识包，当 Claude 匹配到用户请求时载入，将指令注入当前对话上下文。 - **CLAUDE.md** (概念)：每次 Claude Code 对话自动加载的配置文件；用于存放始终生效的项目级标准与约束。 - **子代理** (概念)：为处理委托任务而独立启动的执行上下文，与主对话完全隔离。 - **Hooks** (概念)：在特定 Claude 行为（如文件保存、工具调用）上自动触发的事件驱动自动化，与用户请求无关。 - **MCP 服务器** (软件)：Model Context Protocol 服务器，为 Claude Code 会话提供外部工具接入。 - **Anthropic** (组织)：Claude Code 的创建者，Claude Code skills 教程系列的出品方。