用 Agent Skills 让 agents 胜任真实世界任务
原文: English original · Anthropic/OpenAI 官方
用 Agent Skills 让 agents 胜任真实世界任务
发布于 2025 年 10 月 16 日
Claude 很强大，但真实工作需要流程性知识和组织上下文。本文介绍 Agent Skills：一种用文件和文件夹构建专用 agents 的新方式。
更新：我们已将 Agent Skills 发布为跨平台可移植的开放标准。（2025 年 12 月 18 日）
随着模型能力提升，我们现在可以构建通用 agents，让它们与功能完整的计算环境交互。例如，Claude Code 可以借助本地代码执行和文件系统，完成跨领域的复杂任务。但随着这些 agents 越来越强，我们也需要更可组合、更可扩展、更可移植的方式，为它们配备特定领域的专业能力。
这促使我们创建了 Agent Skills：由指令、脚本和资源组成的有组织文件夹，agents 可以动态发现并加载它们，从而在特定任务上表现得更好。Skills 会把你的专业知识打包成 Claude 可组合使用的资源，扩展 Claude 的能力，将通用 agents 转变为符合你需求的专用 agents。
为 agent 构建一个 skill，就像为新员工整理一份入职指南。过去需要为每个用例构建零散、定制的 agents；现在，任何人都可以捕捉并分享自己的流程性知识，用可组合能力让自己的 agents 具备专门能力。本文将解释 Skills 是什么，展示它们如何工作，并分享构建你自己的 Skills 时的最佳实践。
skill 是一个目录，里面包含 SKILL.md 文件，并通过有组织的指令、脚本和资源，为 agents 提供额外能力。
skill 的构成
为了看看 Skills 在实践中的样子，我们来看一个真实例子：支撑 Claude 最近推出的文档编辑能力的 skills 之一。Claude 已经很擅长理解 PDF，但直接操作 PDF 的能力仍然有限，例如填写表单。这个 PDF skill 让我们能够赋予 Claude 这些新能力。
最简单的 skill，就是一个包含 SKILL.md 文件的目录。这个文件必须以 YAML frontmatter 开头，其中包含一些必需元数据：name 和 description。启动时，agent 会把每个已安装 skill 的 name 和 description 预加载到它的 system prompt 中。
这份元数据是渐进式披露的第一层：它只提供足够的信息，让 Claude 知道每个 skill 什么时候应该被使用，而不必把整个 skill 都加载进上下文。这个文件的正文则是第二层细节。如果 Claude 认为某个 skill 与当前任务相关，就会读取完整的 SKILL.md，把这个 skill 加载进上下文。
SKILL.md 文件必须以 YAML frontmatter 开头，包含 name 和 description，并会在启动时加载进 system prompt。
随着 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 根据 system prompt 触发。
渐进式披露是让 Agent Skills 具备灵活性和扩展性的核心设计原则。就像一本组织良好的手册，先给出目录，再进入具体章节，最后附上详细附录；skills 让 Claude 只在需要时加载信息：
拥有文件系统和代码执行工具的 agents，在处理某个具体任务时，并不需要把一个 skill 的全部内容都读进上下文窗口。这意味着，一个 skill 可以打包的上下文数量实际上不受限制。
Skills 与上下文窗口
下图展示了当用户消息触发某个 skill 时，上下文窗口如何变化。
Skills 通过 system prompt 在上下文窗口中被触发。
图中展示的操作序列如下：
- 一开始，上下文窗口包含核心 system prompt、每个已安装 skill 的元数据，以及用户的初始消息；
- Claude 通过调用 Bash 工具读取
pdf/SKILL.md的内容，从而触发 PDF skill； - Claude 选择读取与该 skill 一起打包的
forms.md文件； - 最后，在从 PDF skill 加载了相关指令后，Claude 继续处理用户任务。
Skills 与代码执行
Skills 也可以包含代码，供 Claude 根据自己的判断作为工具执行。
大型语言模型擅长许多任务，但某些操作更适合传统代码执行。例如，通过 token 生成来给列表排序，成本远高于直接运行排序算法。除了效率方面的考虑，许多应用还需要只有代码才能提供的确定性可靠性。
在我们的例子中，PDF skill 包含一个预先编写的 Python 脚本，用于读取 PDF 并提取所有表单字段。Claude 可以运行这个脚本，而不需要把脚本或 PDF 加载进上下文。并且因为代码是确定性的，这个 workflow 是一致且可重复的。
Skills 还可以包含代码，供 Claude 根据任务性质自行判断是否作为工具执行。
开发与评测 skills
下面是一些有助于开始编写和测试 skills 的指南：
- 从评测开始：通过在有代表性的任务上运行 agents，并观察它们在哪里表现吃力或需要额外上下文，识别 agents 能力中的具体缺口。然后逐步构建 skills 来弥补这些不足。
- 面向扩展来组织结构：当
SKILL.md文件变得难以维护时，把它的内容拆分到单独文件中，并在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 分享自己的上下文和 workflows。我们还会探索 Skills 如何补充 Model Context Protocol（MCP）servers：通过教给 agents 涉及外部工具和软件的更复杂 workflows。
再往后看，我们希望让 agents 能够自行创建、编辑和评测 Skills，把自己的行为模式编码成可复用能力。
Skills 是一个简单概念，也采用相应简单的格式。这种简单性让组织、开发者和最终用户更容易构建定制化 agents，并赋予它们新能力。
我们很期待看到大家会用 Skills 构建出什么。从我们的 Skills docs 和 cookbook 开始上手吧。
致谢
作者为 Barry Zhang、Keith Lazuka 和 Mahesh Murag，他们都真的很喜欢文件夹。特别感谢 Anthropic 内部许多倡导、支持并构建 Skills 的同事。