用 Agent Skills 为现实世界中的 Agent 配备能力

随着模型能力不断提升，我们现在已经能够构建通用型 Agent，让它们与完整的计算环境进行交互。

例如，Claude Code 可以利用本地代码执行和文件系统，完成跨多个领域的复杂任务。

但随着这些 Agent 变得越来越强，我们也需要更加可组合、可扩展、可移植的方式，为它们提供特定领域的专业知识。

这促使我们创建了 Agent Skills：一种由指令、脚本和资源组成的结构化文件夹，Agent 可以动态发现并按需加载这些内容，从而在特定任务上表现得更好。

Skills 会把你的专业知识封装成可组合资源，以此扩展 Claude 的能力，让一个通用 Agent 转变成符合你实际需求的专业 Agent。

为 Agent 构建一个 Skill，就像为新员工准备一份入职指南。

与其针对每一个使用场景分别构建彼此割裂、专门定制的 Agent，现在任何人都可以把自己的流程知识记录并分享出来，然后通过这些可组合能力对 Agent 进行专业化定制。

本文将解释：

• Skill 是什么；

• Skill 如何工作；

• 如何构建自己的 Skill；

• 构建 Skill 时有哪些最佳实践。

一个 Skill 本质上是一个目录，其中包含 SKILL.md 文件，以及用于为 Agent 提供额外能力的结构化指令、脚本和资源。

Skill 的结构

为了理解 Skill 实际是如何工作的，我们来看一个真实例子：

Claude 最近推出的文档编辑能力，其中一部分就是通过 Skill 实现的。

Claude 原本已经非常擅长理解 PDF，但它直接操作 PDF 的能力比较有限，比如填写表单。

PDF Skill 可以让我们为 Claude 增加这些新能力。

最简单的情况下，一个 Skill 就是一个包含 SKILL.md 文件的目录。

这个文件必须以 YAML Frontmatter 开头，其中需要包含一些必填元数据：

• name

• description

Agent 启动时，会把所有已安装 Skill 的 name 和 description 预先加载到系统提示词中。

这就是**渐进式披露（progressive disclosure）**的第一层。

它只向 Claude 提供足够的信息，让 Claude 判断什么时候应该使用某个 Skill，而不需要一开始就把 Skill 的所有内容加载进上下文。

SKILL.md 文件的正文则构成第二层信息。

如果 Claude 判断当前任务与某个 Skill 有关，它就会读取完整的 SKILL.md，把 Skill 加载到上下文中。

SKILL.md 文件必须以 YAML Frontmatter 开头，其中包含 Skill 名称和描述。Agent 启动时，这些信息会被加载到系统提示词中。

随着 Skill 变得越来越复杂，单个 SKILL.md 可能会装不下全部上下文。

另外，有些内容可能只在特定场景下才有用，不应该每次都加载。

在这种情况下，Skill 可以把更多文件一起放进 Skill 目录，并在 SKILL.md 中通过文件名引用它们。

这些额外文件构成第三层，以及更深层的信息。

Claude 可以根据任务需要，自主决定是否继续阅读并探索这些文件。

例如，在下面的 PDF Skill 中，SKILL.md 会引用另外两个文件：

• reference.md

• forms.md

Skill 作者可以把这些文件和核心 SKILL.md 一起打包。

通过把“填写表单”的具体指令单独放进 forms.md，Skill 作者就能够让核心 SKILL.md 保持精简。

只有当 Claude 真正需要填写表单时，它才需要读取 forms.md。

Skill 可以加入额外文件以承载更多上下文，而 Claude 会根据系统提示词和当前任务决定什么时候读取这些内容。

渐进式披露，是 Agent Skills 灵活性和可扩展性的核心设计原则。

你可以把它理解成一本组织良好的手册：

先有目录；

然后是具体章节；

最后是详细附录。

Skill 也采用类似方式，让 Claude 只在需要时加载对应信息。

对于具备文件系统和代码执行工具的 Agent 来说，在执行某个具体任务时，它不需要把整个 Skill 全部读入上下文窗口。

因此，一个 Skill 理论上能够打包的上下文总量，实际上可以非常大，甚至近似不受限制。

Skills 与上下文窗口

下面这个过程展示了，当用户消息触发某个 Skill 时，上下文窗口会如何变化。

Skill 通过系统提示词中的元数据进入上下文，并在需要时逐步加载更多内容。

整体流程如下：

1. 一开始，上下文窗口中包含：

   • 核心系统提示词；

   • 每个已安装 Skill 的元数据；

   • 用户最初的消息。

2. Claude 判断 PDF Skill 与当前任务相关，于是调用 Bash 工具读取：

   pdf/SKILL.md

3. Claude 接着决定读取 Skill 中包含的：

   forms.md

4. 当 Claude 已经加载了 PDF Skill 中与当前任务相关的指令后，它才继续执行用户任务。

Skills 与代码执行

Skill 还可以包含 Claude 能够自行决定是否执行的代码。

大型语言模型非常擅长处理许多任务，但某些操作依然更适合传统代码执行。

例如，如果要对一个列表排序，通过逐 Token 生成排序结果，远比直接运行一个排序算法更加昂贵。

除了效率问题之外，很多实际应用还需要代码执行才能提供的确定性和可靠性。

在前面的例子中，PDF Skill 内置了一个预先写好的 Python 脚本。

这个脚本可以读取 PDF，并提取其中所有表单字段。

Claude 可以直接运行脚本，而不需要把：

• 脚本本身；

• PDF 本身；

全部加载进上下文。

而且，因为代码是确定性的，这个工作流能够保持一致且可重复。

Skill 也可以包含可执行代码，Claude 会根据任务性质自行决定什么时候把这些代码作为工具运行。

开发和评测 Skills

下面是一些在编写和测试 Skill 时很有帮助的实践建议。

从评测开始

先用一些具有代表性的任务测试 Agent，找出它当前能力中的具体缺口。

观察它：

• 在哪里失败；

• 在哪里表现不稳定；

• 在哪些地方缺少必要上下文。

然后再针对这些问题逐步构建 Skill。

不要一开始就试图把所有知识全部塞进 Skill，而应该围绕实际暴露出的不足进行增量开发。

为规模化做好结构设计

当 SKILL.md 变得过于庞大时，就应该把内容拆分成多个独立文件，并从主文件中引用它们。

如果某些上下文彼此互斥，或者几乎不会同时使用，那么把它们拆成不同路径可以减少 Token 消耗。

此外，代码既可以作为：

• 可执行工具；

• 文档参考；

存在。

因此，Skill 中应该明确说明：

• Claude 是应该直接运行某个脚本；

• 还是应该先把它读入上下文，作为参考资料。

从 Claude 的视角思考

在真实场景中观察 Claude 如何使用你的 Skill，并根据实际行为不断迭代。

重点观察：

• 是否出现了意外的执行路径；

• 是否过度依赖某一类上下文；

• 是否在错误场景下触发 Skill；

• 是否在需要 Skill 时没有触发。

尤其要仔细设计 Skill 的：

• name

• description

因为 Claude 正是依靠这两个字段，判断当前任务是否应该触发某个 Skill。

与 Claude 一起迭代

当你和 Claude 一起完成任务时，可以让 Claude 把：

• 成功的方法；

• 经常出现的错误；

• 可以复用的上下文；

• 可重复执行的代码；

整理进 Skill。

如果 Claude 在使用某个 Skill 时走偏了，也可以要求它反思发生了什么问题。

这样做能够帮助你发现：

Claude 实际真正需要哪些上下文。

相比开发者一开始就尝试猜测所有需求，这种方法通常更加有效。

使用 Skills 时的安全注意事项

Skill 会通过指令和代码，为 Claude 提供新的能力。

正因为如此，它们非常强大，但也意味着恶意 Skill 可能会：

• 在运行环境中引入漏洞；

• 指示 Claude 泄露数据；

• 引导 Claude 执行并非用户本意的操作。

因此，我们建议只从可信来源安装 Skill。

如果必须安装来源不够可信的 Skill，那么在使用之前，应彻底审查其中内容。

首先阅读 Skill 中包含的全部文件，确认它究竟会做什么。

尤其要注意：

• 代码依赖；

• 内置资源；

• 图片；

• 脚本。

同样，也要留意 Skill 中是否存在这样的指令或代码：

要求 Claude 连接到可能不可信的外部网络资源。

Skills 的未来

目前，Agent Skills 已经在以下产品和平台中得到支持：

• Claude.ai；

• Claude Code；

• Claude Agent SDK；

• Claude Developer Platform。

接下来，我们会继续增加覆盖 Skill 完整生命周期的功能，包括：

• 创建；

• 编辑；

• 发现；

• 分享；

• 使用。

我们尤其期待 Skills 能够帮助组织和个人，把自己的上下文与工作流分享给 Claude。

我们也会继续探索 Skills 如何与 Model Context Protocol（MCP）Server 互补。

例如，MCP Server 可以向 Agent 提供外部工具和软件接口，而 Skill 可以进一步教会 Agent：

如何把这些工具组合起来，完成更加复杂的工作流。

从更长远来看，我们希望 Agent 能够自行：

• 创建 Skill；

• 编辑 Skill；

• 评测 Skill。

这样一来，Agent 就能够把自己逐渐形成的行为模式，沉淀成可重复使用的能力。

Skills 是一个非常简单的概念，其格式同样很简单。

正是这种简单性，让组织、开发者和普通用户都更容易构建定制化 Agent，并赋予它们新的能力。

我们也非常期待看到大家会用 Skills 构建出什么。