Equipping agents for the real world with Agent Skills

更新：我们已将 Agent Skills 作为开放标准发布，以实现跨平台可移植性。（2025 年 12 月 18 日）

随着模型能力的提升，我们现在可以构建与功能完备的计算环境交互的通用智能体。例如，Claude Code 可以利用本地代码执行和文件系统跨领域完成复杂任务。但随着这些智能体变得更加强大，我们需要更可组合、更可扩展、更可移植的方式，为它们配备特定领域的专业知识。

这促使我们创建了 Agent Skills：这是由指令、脚本和资源组成的有组织的文件夹，智能体可以动态地发现并加载它们，从而在特定任务上表现得更好。 Skills 将你的专业知识打包成可供 Claude 使用的可组合资源，以此扩展 Claude 的能力，将通用智能体转变为符合你需求的专业智能体。

为智能体构建一个 skill 就像为新员工准备一份入职指南。任何人现在都可以通过捕获和分享自己的程序性知识，用可组合的能力来专业化自己的智能体，而不必为每个用例构建零散的定制智能体。在本文中，我们将解释 Skills 是什么，展示它们如何工作，并分享构建自己的 Skills 的最佳实践。

skill 的结构

为了看看 Skills 的实际效果，让我们来看一个真实的例子：为 Claude 最近推出的文档编辑能力提供支持的技能之一。Claude 已经对理解 PDF 有很多了解，但它直接操作 PDF 的能力有限（例如填写表单）。这个 PDF skill 让我们能够赋予 Claude 这些新能力。

最简单地说，skill 是一个包含 SKILL.md file 的目录。该文件必须以 YAML frontmatter 开头，其中包含一些必需的元数据：name 和 description。启动时，智能体会将每个已安装 skill 的 name 和 description 预加载到其系统提示词中。

这些元数据是渐进式披露的第一层：它提供的信息刚好足够让 Claude 知道何时应该使用每个 skill，而无需将全部内容加载到上下文中。该文件的实际正文是第二层细节。如果 Claude 认为该 skill 与当前任务相关，就会将其完整的 SKILL.md 读入上下文来加载该 skill。

随着 skill 复杂度的增加，它们可能包含太多无法放进单个 SKILL.md 的上下文，或者包含仅在特定场景下才相关的上下文。在这些情况下，skill 可以在 skill 目录中打包额外的文件，并在 SKILL.md 中按名称引用它们。这些额外的关联文件是第三层（及更深层）的细节，Claude 可以选择仅在需要时才浏览和发现它们。

在下图所示的 PDF skill 中，SKILL.md 引用了两个额外的文件（reference.md 和 forms.md），它们是 skill 作者选择与核心 SKILL.md 捆绑在一起的。通过将表单填写指令移到单独的文件（forms.md）中，skill 作者能够让 skill 的核心保持精简，并相信 Claude 只会在填写表单时才读取 forms.md。

渐进式披露是让 Agent Skills 灵活且可扩展的核心设计原则。就像一本组织良好的手册，从目录开始，然后是具体章节，最后是详细的附录，技能让 Claude 只在需要时才加载信息：

拥有文件系统和代码执行工具的智能体在处理特定任务时，无需将技能的全部内容读入其上下文窗口。这意味着可以打包进技能的上下文数量实际上不受限制。

技能与上下文窗口

下图展示了当技能被用户消息触发时，上下文窗口的变化情况。

图中所示的操作顺序：

1. 首先，上下文窗口包含核心系统提示和每个已安装技能的元数据，以及用户的初始消息；
2. Claude 通过调用 Bash 工具读取 pdf/SKILL.md 的内容来触发 PDF 技能；
3. Claude 选择读取随技能打包的 forms.md 文件；
4. 最后，Claude 在从 PDF 技能加载了相关指令后，继续处理用户的任务。

技能与代码执行

技能还可以包含代码，供 Claude 自行决定将其作为工具执行。

大型语言模型擅长许多任务，但某些操作更适合传统的代码执行。例如，通过生成 token 来排序列表比直接运行排序算法成本高得多。除了效率问题之外，许多应用程序还需要只有代码才能提供的确定性可靠性。

在我们的示例中，PDF 技能包含一个预编写的 Python 脚本，用于读取 PDF 并提取所有表单字段。Claude 可以运行这个脚本，而无需将脚本或 PDF 加载到上下文中。而且由于代码是确定性的，这一工作流是一致且可重复的。

开发和评估技能

以下是一些有助于开始编写和测试技能的实用指南：

• 从评估开始：通过让智能体在代表性任务上运行，并观察它们在哪些方面遇到困难或需要额外上下文，来识别其能力中的具体差距。然后逐步构建技能来弥补这些不足。
• 为扩展性而设计结构：当 SKILL.md 文件变得过于庞大时，将其内容拆分为单独的文件并进行引用。如果某些上下文相互排斥或很少一起使用，将路径分开可以减少 token 的使用。最后，代码既可以作为可执行工具，也可以作为文档。应当明确 Claude 是应该直接运行脚本，还是将其读入上下文作为参考。
• 从 Claude 的角度思考：监控 Claude 在实际场景中如何使用你的技能，并根据观察结果进行迭代：留意意外的执行路径或对某些上下文的过度依赖。特别要关注技能的 name 和 description。Claude 在决定是否针对当前任务触发该技能时会使用这些信息。
• 与 Claude 一起迭代：在与 Claude 合作完成任务的过程中，可以让 Claude 将其成功的方法和常见错误捕捉沉淀为 skill 中可复用的上下文和代码。如果它在使用某个 skill 完成任务时偏离了方向，可以让它自我反思问题出在哪里。这一过程将帮助你发现 Claude 实际需要哪些上下文，而不是试图提前预测。

使用 Skills 时的安全注意事项

Skills 通过指令和代码为 Claude 提供新能力。虽然这使其功能强大，但也意味着恶意 skill 可能会在其使用环境中引入漏洞，或指示 Claude 窃取数据并执行非预期的操作。

我们建议仅从受信任的来源安装 skill。从可信度较低的来源安装 skill 时，请在使用前对其进行彻底审计。首先阅读 skill 中打包文件的内容以了解其功能，特别要留意代码依赖项以及图像或脚本等打包资源。同样，也要注意 skill 中指示 Claude 连接到潜在不可信外部网络源的指令或代码。

Skills 的未来

Agent Skills 目前已在 Claude.ai、Claude Code、Claude Agent SDK 和 Claude Developer Platform 上获得支持。

在接下来的几周里，我们将继续添加支持 Skills 创建、编辑、发现、共享和使用全生命周期的功能。我们尤其期待 Skills 能够帮助组织和个人与 Claude 分享他们的上下文和工作流程。我们还将探索 Skills 如何通过向智能体传授涉及外部工具和软件的更复杂工作流程，来补充Model Context Protocol（MCP）服务器。

展望更远的未来，我们希望让智能体能够自主创建、编辑和评估 Skills，使它们能够将自身的行为模式固化为可复用的能力。

Skills 是一个简单的概念，其格式也相应简单。这种简洁性使组织、开发者和最终用户更容易构建定制化的智能体并赋予它们新能力。

我们很期待看到人们用 Skills 构建出什么。欢迎今天就查阅我们的 Skills 文档和 cookbook，立即上手。

致谢

本文由 Barry Zhang、Keith Lazuka 和 Mahesh Murag 撰写，他们都非常喜欢文件夹。特别感谢 Anthropic 内众多倡导、支持和构建 Skills 的同事。