Agent Skills¶

1、课程介绍¶

Skills 对智能体是渐进式披露的，Skill 的名称和描述始终存在于智能体的上下文窗口中，但直到用户请求与 Skill 的描述匹配时，智能体才会将剩余的指令加载到其上下文中。那时，智能体可能还会根据需要额外加载引用文件和资源文件。

要使用 Skill，你的智能体需要一组基本工具：用于读写文件的文件系统访问权限和用于执行代码的 bash 工具。这些工具使智能体能够执行 Skill 所需的任何命令。

智能体可以将 Skills 与 MCP 和子智能体结合，创建强大的智能工作流。例如，它可以使用 MCP 从外部源获取数据，然后依靠 Skill 知道如何处理这些数据或如何高效检索数据。它还可以将任务委托给具有隔离上下文的子智能体，而子智能体本身也可以使用 Skills 获取专业知识。

每个 Skill 都有一个必需的 SKILL.md 文件，其中包含 YAML 前置元数据，名称、描述和主要指令。主要指令还可以引用其他文件，如脚本、额外的 Markdown 文件以及模板和图片等资源。

名称和描述不仅是 Claude 分析你的 Skill 功能的方式，也是检测何时使用该特定 Skill 的方式。

名称有最大字符限制，描述也一样。名称通常使用动词+ing 形式。描述不仅要说明 Skill 做什么，还要说明何时使用。如果有特定关键词会导致智能体触发这个 Skill，一定要充分利用这些词。

除了必填字段外，Agent Skills 规范还允许可选字段。这可以是许可证、兼容性以及元数据中的任意键值对。

在 YAML 前置元数据之后，进入 Skill 的主体部分，我们对 Skill 的格式没有底层限制。但在构建可预测的工作流时，你需要确保有逐步说明。正如我们在其他 Skills（尤其是 skill-creator）中看到的，指定边界情况、逐步说明以及如果有理由跳过某一步，要明确说明原因。

通常，保持在 500 行以内是最佳实践，因为我们可以在需要时引用外部文件、资源和脚本。

对于涉及多个 Skills 的更复杂工作流，将事情分解为顺序步骤总是比拥有一个试图完成所有事情的极其庞大的 Skill 更有价值。

规范中有可选目录的空间，有 scripts、references 和 assets 的子文件夹。

scripts 包含需要读取和执行的代码。要确保有错误处理和清晰的文档。
references 参考资料。
assets 包含输出模板、图像、徽标、数据文件、模式等。

2、Skills 的意义¶

创建 Skill 时，只要所有文件都在同一个父文件夹中，Skill 就可以引用其他文件。

Skills 是可组合的。我们可以将自定义 Skills 与内置 Skills 结合使用。我们不仅可以使用多个 Skills，还可以将它们组合起来构建复杂且可预测的工作流。

为了避免用可能不需要的数据污染上下文窗口，Skills 引入了渐进式披露的概念。当从文件系统加载 Skills 时，只有 Skill 的名称和描述被添加到上下文窗口中。这对于 Claude 或任何其他系统知道 Skill 是什么以及如何触发它至关重要。

一旦 Skill 被触发，底层的 SKILL.md 被加载。这是将数据加载到上下文中的下一阶段。根据需要，如果有额外的文件或脚本需要加载和执行，它们将被逐步加载。

这些额外资源可以按需加载，如果有脚本需要加载，这些脚本与上下文窗口分开加载和执行，以避免用不必要的额外 token 污染上下文。

通过使用 bash 和文件系统等工具，Claude 可以只加载必要的信息，只执行必要的脚本和文件读取，并有意识地将必要的内容添加到上下文窗口中。

3、Skill、工具、MCP¶

引入 MCP 服务器来获取所需的上下文。
引入 Skills 来实现可重复的工作流。

MCP¶

当我们比较 Skills 与 MCP 时，主要考虑的是与外部数据系统的协作以及引入所需的工具和资源。MCP 将我们的智能体或 AI 应用与外部系统和数据连接起来。可以是外部数据库、Google Drive 的数据等各类系统。任何时候需要模型不知道的外部数据和上下文时，MCP 都非常有用。

你的 Skills 可以利用 MCP 提供的底层工具和数据，教会你的智能体如何处理这些数据。可以把 MCP 想象成带来所有底层工具，而 Skill 则是将这些工具组合起来构建特定工作流的指令集，这些工作流是可重复的，并能产生你期望的数据。

工具¶

关于 Skills 与工具的对比，我喜欢用比喻：工具有点像更底层的概念。想象你有锤子、锯子和钉子。而你有技能，比如如何建造书架。

工具本身是访问系统和为智能体提供完成任务所需能力的底层方式。实际上，工具在底层驱动着生成 Skills、读取 Skills，甚至创建用于执行代码和加载这些 Skills 的文件系统的能力。

Skills 通过专业知识扩展能力，引入需要执行的额外文件和脚本。但执行这些底层脚本、加载文件和文件夹的能力是由工具提供的。有内置在某些智能体生态系统中的工具，有我们自己编写的工具，还有通过 MCP 加载的工具。

工具定义始终存在于上下文窗口中，而 Skills 在必要时逐步加载。

4、预建 Skills¶

在 github.com/anthropic/skills 仓库中，查看 skills 文件夹有哪些内置 Skills。

skill-creator 是一个以编程方式为你创建 Skills 的 Skill。

在 SKILL.md 文件中，我们指定了 Skill 是什么，它提供什么，然后包含了一些与 Skills 相关的最佳实践。

在查看 skill 创建过程时，我们在这里的步骤非常明确。因为我们希望这个 Skill 创建一个可预测的工作流，所以我们对步骤、如何遵循它们以及只有在有原因的情况下才跳过哪一步非常明确。

当开始初始化 Skill 时，运行底层的 Python 脚本来执行必要的任务。在 scripts 文件夹中，有三个 Python 文件：

初始化 Skill 并提供底层文本的脚本。初始化脚本使用现有的模板（带有 YAML 前置元数据、占位符和待办事项），并根据传入的数据填充内容。
打包该 Skill 的 Python 文件。
验证该 Skill 的脚本。确保 SKILL.md 存在，验证 YAML 前置元数据，并确保文件夹和文件中的内容正确。

我们将利用这个 skill-creator Skill 将现有内容打包成可重用和模块化的脚本。

5、创建自定义 Skills¶

如果需要扩展，我们总是可以包含底层的引用文件。

对于输出格式，我们指定它取决于用户请求。我们没有直接给出每种输出类型的例子，而是引用了 assets 文件夹中的模板。

如果需要特定的输出格式，不要把所有内容都放在 SKILL.md 中，而是在外部资源或文件中引用。记住，这些模板只有在需要时才会加载。因此，我们可以通过只加载所需数据格式的特定文件来高效使用 token 和上下文窗口。

使用 skill-creator 来评估 Skills 对最佳实践的遵循情况。使用并行子智能体来加速评估。

评估 Skills 的一个好方法是通过 skill-creator 运行它们。但如何确保 Skills 按预期工作呢？

我们可以为 Skills 编写单元测试，就像为软件编写单元测试一样。

6、在 Claude API 中使用 Skills¶

要在 Claude API 中使用 Skills，需要使用代码执行工具和 Files API。这将使 Claude 具备文件系统访问权限（用于读写文件）和 bash（用于执行代码）。

我们从 Claude AI 和 Claude Desktop 中的 Skills 开始，现在转向如何通过 Claude Messages API 使用 Skills。

有几点需要确保我们理解。

第一，你在 Claude AI 和 Claude Desktop 中创建的 Skills 不会与 Claude API 或 Claude Code 共享。

第二，要使用 Skills，我们需要让 Claude 具备执行代码、创建和编辑文档、演示文稿、PDF、数据报告以及与文件系统交互的能力。当使用 Claude API 时，这些都需要手动配置，而在使用 Claude AI 和 Claude Desktop 时，这些是为您直接配置好的。

在 Claude Desktop 或 Claude AI 中，如果我进入设置查看功能配置，你会看到一个叫做"代码执行和文件创建"的部分。这是我们在直接使用 API 时要深入探讨的部分。这个设置默认开启，允许 Claude 执行代码、创建文档、电子表格、演示文稿等。这本质上为 Claude AI 和 Claude Desktop 提供了一台计算机或虚拟机来执行代码并完成使 Skills 工作的所有事情。如果禁用此功能，我们需要在使用 Skills 前将其打开。

现在我们对代码执行工具和文件创建在 Claude AI 和 Desktop 中的工作原理有了更好的理解，我们来谈谈它在底层是如何工作的，因为在使用 API 时需要手动启用。

在使用 Claude Code 和 Claude 智能体产品等工具时，你可以直接访问文件系统。
使用 Claude API 时，你没有直接访问权限，我们需要一个容器来执行代码，同时搭配一个文件系统。
在 Claude AI 和 Claude Desktop 中，这种容器化环境和文件系统是直接提供给你的，你不需要自己实现。

当我们开始探索 Messages API 时，我们将使用代码执行工具。代码执行工具允许 Claude 运行 bash 或 shell 命令，完成我们在使用 Skills 时看到的所有操作——在沙箱环境中创建、查看和编辑文件、编写代码。

代码执行工具使我们的应用拥有一个仅供我们自己使用的专属容器，我们可以在其中执行代码和处理文件系统。正如你看到的 Skills 功能，这对于读取 Skills、在 Skills 中执行代码以及处理其他我们可能想编辑、查看和创建的文件至关重要。

实际上，当我们集成代码执行工具时，我们基本上给了 Claude 一个用于执行的沙箱或容器。

当我们要求 Claude 创建和执行文件时，这些操作发生在安全且隔离的环境中。该环境内存、磁盘、CPU 有限，最重要的是没有互联网访问权限，并且有一些开箱即用的库。因此它并不适用于所有类型的编码环境。有一些注意事项和限制。

同时，我们可以访问一个文件系统并开始在其中添加目录。你在使用 Claude Desktop 和 Claude AI 时可能已经看到了一些相关迹象。

代码执行工具与 Claude API 提供的另一组 API 配合得很好。正如我们可以想象的，当处理文件时——添加、创建、写入、修改文件——我们需要某种机制来实际存储底层文件。Claude API 包含一组称为 Files API 的接口，用于上传和下载可以在容器内执行和处理的文件。

可以想象这样一个场景：用户要求总结一些输入内容并将其保存到文本文件中。我们上传输入文件，发送到容器，然后通过 Files API 下载结果文件。

我们很快会在代码中看到这一点。当我们看到上传和下载文件返回的 ID，以及它们如何与我们的 Skills 和代码执行工具完美配合时，我们就会明白 Skills 如何协同工作。

你可以使用的 Skills 仓库——无论是来自 Claude AI 等工具的内置技能组，还是你通过 API 手动添加的——都存储在容器中的一个目录中。

这就是 Skills 发挥作用的地方：当我们开始从这个 Skills 目录中读取内容、向 Skills 中添加信息，并使用这些底层 Skills 来创建我们可以下载或上传的新文件。你还会注意到，在所有 API 和使用中，当你想使用 Skills 时，也需要使用代码执行工具。

现在我们了解了代码执行工具和 Files API 的功能，让我们看看如何实际使用它们。我们将重新审视之前创建的两个自定义 Skills：用于生成练习题的 Skills 和用于分析时间序列的 Skills。

现在进入 Jupyter Notebook 探索。这里有我们之前使用的两个自定义 Skills、一个用于分析时间序列数据的数据文件夹，以及一个在使用生成练习题 Skill 时会用到的讲义笔记文件夹。

看看 Notebook 的第一部分。我们将设置 API 客户端和代码执行工具。配置客户端使用代码执行工具，然后发送关于我们需要什么的消息。

我们首先会先测试一下代码执行工具和 Files API。上传时间序列数据 CSV，确保连接正常。

使用代码执行工具查看在上传 Skill 文件后创建的 skills 目录内部。上传自定义 Skill 并直接在代码执行容器中解压。

将两个 Skills 上传到容器并解压到 skills 目录后，确保一切正常。查看目录内容。

可以看到自定义 Skills 按预期出现在这里：analyzing-time-series 和 generating-practice-questions。

然后上传要使用的数据 CSV。上传后，使用代码执行工具测试时间序列分析 Skill。给 Claude 一个描述我们需求的提示，指定使用这个 Skill。

运行提示时，可以看到 Claude 正在使用这个 Skill 文件，读取其中的指令，然后执行我们指定的工作流。

查看我们给出的提示：要求 Claude 使用 analyzing-time-series Skill 分析时间序列数据，描述数据及其特征，告诉我们是否可预测。

我们看到 Claude 读取 Skill 文件，提取指令，然后开始工作流：第一步，通过 Python 脚本运行诊断，然后总结发现。

然后我们看到结果。可以看到运行的诊断、文本文件、甚至生成的图表图像。Skill 的流程完全按照我们在 SKILL.md 中编写的方式执行。

对于第二个 Skill，生成练习题。上传讲义笔记（这次是 PDF），然后使用 generating-practice-questions Skill。

要求 Claude 使用这个 Skill 基于上传的 PDF 讲义笔记生成练习题，并将结果保存到 LaTeX 和 markdown 文件。

我们看到 Claude 再次读取 Skill 文件，然后发送我们要求的期望输出格式（在提示中指定）。然后按预期生成问题，从讲义笔记中获取学习目标。

对于输出，我们看到它引用了 assets 文件夹，查看模板 markdown 文件以了解如何以 markdown 格式输出问题。对 LaTeX 也做了同样的事情。

然后，它使用 markdown 模板和 LaTeX 模板创建文件，我们可以通过 Files API 从代码执行容器中下载。

完整的代码示例可以在 GitHub 上找到。

在本课中，我们结合了 Messages API、代码执行工具、Files API 和 Skills，最终实现了以编程方式处理自定义 Skills 的能力。在下一课中，我们将转向 Claude Code，在 .claude 文件夹中添加自己的自定义 Skills，并构建更复杂的命令行应用。

7、在 Claude Code 中使用 Skills¶

现在我们将转向 Claude Code，使用 Skills 进行代码生成、审查和测试。我们还将设置子智能体并为它们配备 Skills。

.claude/CLAUDE.md在每次对话开始时加载。它添加 Claude 在每个对话中都需要知道的关于这个项目的上下文。

.claude/skills提供了额外的领域专业知识、可重复的工作流和新能力，这些是逐步加载的，只在需要时加载。

所以任何你希望 Claude 在每个对话中都了解的内容，放在 CLAUDE.md 中。而只在需要时才加载的知识，则使用 Skills。

在这个 skills 文件夹中，我有几个 Skills：一个代码审查 Skill、一个生成测试的 Skill 和一个生成代码的 Skill。

在代码审查 Skill 中，有熟悉的 YAML 前置元数据。名称 code-review，描述指定了做什么以及何时使用。我希望 Claude 在任何需要代码审查的时候使用这个 Skill，提到代码质量、最佳实践、安全性和其他关键词。

在主体中，我指定了希望 Claude 遵循的步骤。审查侧重于安全性、Python 最佳实践、项目约定等。我指定了一些关于审查什么和不审查什么的具体内容。这部分确保了代码审查精确按照我或我的团队希望的方式进行，而不需要我每次都指定规则。

我还有一个生成测试的 Skill。描述了它的功能和何时使用。这里我指定了来自 CLAUDE.md 的一些关于项目约定的相同内容，但这部分只在需要生成测试时加载。对于生成测试，我指定了特定的测试框架和其他设置。

最后一个 Skill 是代码生成 Skill。有描述和何时使用，指定了一些关于生成内容的特定要求。

现在看看这些 Skills 如何与 Claude Code 一起使用。

首先在我的项目目录中启动 Claude Code，要求它使用代码生成 Skill 生成一些代码。

我想让 Claude 使用这个 Skill 给我的待办应用添加一个新功能——允许在特定待办事项上设置提醒。要求 Claude 添加这个功能，使待办事项有一个可选的提醒字段。

在 Claude Code 中运行。Claude 立即根据我们提供的描述识别出 Skill，并按照我们指定的工作流执行。它给出了发现的摘要，并根据 Skill 的标准审查生成的代码。我可以查看生成的代码，看到 Claude 考虑了安全性、边界情况、错误处理等。

当需要代码审查时，我也可以使用那个 Skill。让 Claude 审查现有代码。Claude 读取 Skill 文件并执行审查，遵循我列出的具体标准：安全性、性能、边界情况等。它还会标记潜在问题并推荐改进。

当需要测试时，使用测试生成 Skill。Claude 读取 Skill 并按照我指定的框架和约定生成测试，不需要我每次都重新解释。

这里一个非常强大的概念是将子智能体与 Skills 结合使用。在 Claude Code 中，我可以生成自己的 Skills、自己的隔离上下文并且可以并行执行任务的子智能体。

设置一个用于代码审查的子智能体。该子智能体将使用我们创建的 code-review Skill。当我运行更复杂的任务时，可以让 Claude 生成这个子智能体来审查我的代码，同时主智能体继续处理其他任务。这种隔离意味着子智能体的上下文不会污染主对话。

其工作方式是，在 skills 目录中，有一个 subagents 文件夹。在其中，我使用 markdown 文件定义子智能体，指定它们的角色、Skills 和工具。

例如，我可以有一个只对文件系统有读取权限并使用 code-review Skill 的代码审查子智能体。当 Claude 检测到可能需要代码审查时，就会生成这个子智能体。

在演示中，当我输入/提示一个新功能实现时，Claude 可以生成一个代码审查子智能体来并行审查生成的代码，同时主智能体继续实现功能。子智能体返回发现的结果，主智能体可以据此采取行动。这对于在不减慢开发速度的情况下维护代码质量非常强大。

更广泛地看子智能体在 Claude Code 中的工作方式。当你有需要深度关注特定领域的任务时，子智能体非常完美。它们具有有限的工具权限和隔离的上下文，因此不会消耗你的主上下文窗口。你可以精确指定每个子智能体可以访问哪些 Skills。

假设我有一个大型代码库，想在多个文件中进行代码审查。主智能体不需要读取所有这些文件并消耗上下文，我可以生成一个具有 code-review Skill 的代码审查子智能体。子智能体审查代码，生成摘要，并将其返回给主智能体。主智能体只使用摘要继续工作，节省大量 token。

另一个例子——我可以有一个专门专注于测试、配备测试生成 Skill 的子智能体。当我添加新功能时，这个子智能体可以自动生成相应的测试。

Skills 和子智能体一起允许一个极其强大的工作流：你可以让主智能体编排多个专业工作者，每个都有自己的专业知识，在同一个项目的不同方面并行工作。

在 Claude Code 中，我可以在 .claude/subagents 目录中配置我的子智能体，类似于 Skills 的配置方式。每个子智能体都有自己的系统提示、工具权限和可以加载的 Skills。

总结一下，当你在 Claude Code 中使用 Skills 时： - Skills 提供专业知识、可重复的工作流和新能力 - 子智能体使用自己的 Skills 和工具提供隔离的执行 - 两者结合使用，可以创建强大的并行工作流，维护代码质量和一致性

8、Claude Agent SDK 中的 Skills¶

使用 Claude Agent SDK 创建一个研究智能体。该智能体将使用一个 Skill，基于工具的技术文档、GitHub 仓库和网络搜索，为该开源工具创建学习指南。

我们已经了解了如何在网页端使用 Skills、使用 Messages API 和 Claude Code，现在来谈谈如何在 Claude Agent SDK 中使用 Skills。回顾一下，Claude Agent SDK 是一种以编程方式构建你自己的智能体应用的方法，利用 Claude 的底层智能来构建复杂且非确定性的智能体。

在本课中，我们将构建一个研究智能体。把它想象成一个通用研究智能体，其主要职责是接收任务，使用 Skill 制定计划，然后将任务分派给各自有专长的子智能体。让我们看看架构。

这个智能体的架构类似于指挥官带领专业士兵。我们有主智能体，即指挥官。指挥官可以访问 skill tool，该工具加载一个用于学习工具的 Skill。指挥官使用这个 Skill 制定计划，然后使用 task tool 将工作分派给三个子智能体。

三个子智能体各有专长：Docs Researcher 负责阅读文档；Repo Analyzer 负责克隆仓库和分析代码；Web Researcher 负责查找教程、YouTube 视频和其他外部资源。

主智能体还可以访问 Notion 的 MCP 服务器，因此可以将最终结果写入 Notion 页面。

我们使用的 Skill 叫做"learning-a-tool"。这个 Skill 提供了如何学习新开源工具的计划。Skill 有元数据——名称和描述——并引用了一个包含详细说明的 progressive_learning.md 文件。这就是渐进式披露的实际应用：Skill 描述始终加载，但详细说明只在 Skill 被触发时才加载。

看看项目结构。agent.py 是主入口。agents 目录有定义子智能体的 markdown 文件：docs_researcher.md、repo_analyzer.md 和 web_researcher.md。还有一个 .claude/skills/learning-a-tool 目录，包含 SKILL.md 和 progressive_learning.md 文件。

让我们浏览代码。首先，导入必要的模块并配置工具。SDK 默认是只读且安全的，所以我们需要显式允许某些工具。我们允许写入、bash、网络搜索和网络抓取。这些是使智能体能够完成工作的工具。

接下来，配置 MCP 服务器。我们定义一个 Notion MCP 服务器，让智能体可以将结果写入 Notion 页面。我们使用通配符模式将 MCP 工具名称添加到允许的工具列表中。

然后配置 Skill tool 和 Task tool。Skill tool 从项目的 .claude/skills 目录加载 Skills。Task tool 加载子智能体定义，允许我们向它们分派任务。

允许的工具被组合并传递给主智能体。子智能体有自己更受限的工具集。例如，Repo Analyzer 需要 bash 权限来克隆仓库，但 Docs Researcher 只需要网络搜索和抓取。这遵循最小权限原则——每个智能体只能访问它需要的工具。

当用户给出任务时，比如"为 MinerU 创建学习指南"，主智能体首先使用 Skill 制定计划。Skill 逐步披露——首先只是名称和描述，触发后加载完整的 SKILL.md，当计划引用更深入的指令时，加载 progressive_learning.md。

计划创建后，主智能体并行向三个子智能体分派任务。每个子智能体使用自己的上下文和工具独立工作。Docs Researcher 阅读网页文档。Repo Analyzer 克隆 GitHub 仓库并分析代码结构。Web Researcher 查找教程和视频。

子智能体返回发现的结果，主智能体将所有内容综合成全面的学习指南。它创建一个本地文件结构，包含学习路径和时间预估的 README.md，整理链接的 resources.md，以及带有基本代码示例的 examples 文件夹。

最后，当用户要求将资源写入 Notion 时，主智能体使用 MCP 服务器将内容写入 Notion 页面。它读取本地的 resources.md 文件，自动将其转换为 Notion 的富文本块格式。

这展示了结合 Skills、子智能体、MCP 和 Agent SDK 的全部力量。Skill 提供结构化的流程。子智能体提供并行、专注的研究。MCP 服务器提供外部连接。SDK 以可编程的方式将所有内容整合在一起。

本课的一些重要收获：

Claude Code CLI 和 Claude Agent SDK 有重要区别。Claude Code 是用于辅助编码和一次性任务的交互式工具。SDK 是用于构建可扩展 AI 应用的编程框架，可以对系统提示、工具集和错误处理进行精细控制。
安全性至关重要。在生产环境中，对于 bash 和 write 等高风险工具，需要人工参与的审批流程。SDK 允许你实现权限请求，智能体在执行危险操作前暂停并请求确认。
可移植性是一个关键优势。你在 .claude/skills 目录中创建的 Skills 遵循开放标准。你可以将为 SDK 编写的 Skill 在 Claude Desktop 或其他任何兼容 Skills 的智能体中使用，无需修改。

9、总结¶

在创建 Skill 时，从基础的 markdown 指令开始，然后按照渐进式披露的原则逐步扩展。监控你的智能体在真实场景中如何使用你的 Skill，并根据观察进行迭代。确保描述包含足够的细节，让你的智能体知道何时使用它。

别忘了，Claude 非常了解 Skills 是什么。所以你可以随时从一个简单的对话开始创建 Skills，然后使用 skill-creator 遵循最佳实践。