用 Agent Skills 让 agent 适应真实世界

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

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

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

为 agent 构建 skill，就像为新员工整理一份入职指南。现在，不必再为每个用例构建碎片化的定制 agent，任何人都可以通过捕获并共享自己的流程性知识，用可组合的能力来专门化自己的 agent。本文将解释什么是 Skills，展示它们如何工作，并分享构建你自己的 Skills 的最佳实践。

skill 是一个目录，其中包含一个 SKILL.md 文件；该目录包含由指令、脚本和资源组成的有组织文件夹，为 agent 提供额外能力。

skill 的结构

为了了解 Skills 的实际运作方式，我们来看一个真实例子：支撑 Claude 最近发布的文档编辑能力的其中一个 skill。Claude 已经非常擅长理解 PDF，但直接操作 PDF 的能力有限（例如填写表单）。这个 PDF skill 让我们能够赋予 Claude 这些新能力。

最简单的 skill 是一个包含 SKILL.md file 的目录。该文件必须以 YAML frontmatter 开头，其中包含一些必需元数据：name 和 description。启动时，agent 会把每个已安装 skill 的 name 和 description 预加载到其 system prompt 中。

这些元数据是 progressive disclosure（渐进式披露）的第一层：它提供了刚好足够的信息，让 Claude 知道何时应使用每个 skill，而无需把整个 skill 都加载进 context。该文件的正文则是第二层细节。如果 Claude 认为该 skill 与当前任务相关，就会通过读取完整的 SKILL.md，把该 skill 加载进 context。

SKILL.md 文件必须以 YAML Frontmatter 开头，其中包含文件名和描述；这些内容会在启动时加载到其 system prompt 中。

随着 skills 变得更复杂，它们可能包含过多 context，无法放入单个 SKILL.md，或者包含只在特定场景中相关的 context。在这些情况下，skills 可以在 skill 目录中打包额外文件，并从 SKILL.md 中按名称引用它们。这些额外链接的文件是细节的第三层（以及后续层级），Claude 可以只在需要时选择导航和发现它们。

在下方展示的 PDF skill 中，SKILL.md 引用了两个额外文件（reference.md 和 forms.md），skill 作者选择把它们与核心 SKILL.md 一起打包。通过把表单填写指令移到单独文件（forms.md）中，skill 作者可以保持 skill 核心部分精简，并相信 Claude 只会在填写表单时读取 forms.md。

你可以把更多 context（通过额外文件）纳入你的 skill，随后 Claude 可以基于 system prompt 触发这些内容。

Progressive disclosure 是让 Agent Skills 具备灵活性和可扩展性的核心设计原则。就像一本组织良好的手册，从目录开始，再到具体章节，最后是详细附录，skills 让 Claude 只在需要时加载信息：

拥有文件系统和代码执行工具的 agent，在处理特定任务时不需要把整个 skill 读入其 context window。这意味着可以打包进 skill 的 context 数量实际上没有上限。

Skills 与 context window

下图展示了当用户消息触发某个 skill 时，context window 如何变化。

Skills 通过你的 system prompt 在 context window 中被触发。

图中展示的操作顺序：

1. 一开始，context window 包含核心 system prompt、每个已安装 skill 的元数据，以及用户的初始消息；
2. Claude 通过调用 Bash tool 读取 pdf/SKILL.md 的内容，从而触发 PDF skill；
3. Claude 选择读取与该 skill 打包在一起的 forms.md 文件；
4. 最后，Claude 已从 PDF skill 加载相关指令，于是继续处理用户的任务。

Skills 与代码执行

Skills 还可以包含代码，供 Claude 作为 tools 酌情执行。

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

在我们的例子中，PDF skill 包含一个预先编写的 Python 脚本，用于读取 PDF 并提取所有表单字段。Claude 可以运行这个脚本，而无需把脚本或 PDF 加载进 context。并且由于代码是确定性的，这个 workflow 是一致且可重复的。

Skills 还可以包含代码，Claude 可以根据任务性质将其作为 tools 酌情执行。

开发和评估 skills

以下是一些有助于开始编写和测试 skills 的指南：

• 从 evaluation 开始： 通过让你的 agent 执行代表性任务，并观察它们在哪些地方遇到困难或需要额外 context，识别其能力中的具体缺口。然后逐步构建 skills 来弥补这些不足。
• **面向规模设计结构：**当 SKILL.md 文件变得难以维护时，把其内容拆分为单独文件并引用它们。如果某些 context 互斥，或很少一起使用，保持路径分离会减少 token 使用量。最后，代码既可以作为可执行 tools，也可以作为文档。应明确 Claude 是应该直接运行脚本，还是把它们读入 context 作为参考。
• 从 Claude 的视角思考： 监控 Claude 在真实场景中如何使用你的 skill，并根据观察进行迭代：留意意外的执行路径，或对某些 context 的过度依赖。特别关注你的 skill 的 name 和 description。Claude 会在判断是否应响应当前任务触发该 skill 时使用它们。
• 与 Claude 一起迭代： 当你与 Claude 一起处理任务时，请 Claude 把成功做法和常见错误捕获到 skill 中的可复用 context 和代码里。如果它在使用 skill 完成任务时偏离方向，请它自我反思哪里出了问题。这个过程将帮助你发现 Claude 实际需要什么 context，而不是试图提前预判。

使用 Skills 时的安全考虑

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

我们建议只安装来自可信来源的 skills。当从可信度较低的来源安装 skill 时，请在使用前彻底审计。首先阅读该 skill 打包的文件内容，了解它的作用，并特别注意代码依赖以及图像或脚本等打包资源。同样，也要注意 skill 中指示 Claude 连接到潜在不可信外部网络来源的指令或代码。

Skills 的未来

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

未来几周，我们将继续添加功能，支持创建、编辑、发现、共享和使用 Skills 的完整生命周期。我们尤其期待 Skills 能帮助组织和个人与 Claude 共享他们的 context 和 workflows。我们也将探索 Skills 如何补充 Model Context Protocol（MCP）servers，通过教授 agent 涉及外部 tools 和软件的更复杂 workflows 来发挥作用。

展望更远的未来，我们希望让 agent 能够自行创建、编辑和评估 Skills，使它们能够把自己的行为模式编码为可复用能力。

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

我们期待看到人们用 Skills 构建什么。你可以从查看我们的 Skills 文档和 cookbook 开始。

致谢

作者：Barry Zhang、Keith Lazuka 和 Mahesh Murag，他们都非常喜欢文件夹。特别感谢 Anthropic 内部许多倡导、支持并构建 Skills 的同事。