用 Agent Skills 武装真实世界的代理¶
- 原文链接：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills [63]
- 发布时间：2025-10-16
- 作者：Barry Zhang、Keith Lazuka、Mahesh Murag
Claude 很强，但真正的工作需要流程知识与组织上下文；Agent Skills 提供了可组合、可移植的能力封装。[63]
更新（2025-12-18）： 我们已将 Agent Skills 作为跨平台开放标准发布。[63]
随着模型能力提升，我们可以构建能够与完整计算环境交互的通用代理。例如 Claude Code 可利用本地代码执行与文件系统跨领域完成复杂任务。但代理越强，就越需要可组合、可规模化、可移植的方法来注入领域知识。[63]
这促使我们创建 Agent Skills：由指令、脚本与资源组成的文件夹结构，代理可动态发现并加载，用于提升特定任务能力。Skills 把你的专业知识打包成可组合资源，让通用代理变成贴合需求的专用代理。[63]
构建一个 skill 就像给新员工做 onboarding：与其为每个场景制作碎片化的定制代理，不如把流程知识沉淀成可复用的技能。本文介绍 Skills 的概念、工作方式与最佳实践。[63]
图注：Skill 是包含 SKILL.md 的目录，内部组织了指令、脚本与资源，用于赋予代理额外能力。[63]
Skill 的解剖结构¶
让我们通过一个真实例子理解 Skills：它为 Claude 最近上线的文档编辑能力 提供支持。Claude 已能理解 PDF，但无法直接操作（例如填表）。该 PDF skill 赋予了这些能力。[63]
最简单的 skill 是一个目录，包含一个 SKILL.md 文件。这个文件必须以 YAML frontmatter 开头，包含必需元数据：name 与 description。启动时，代理会把每个已安装 skill 的 name 和 description 预加载到系统提示中。[63]
这就是渐进式披露（progressive disclosure）的第一层：提供足够信息让 Claude 判断是否需要该 skill，但不加载全部内容。SKILL.md 正文是第二层：当 Claude 判断相关时，会把整个 SKILL.md 读入上下文。[63]
图注：SKILL.md 必须以 YAML Frontmatter 开头，包含名称与描述，这些信息在启动时会被加载到系统提示中。[63]
随着技能变复杂，单个 SKILL.md 可能过长，或仅在特定场景相关。这时可以把额外文件放在 skill 目录中，并从 SKILL.md 引用。这样形成第三层（及更高层）信息，Claude 只在需要时读取。[63]
例如 PDF skill 中，SKILL.md 引用了 reference.md 和 forms.md。作者把表单填充说明移到 forms.md，让核心 SKILL.md 保持精简，信任 Claude 只在填表时加载。[63]
图注：通过额外文件扩展上下文，Claude 会基于系统提示按需加载。[63]
渐进式披露是 Agent Skills 的核心设计原则，使其灵活可扩展：像目录表 → 章节 → 附录，Claude 只在需要时加载。[63]
具备文件系统与代码执行工具的代理无需把技能全量读入上下文，这意味着 skill 中能容纳的上下文几乎无限。[63]
Skills 与上下文窗口¶
下图展示当用户触发 skill 时上下文的变化。[63]
图注：技能通过系统提示触发并逐层加载进上下文。[63]
流程如下：[63]
- 起始时，上下文包含核心系统提示、已安装技能的元数据和用户消息；
- Claude 触发 PDF skill，调用 Bash 读取
pdf/SKILL.md； - Claude 选择读取 skill 中的
forms.md； - 加载相关指令后继续完成用户任务。
Skills 与代码执行¶
Skills 还可以包含代码，供 Claude 作为工具按需执行。[63]
LLM 擅长许多任务，但某些操作更适合传统代码：比如排序列表，用 token 生成远不如直接运行排序算法高效。更重要的是许多场景需要确定性的可靠性。[63]
在 PDF skill 示例中，Skill 包含一个预写 Python 脚本用于读取 PDF 并提取表单字段。Claude 可以在不把脚本或 PDF 加载进上下文的情况下运行该脚本。由于代码是确定性的，流程可重复、结果稳定。[63]
图注：Skills 也可包含可执行代码，Claude 会按需作为工具执行。[63]
开发与评估 Skills¶
以下是编写与测试 Skills 的建议：[63]
- 从评估开始：先用代表性任务测试代理，观察它在哪些地方卡住或缺乏上下文，再逐步构建技能补齐短板。
- 为规模化组织结构：当
SKILL.md变得冗长，拆分为独立文件并引用。若某些上下文互斥或很少同时使用，分离路径可减少 token 消耗。代码既可作为可执行工具，也可作为文档；需要明确 Claude 应该运行脚本还是阅读脚本。 - 从 Claude 的视角思考：监控 Claude 在实际场景中如何使用技能并迭代，留意异常路径或对特定上下文的过度依赖。尤其要关注 skill 的
name与description，Claude 用它们判断是否触发技能。 - 与 Claude 一起迭代：当 Claude 成功完成任务时，让它把成功方法与常见错误沉淀成可复用上下文与代码。如果 Claude 在使用某 skill 时偏离目标，让它自我反思问题所在，帮助你发现真正需要的上下文。
使用 Skills 的安全考虑¶
Skills 通过指令与代码扩展能力，但也可能引入安全风险：恶意技能可能植入漏洞、引导数据外泄或执行非预期操作。[63]
我们建议只安装可信来源的技能；对于不太可信的来源，要充分审计。先阅读 skill 目录中的所有文件，理解其用途，特别关注代码依赖与附带资源（图片/脚本）。还要警惕 skill 中指向不可信外部网络的指令或代码。[63]
Skills 的未来¶
Agent Skills 已在 Claude.ai、Claude Code、Claude Agent SDK 与 Claude Developer Platform 中得到支持。[63]
接下来几周，我们将继续增强 Skills 的全生命周期功能：创建、编辑、发现、共享与使用。我们尤其期待 Skills 帮助组织与个人把上下文与工作流共享给 Claude，同时也会探索 Skills 与 MCP 的互补方式（例如教会代理更复杂的跨工具工作流）。[63]
更远期，我们希望代理能自己创建、编辑、评估 Skills，把自己的行为模式固化为可复用能力。[63]
Skills 是一个简单概念，对应的是简单格式，因此组织、开发者与最终用户都能轻松构建定制代理能力。[63]
欢迎查看我们的 Skills 文档 与 cookbook 开始实践。[63]
致谢¶
本文由 Barry Zhang、Keith Lazuka 与 Mahesh Murag 撰写，他们都很喜欢文件夹。感谢 Anthropic 内部众多支持与构建 Skills 的同事。[63]
图注：原文未提供图注。[63]