Agent Skills· Anthropic Engineering
原文
Engineering at Anthropic · 2025-10-16

给通用 Agent 装上专业知识 · Agent Skills

模型越来越强,但真实工作还需要程序性知识和组织上下文。Anthropic 用一种极简的格式回答这个问题: 一个文件夹、一份 SKILL.md、加上按需加载的脚本和资源。

阅读约 10 分钟 作者 Barry Zhang · Keith Lazuka · Mahesh Murag 核心概念 渐进式披露 · 文件即接口
TL;DR · 30 秒抓核心

Skill = 一个带 SKILL.md 的文件夹。SKILL.md 的 YAML 头里只放 namedescription, 启动时会被加载进系统提示,作为所有 skill 的"目录";正文和附带的脚本 / 文档,只有当 Claude 判断这个 skill 与当前任务相关时才会被读进上下文。

关键设计是渐进式披露:上下文里始终只装"当前需要"的那部分,所以一个 skill 可以打包任意多的程序性知识,而不会撑爆 context window。 Skill 还可以包含可执行脚本,让 Claude 把那些"代码做更可靠"的事情交给确定性的代码去做。

01 · 起点

为什么通用 Agent 还差最后一公里?

模型能在通用任务上表现很好,但落到具体团队、具体流程时, 总是缺少"那一份只有你才知道的程序性知识"。

随着模型能力变强,我们已经可以构建在真实环境中独立行动的通用 Agent —— Claude Code 就是这样一个例子,它能借助本地代码执行和文件系统跨领域完成复杂任务。 但越是通用,越需要可组合、可扩展、可移植的方式把领域专家的知识喂给它。

Anthropic 的回答是 Agent Skills:把一份份程序性知识打包成"一个文件夹 + 一份 SKILL.md"的形式,让 Agent 在需要时自己去发现和加载。 作者把这件事比作给新员工写入职指南 —— 你不会一次性塞所有制度给新人,而是先给一份目录,让他在遇到问题时再翻特定章节。

不解决会怎样
每个用例都得做一个定制 Agent
原本要为每个新场景重新搭一套提示、一套工具、一套上下文,结果是碎片化的、互不兼容的 Agent 集合, 团队的程序性知识既没沉淀也没复用。
Skills 怎么解
把"专家知识"做成可拼装的资源
任何人都能把一段流程、一份模板、一个脚本写成 skill,扔进文件夹。 通用 Agent 在需要时自己 发现 → 加载 → 调用,专业 Agent 由通用 Agent 加上一组合适的 skill 拼出来。
02 · 它长什么样

一个 skill = 一个文件夹

最简形态:一个文件夹,里面有一份 SKILL.md,开头是一段 YAML frontmatter 描述这个 skill 的身份。

文章中举了 Claude 文档编辑能力背后的 PDF skill 作为例子。Claude 本身已经知道很多关于 PDF 的事情, 但直接操作(比如填表单)还差一截。PDF skill 就是来补这部分能力的。

当一个 skill 的内容多到一份 SKILL.md 装不下,或某些章节只在特定场景才需要时, 就把它们拆成 SKILL.md 旁边的附带文件,在主文件里按名字引用。 Claude 只在真的需要时才去读那些附带文件。

📁pdf/skill 目录
├─SKILL.md入口 · 主文件
├─reference.md第三层 · 参考
├─forms.md第三层 · 填表流程
└─scripts/可执行代码
   └─extract_fields.py读取 PDF 表单字段

SKILL.md 的开头是元数据

每个 SKILL.md 必须以 YAML frontmatter 开头,至少包含 namedescription。 这两段会在 Agent 启动时被加载进系统提示,作为「skill 目录」的索引

这个 description 写得好不好,直接决定 Claude 能不能在需要的时候联想到这个 skill。 作者特别强调:把 name 和 description 当成触发条件来写

--- name: pdf description: Read, fill, and edit PDF documents, including form fields and signatures. --- # PDF Skill For form-filling workflows, see forms.md. For low-level PDF spec details, see reference.md.
03 · 核心机制

渐进式披露 · 把上下文按需打开

从"目录"到"章节"再到"附录",Claude 只读它当下需要的那一层 —— 这是 Skills 能做大、做多、做杂的根本原因。

作者打了一个比喻:好的手册从目录开始,再到具体章节,最后才是详细附录。 渐进式披露就是把这套阅读节奏直接搬进了 Agent 的 context window。

一个 Agent 配了 n 个 skill,并不意味着上下文里要塞 n 份手册的全文。 实际上常驻的,只有每个 skill 的一段元数据

↓ 三层加载,token 成本逐层放大但只在需要时才支付
L1
Always
元数据(name + description)
所有已安装 skill 的名字描述,启动时就预载进系统提示。 它的作用是让 Claude "知道有哪些工具可用"。
触发条件
系统启动
~30tokens
每个 skill
L2
On match
SKILL.md 正文
当 Claude 判断这个 skill 与当前任务相关,就读入完整 SKILL.md: 主流程、术语、关键约束、对其他附带文件的指引。
触发条件
任务匹配
~5Ktokens
读入一次
L3+
As needed
附带文件 / 脚本(forms.md、reference.md、scripts/…)
只在真正用到的时候才读 —— 比如要填表单时才打开 forms.md。 脚本则可以"运行而不读"。
触发条件
子任务命中
理论无上限
关键含义:因为有"代码执行 + 文件系统"两件套,Agent 不必把整个 skill 读进 context window。 所以一个 skill 能打包的程序性知识量,实际上是无界的
04 · 走一遍 PDF 例子

四步看懂 context window 怎么变化

点上方任意一步,看看用户问"帮我填这份 PDF"时,Claude 的上下文是怎么逐层打开的。

Context Window
大约 ~3.2K tokens 占用
四步走完之后回头看:用户那句"帮我填这份 PDF"触发了一系列由小到大的加载。 只有最相关的部分进了上下文,附带文件按需打开,最重的活(解析 PDF 字段)甚至全程没进上下文 —— 它在沙盒里跑,只把结果回来。这就是"渐进式披露 + 代码执行"放在一起的威力。
05 · 不只是文档

Skill 也可以打包代码 · 让模型把"该用代码做的事"交给代码

大模型擅长的事很多,但排序、解析二进制、读取 PDF 字段这种事, 让模型一个 token 一个 token 地生成既慢又贵,还不一定对。

在 PDF skill 里,Anthropic 预先写了一段 Python 脚本,用来读取 PDF 并提取所有表单字段。 Claude 可以直接运行这个脚本既不用把脚本读进上下文,也不用把 PDF 读进上下文。 因为代码是确定性的,这个流程稳定可重复 —— 这是任何 token 生成都给不了的保证。

如果让模型自己做

用 token 生成"硬解析"PDF

把整份 PDF 塞进上下文,让模型一格一格地"看"出哪里是字段、哪里是签名位 —— 慢、贵、还可能漏

对每一份新 PDF 都要重来一次。

Skill 里打包好的脚本

调用 extract_fields.py

Claude 看到 SKILL.md 里写的"用 extract_fields.py 读取字段", 直接 bash 调用脚本,只有结果(字段列表)回到上下文

# inside Claude's bash tool $ python pdf/scripts/extract_fields.py form.pdf [{"name": "applicant_name", "type": "text"}, {"name": "signature", "type": "signature"}]
06 · 怎么写一个好 skill

四条作者亲口讲的实操经验

点开任一卡片,看看它对应的具体做法。

01 · 起点
+
从评测开始,而不是从写文档开始
先在真实任务上跑一遍 Agent,看它在哪儿卡住,再针对性地补 skill。
找到具体的能力缺口才能写出有用的 skill。空想"它可能需要什么"很容易写出大而无当的 skill, 最后既触发不准,也没人愿意维护
02 · 规模化
+
SKILL.md 撑不下时,立刻拆文件
把互斥或低频路径拆成附带文件,主文件保持轻盈、token 友好。
如果两条路径几乎不会同时被用到(例如解析 PDF vs 填表),就拆开。 另外,代码既可以是工具也可以是文档 —— 在 SKILL.md 里说清楚是"运行它"还是"读它"。
03 · 视角
+
站在 Claude 的角度看 skill 怎么被用
观察真实 trace,重点看 name / description 是不是能精准触发。
真实使用时它走错了哪条路?过度依赖了哪段上下文?回过头去改 skill。 name 和 description 是触发开关,写不好的话整个 skill 都不会被叫起来。
04 · 协同
+
和 Claude 一起迭代 skill
让模型自己复盘哪里走偏,把成功路径沉淀回 skill 里。
做完一个任务,让 Claude 把"这次哪里做对、哪里走弯路"反思总结成可复用的 skill 内容。 这比你提前预测它"需要什么上下文"靠谱得多 —— 真实需要由真实使用揭示
07 · 风险 & 未来

它强大也意味着它危险 · 它简单也意味着它能长出更多

Skill 给 Claude 注入的是"指令 + 代码",所以它能放大能力,也能放大恶意。 但同样因为格式简单,它有非常大的演化空间。

装载之前,先审计

恶意 skill 可能往运行环境里塞漏洞,或引导 Claude 把数据外发,做出预期之外的动作。
  • 只装来自可信来源的 skill。
  • 来自非完全可信来源时,逐文件审一遍:注意代码依赖、附带的图片或脚本。
  • 特别留意"指示 Claude 连接外部网络"的指令或代码。

Skills 接下来会去哪

目前 Claude.ai、Claude Code、Claude Agent SDK、Developer Platform 都已经支持。
  • 持续完善创建 / 编辑 / 发现 / 分享的全生命周期工具。
  • 探索 Skills 与 MCP server 的互补关系:用 skill 教更复杂的工作流。
  • 更长远:让 Agent 自己创建、编辑、评估 skill,把行为模式沉淀成可复用能力。

Skills 是一个简单的概念,对应的是一个同样简单的格式。 正是这种简单,让组织、开发者和最终用户都能定制自己的 Agent,赋予新能力。 作者最后一句话很克制:Skills 一开始只是给文件夹的人写的;接下来轮到 Agent 自己来写文件夹了。