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

这是 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 的创建者；本教程系列的制作方

陶哲轩与 Dwarkesh 以开普勒发现行星运动定律为切入点，探讨 AI 究竟在改变科学的哪些环节。陶哲轩认为，假设生成如今近乎零成本，瓶颈已转移到评估、同行评审和时间检验。当前 AI 胜在广度（对每个问题穷举所有标准技术），人类胜在深度（在局部进展上逐步累积），因此人机协同模式将在数学领域至少主导十年。 ## [00:00] 开普勒是一个高温 LLM 陶哲轩重述了开普勒发现行星运动三大定律的过程。开普勒最初的理论虽有美感却是错的——他设想柏拉图多面体嵌套在行星轨道之间——直到多年苦苦研磨第谷·布拉赫偷来的裸眼观测数据后，才终于放弃。椭圆轨道、等面积定律和三次方-二次方定律，都是十年数据分析的产物，牛顿的解释则要再等一个世纪。 Dwarkesh 的框架是：开普勒更像一个高温 LLM，对照可验证的数据集循环尝试随机关系。陶哲轩认可这一机制，但对瓶颈所在提出了不同看法：想法生成本就不是问题，开普勒从不缺乏理论，他真正需要的是第谷那比前人精确一个量级的数据，以及耐心地丢弃被数据否定的想法。 > *但正如你所说，这必须与等量的验证相匹配，否则就是垃圾。* ## [11:44] 如何在大量 AI 垃圾内容中发现新的统一概念？ 陶哲轩：如果 AI 已将想法生成的成本压至近乎零，同行评审和时间检验就成了新的约束。学术期刊已被 AI 生成的投稿淹没。任何想法的地位取决于后续科学如何利用它——哥白尼在开普勒完善体系前，精度甚至不如托勒密——因此在当下很难做到自动化评估。 Dwarkesh 问：如何在数百万篇平庸论文中识别出贝尔实验室式的统一概念（香农的比特、Transformer）？陶哲轩的回答指向了可能仍是人类专属的那部分：科学家不只是产出理论，他们还要讲出能说服其他科学家投入数年去跟进的故事。达尔文的散文所做的工作，是牛顿的拉丁方程式做不到的。 > *AI 将想法生成的成本压低到近乎零，与互联网将通信成本压低到近乎零的方式非常相似。* ## [26:10] 演绎悬量 陶哲轩谈到现有数据中尚未充分挖掘的信号。几个世纪以来，天文学一直是那门从最少数据中提取最多信息的学科，这也是为什么量化对冲基金格外青睐天文学博士。他举了一个喜欢的例子：研究人员通过追踪错别字在引用链中的传播，来测量科学家实际阅读被引论文的频率。 他建议，用同样的科学社会学方法来分析 AI 进展本身——挖掘引用模式、会议提及及其他痕迹，来判断某项成果是否真正构成进步，而不是慢慢等待时间检验。 > *一个启示是，许多领域的演绎悬量可能远比人们意识到的要大。* ## [30:31] AI 发现报告中的选择偏差 AI 解决了约 1100 道 Erdős 问题中的大约 50 道，随后停滞。陶哲轩解释了选择效应：这 50 道题几乎没有文献基础，一种冷僻技巧加上一个已知结论就够了，而 AI 工具正擅长"穷举所有标准组合"。当一道题已有 80% 的工作被现有方法完成，AI 就能解决；一旦需要真正新颖的技巧，工具就会卡住，系统性扫描的逐题成功率只有 1% 到 2%。 陶哲轩的比喻：AI 工具是在山脉中黑暗里乱跳的机器人。它们能越过人类够不到的矮墙，但无法抓住一个支点、停在那里、再从局部进展往上拉。乐观的解读是：一旦 AI 达到某个水平，就能在百万道题上同时跑百万个副本，这是任何人类团体都做不到的；而这个结构性原因也意味着，科学需要真正能利用广度的新范式。 > *它们擅长广度，而人类，至少是人类专家，擅长深度。* ## [46:43] AI 让论文更丰富、更广泛，但并不更深刻 陶哲轩谈自己的工作方式：论文现在包含了更多代码、更多图表、更深的文献综述，因为辅助性工作的成本大约降低了 5 倍。真正的核心——攻克问题最难的部分——仍然靠纸笔完成。他不愿说自己"生产力提升了 2 倍"，因为衡量标准本身不是线性的；改变的是他所写的论文类型，而不是他解答最初问题的速度。 聪明与智识的区别也指向同一个地方。两个人合作解一道数学题时，每一个失败的尝试都会成为下一次的立足点。而现有 AI 每次新开会话都会忘掉上次弄清楚的东西，缺少那个累积叠加的拉升步骤，只有蛮力试错，以及最终被吸收进下一轮训练。 > *它让论文更丰富、更广泛，但不一定更深刻。* ## [53:00] 如果 AI 解决了一个问题，人类能从中获得理解吗？ AI 能用 Lean 证明黎曼猜想，却让我们一无所获吗？陶哲轩并不担心。Lean 的特性是任何证明都可以被原子化分解——每个引理都可以单独检查、消融测试和验证。因此，即便是一个 3000 行的生成证明也能成为原材料：其他 AI 可以重构以提升优雅性，人类可以从中提取概念内容，即便原始推导过程是不透明的，产物仍然有价值。 他预言会涌现出一整个职业：专门把 Lean 生成的庞大证明拆解开来、从中找出内在想法的数学家——一种证明考古学，人类判断力与 AI 消融工具并用。 > *你会从人类与这些工具协同互动中获得更多收益。* ## [59:20] 我们需要一种半形式化语言来描述科学家实际交流的方式 Dwarkesh 问，一种描述数学策略（而非数学证明）的半形式化语言会是什么样的。陶哲轩从高斯的质数定理谈起——数学中第一个重大统计猜想，在任何证明出现之前就从原始数据中推导出来——再到孪生素数猜想，数学家相信它成立，是因为素数的随机模型预测了这一点。数学兼具严格证明和严格启发式推理，但只有证明的一侧被形式化成了 Lean 能检验的东西。 启发式一侧迟迟未被形式化，原因在于：任何可用 RL 评分的评判器都会成为被攻击的目标，而"这个论证令人信服"的主观部分目前还不存在可供利用的可量化框架。陶哲轩希望有一种方法能大规模评测猜想生成和策略选择，或许可以通过在玩具数学宇宙中跑小型 AI，观察什么样的策略会自然涌现。 > *科学有某种主观性，我们还不知道如何把它捕捉成一种能让 AI 有效介入的形式。* ## [69:48] 陶哲轩如何分配时间 陶哲轩谈自己吸收新子领域的方式。用伯林的分类，他把自己定位成"狐狸"——对很多事情了解一点，必要时也会变成"刺猬"。驱动力是一种追求完整的执念：只要有另一位数学家用他不懂的技巧证明了某个结果，他就必须弄清楚对方的诀窍是什么。（出于同样的原因，他不得不戒掉了电子游戏。）与其他数学家合作是主要方式，而在博客上写下东西是他后来发展出来的记忆辅助手段——因为他反复在推导出某个结论的六个月后，又在辩论中丢失了它。 在日程安排上，陶哲轩刻意为偶然性留出空间。他不愿把时间排得太满，以至于再也不会偶然坐进一个超出自己舒适区的会议。在高等研究院度过的那一年印证了这个陷阱——两周的纯研究很美好，之后灵感就枯竭了。下一个书架上的意外发现、走廊里随口的闲聊、那个他勉强去参加的会议，实际上发挥的作用远比看起来大。 > *那些偶然的互动可能看起来并不最优，但它们其实非常重要。* ## [77:05] 人机混合将在数学领域主导更长时间 AI 什么时候能独立做数学？陶哲轩重新框定了这个问题——AI 其实已经在做人类做不到的数学了，计算器就是如此，只是在不同的前沿。他预计在大约十年内，研究生目前所做的大部分工作——运用标准技巧、梳理文献——会转移给 AI，但整个领域会像计算机代数系统吸收符号积分时那样整体上移一层。基因学在测序变得廉价后并没有终结，它只是扩展到了生态系统层面。数学也会如此。 他给当下入行的学生的建议是：假设变化会发生，但仍用传统方式取得资质——目前还没有什么能替代老老实实走一遍数学的传统路径。同时，保持足够的适应性，能够运用全新的研究模式，包括那些现在还不存在的模式。一个值得注意的事实是：借助 AI 工具和 Lean，一个高中生今天就能为真正的数学研究做出贡献，这在五年前是不可能的。 > *我确实相信，人机混合将在数学领域主导更长时间。* ## 实体 - **陶哲轩** (人物): 菲尔兹奖得主（2006年），UCLA 数学家，长期撰写关于 AI 在数学研究中的作用的文章。 - **Dwarkesh Patel** (人物): Dwarkesh Podcast 主持人，专注于 AI、科学与技术的长篇访谈。 - **Johannes Kepler** (人物): 天文学家（1571-1630），从第谷·布拉赫的观测数据中推导出行星运动三大定律。 - **Tycho Brahe** (人物): 丹麦裸眼天文学家，其数十年的行星观测数据正是开普勒所需要的数据集。 - **Lean** (软件): 数学证明助手，形式化的证明可在其中被检验、分解和消融测试。 - **Erdős 问题** (概念): Paul Erdős 提出的约 1100 道未解问题；AI 已解决大约 50 道，几乎都是先前文献极少的题目。 - **演绎悬量** (概念): 现有数据中已编码了远比已被提取的更多的可推导知识，天文学是这一概念的典型模型。 - **黎曼猜想** (概念): 关于素数分布的未解猜想；用来检验 AI 证明能否推进人类数学理解的测试案例。

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 教程系列的出品方。