用 Agent Skills 装备面向真实世界的智能体

Claude 很强大，但真实工作需要流程性知识和组织上下文。介绍 Agent Skills：一种使用文件和文件夹构建专门化智能体的新方式。

来源：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
发布日期：2025-10-16

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

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

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

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

一个 skill 是一个包含 SKILL.md 文件的目录，其中还可以组织指令、脚本和资源文件夹，为智能体提供额外能力。

skill 的构成

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

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

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

SKILL.md 文件必须以 YAML Frontmatter 开头，其中包含名称（name）和描述（description），并会在启动时加载到系统提示词中。

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

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

你可以把更多上下文（通过额外文件）纳入你的 skill，然后 Claude 可以基于系统提示词触发它。

渐进式披露是让 Agent Skills 具备灵活性和可扩展性的核心设计原则。就像一本组织良好的手册，会先给出目录，再给出具体章节，最后提供详细附录一样，skills 让 Claude 只在需要时加载信息：

拥有文件系统和代码执行工具的智能体，在处理某个具体任务时，不需要把整个 skill 都读入上下文窗口。这意味着，可以打包进一个 skill 的上下文量实际上没有上限。

Skills 与上下文窗口

下图展示了当用户消息触发某个 skill 时，上下文窗口会如何变化。

Skills 通过系统提示词在上下文窗口中被触发。

图中展示的操作序列如下：

1. 起始时，上下文窗口中包含核心系统提示词、每个已安装 skill 的元数据，以及用户的初始消息；
2. Claude 通过调用 Bash 工具读取 pdf/SKILL.md 的内容，从而触发 PDF skill；
3. Claude 选择读取与该 skill 一起打包的 forms.md 文件；
4. 最后，Claude 已经从 PDF skill 加载了相关指令，于是继续处理用户任务。

Skills 与代码执行

Skills 也可以包含代码，供 Claude 根据自己的判断作为工具执行。

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

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

Skills 也可以包含代码，让 Claude 根据任务性质自行判断并作为工具执行。

开发和评估 skills

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

• 从评估开始： 通过让智能体处理有代表性的任务，并观察它们在哪些地方吃力或需要额外上下文，识别其能力中的具体缺口。然后逐步构建 skills 来弥补这些短板。
• 按规模组织： 当 SKILL.md 文件变得难以管理时，将其内容拆分到单独文件中并进行引用。如果某些上下文彼此互斥或很少一起使用，将路径分开可以减少 token 使用量。最后，代码既可以充当可执行工具，也可以充当文档。应该明确 Claude 是应直接运行脚本，还是将其读入上下文作为参考。
• 从 Claude 的视角思考： 观察 Claude 在真实场景中如何使用你的 skill，并根据观察结果迭代：留意意料之外的行动路径，或对某些上下文的过度依赖。特别注意 skill 的 name 和 description。Claude 会在决定是否针对当前任务触发该 skill 时使用这些信息。
• 与 Claude 一起迭代： 当你和 Claude 一起处理任务时，让 Claude 把它成功的方法和常见错误沉淀为 skill 中可复用的上下文和代码。如果它在使用某个 skill 完成任务时偏离方向，让它自我反思哪里出了问题。这个过程能帮助你发现 Claude 实际需要什么上下文，而不是试图一开始就预判所有需求。

使用 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 分享他们的上下文和工作流。我们也会探索 Skills 如何补充模型上下文协议（MCP）服务器：通过教授智能体涉及外部工具和软件的更复杂工作流来实现这一点。

再往前看，我们希望让智能体能够自行创建、编辑和评估 Skills，使它们能把自己的行为模式编码成可复用能力。

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

我们很期待看到大家用 Skills 构建出什么。现在就查看我们的 Skills 文档和 cookbook，开始上手。

致谢

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