原文：Equipping agents for the real world with Agent Skills
作者：Barry Zhang、Keith Lazuka、Mahesh Murag / Anthropic
原文发布日期：2025 年 10 月 16 日
本文为全文中文翻译，原文版权归原权利人所有。
更新：我们已将 Agent Skills 发布为开放标准，以实现跨平台可移植性。（2025 年 12 月 18 日）
随着模型能力提升，我们现在能够构建与完整计算环境交互的通用智能体。例如，Claude Code 可以通过本地代码执行和文件系统，完成跨领域的复杂任务。但随着这些智能体越来越强大，我们也需要更易组合、扩展和迁移的方法，为它们配备特定领域的专业知识。
这促使我们创建了 Agent Skills：将指令、脚本和资源有组织地放在文件夹中，智能体可以动态发现并加载它们，从而更好地完成特定任务。Skills 将你的专业知识打包成 Claude 可以组合使用的资源，扩展 Claude 的能力，把通用智能体转变为符合你需求的专用智能体。
为智能体构建一项技能，就像为新员工准备入职指南。现在，任何人都可以通过记录和分享自己的流程性知识，以可组合的能力定制智能体，而不必为每种使用场景构建零散的、专门设计的智能体。本文将解释 Skills 是什么，展示其工作原理，并分享构建自定义技能的最佳实践。
技能是一个包含 SKILL.md 文件的目录，其中有组织地存放指令、脚本和资源，为智能体提供额外能力。
技能的组成
为了看看 Skills 如何发挥作用，我们来看一个真实示例：支持 Claude 最近推出的文档编辑能力的其中一项技能。Claude 已经掌握了许多理解 PDF 的知识，但直接操作 PDF 的能力仍然有限，例如填写表单。这项 PDF 技能让我们能够为 Claude 提供这些新能力。
最简单的技能，是一个包含 SKILL.md 文件的目录。这个文件必须以 YAML frontmatter 开头，其中包含必需的元数据：name 和 description。启动时，智能体会将所有已安装技能的 name 和 description 预先加载到系统提示词中。
这些元数据是渐进式披露的第一层：只提供足够的信息，让 Claude 知道何时应该使用每项技能，而不必将整个技能加载到上下文中。文件的实际正文则是第二层详细信息。如果 Claude 认为某项技能与当前任务相关，就会通过读取完整的 SKILL.md，将其加载到上下文中。
SKILL.md 文件必须以包含名称和描述的 YAML frontmatter 开头，这些内容会在启动时加载到系统提示词中。
随着技能变得复杂，它们可能包含太多上下文，无法全部放进一个 SKILL.md，也可能包含只在特定场景下才相关的上下文。在这种情况下，技能可以在目录中附带额外文件，并在 SKILL.md 中按名称引用它们。这些额外链接的文件，就是第三层以及更深层的详细信息，Claude 可以只在需要时选择浏览和探索。
在下图的 PDF 技能中，SKILL.md 引用了两个额外文件（reference.md 和 forms.md），技能作者将它们与核心 SKILL.md 一起打包。通过将表单填写指令移到单独的文件（forms.md），作者能够保持技能核心内容精简，并相信 Claude 只会在填写表单时读取 forms.md。
你可以通过额外文件为技能加入更多上下文，随后由 Claude 根据系统提示词按需触发。
渐进式披露是让 Agent Skills 灵活且可扩展的核心设计原则。就像一份组织良好的手册，先给出目录，再提供具体章节，最后附上详细附录，技能让 Claude 只在需要时加载信息：
这张图展示了 Skills 中上下文的渐进式披露。
拥有文件系统和代码执行工具的智能体，在处理某项任务时，不必将整项技能全部读入上下文窗口。这意味着，技能能够附带的上下文数量实际上不受这一窗口大小限制。
技能与上下文窗口
下图展示了用户消息触发技能后，上下文窗口如何变化。
技能通过系统提示词在上下文窗口中被触发。
图示的操作顺序如下：
- 最初，上下文窗口包含核心系统提示词、每项已安装技能的元数据，以及用户的初始消息；
- Claude 调用 Bash 工具读取
pdf/SKILL.md，触发 PDF 技能； - Claude 选择读取技能附带的
forms.md文件； - 最后，Claude 已从 PDF 技能中加载相关指令，继续执行用户任务。
技能与代码执行
技能也可以包含代码，由 Claude 自行决定是否作为工具执行。
大语言模型擅长许多任务，但有些操作更适合传统代码执行。例如，通过生成 token 对列表排序，远比直接运行排序算法昂贵。除了效率问题，许多应用还需要只有代码才能提供的确定性可靠性。
在我们的示例中，PDF 技能包含一个预先写好的 Python 脚本，用于读取 PDF 并提取所有表单字段。Claude 可以运行这个脚本，而不必将脚本或 PDF 加载到上下文中。由于代码具有确定性，这一工作流是一致且可重复的。
技能也可以包含代码，由 Claude 根据任务性质自行决定是否作为工具执行。
开发与评估技能
以下指导有助于开始编写和测试技能：
- 从评估开始： 让智能体运行具有代表性的任务，观察它在哪些地方遇到困难或需要额外上下文，从而识别具体的能力缺口。随后逐步构建技能，解决这些不足。
- 为扩展组织结构： 当
SKILL.md变得难以管理时，将内容拆分到独立文件中并引用它们。如果某些上下文互斥，或很少一起使用，保持路径分离可以减少 token 消耗。最后，代码既可以是可执行工具，也可以是文档。应明确说明 Claude 是应该直接运行脚本，还是将其读入上下文作为参考。 - 从 Claude 的角度思考： 观察 Claude 在真实场景中如何使用技能，并根据观察结果迭代：留意意料之外的执行路线，或对某些上下文的过度依赖。特别关注技能的
name和description。Claude 会依据这些信息，决定是否应为当前任务触发技能。 - 与 Claude 一起迭代： 在与 Claude 合作完成任务时，请它将成功方法和常见错误整理为技能中可复用的上下文和代码。如果它使用技能完成任务时偏离方向，请它反思哪里出了问题。这个过程有助于发现 Claude 真正需要哪些上下文，而不是试图提前猜测。
使用 Skills 时的安全注意事项
技能通过指令和代码为 Claude 提供新能力。这让它们功能强大，但也意味着恶意技能可能在使用环境中引入漏洞，或引导 Claude 外传数据、执行非预期操作。
我们建议只安装来自可信来源的技能。从可信度较低的来源安装技能时，应在使用前全面审计。先阅读技能附带文件的内容，了解它做什么，尤其关注代码依赖，以及图像、脚本等附带资源。同样，要留意技能中要求 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 的同事。