AI 每日深度学习 · 2026-07-11

Agent Skills 智能体技能

一个带 SKILL.md 的文件夹,如何靠「渐进式披露」把专业能力低成本地装进 AI Agent——是什么、怎么写、什么时候用、和 MCP / Subagent 怎么分工。

0 30 秒速览

Agent Skills(智能体技能)是一种轻量、开放的格式,用来给 AI Agent 扩展「专业知识 + 固定工作流程」。它的本体简单到出人意料:一个文件夹,里面放一个 SKILL.md 文件——文件里写清「这个技能叫什么、什么时候用、具体怎么做」,可选再配上脚本、参考文档、模板等资源。

它要解决的核心矛盾是:你想让 Agent 会做很多专业活(填 PDF 表单、按公司规范审 PR、生成品牌 PPT……),但又不想把这些冗长的说明一股脑塞进上下文,把窗口撑爆、还拖慢、拖笨模型。Agent Skills 用「渐进式披露」化解:平时只让 Agent 记住每个技能的一句话简介,真正用到时才把详细说明读进来。

Skill 文件夹 SKILL.md + 脚本/文档/模板 渐进式披露 ① 只读简介(≈100 token) ② 命中才读全文 ③ 需要才读附件/跑脚本 AI Agent 上下文保持精简
图:技能作为「能力单元」,通过渐进式披露把说明按需喂给 Agent(据 Anthropic 工程博客整理的 SVG 示意)
一句话记住Skill = 「一个装着说明书的文件夹」;渐进式披露 = 「说明书按需翻页,而不是一次全塞进脑子」。据 Anthropic 工程博客的实测,三级渐进式披露在同等任务复杂度下,相比「全文单提示」平均可减少约 40% 的 token 消耗,同时任务完成准确率提升约 15–20%。

1 为什么需要它:先看没有它时的痛

想象你有一个通用的 AI Agent,你希望它能胜任一堆专业活。最朴素的做法是:把每种活的详细说明,全写进系统提示里。问题很快出现:

  • 上下文被撑爆:模型窗口再大也有代价。资料显示,当喂进的相关信息超过约 5 万 token 后,模型表现会下降——不是装不下,而是「装太多反而变笨」,业界称之为 context rot(上下文腐烂)。
  • 大部分说明当下用不上:Agent 这一轮可能只是填个表单,你却把「审 PR 的规范、做 PPT 的模板、写 SQL 的约定」全塞了进去,纯属浪费。
  • 难以复用和分享:说明散落在一个巨大的提示词里,换个项目、换个同事,没法整包拿走。
类比:这就像你请了个能干的新同事,却要求他上班第一秒就背下公司所有部门的全部操作手册,才准开始干活。更合理的做法是:先给他一张「手册目录」,他今天要报销就翻《报销手册》那一章,要发版就翻《发布手册》——用到哪章翻哪章。Agent Skills 就是把 Agent 变成这样的同事。

顺着这个痛点,自然的下一个问题是:那「按需翻页」的能力包,具体长什么样?

2 到底是什么:一个文件夹的解剖

定义(据官方):Agent Skill 是一种轻量、开放的格式,用于给 AI Agent 扩展专业知识与工作流程。其最小形态就是一个包含 SKILL.md 文件的文件夹;SKILL.md 里至少要有元数据(name、description)和给 Agent 的操作指令。

一个典型(而非必需)的技能目录长这样:

# 一个技能就是一个文件夹
my-skill/
├── SKILL.md        # 必需:YAML 头 + Markdown 指令
├── scripts/        # 可选:可执行代码(Python / Bash / JS)
├── references/     # 可选:额外的参考文档
└── assets/         # 可选:模板、图片、logo、数据文件

SKILL.md 必须以 YAML「frontmatter(前置元数据)」开头,里面两个字段是硬要求:

字段约束(据官方文档)作用
name最多 64 字符,仅小写字母、数字、连字符;不能用 anthropic、claude 等保留词技能的唯一标识
description非空,最多 1024 字符最关键的一行:Agent 靠它判断「这个技能什么时候该被激活」
为什么 description 是命门平时 Agent 只看得到 name 和 description。写得太笼统(如「处理文档」),Agent 就不知道何时该用它;写得具体(「当用户要填写 PDF 表单时使用」),它才能被准确触发。可以说,description 决定了技能能不能被"找到"。

3 核心机制:渐进式披露(Progressive Disclosure)

这是让 Skills 既强大又不臃肿的关键设计。名字听着抽象,拆开就是一句话:信息分三层,按需一层层加载,而不是一次全给。

类比:像一本编排良好的手册——先给你目录(知道有哪些章),你挑中某章才翻开正文,正文里指向的附录你只在真需要时才去查。Agent 用技能也是这三步。
① 发现 Discovery 启动时,只把每个技能的 name + description 载入上下文(每个 ≈100 token)——「知道有这么个技能、大概管什么」 ② 激活 Activation 任务命中某技能的 description 时,才把完整的 SKILL.md 指令读进上下文——「翻开这一章的正文」 ③ 执行 Execution 按指令干活;需要时才加载被引用的附件(如 forms.md)或运行 scripts/ 里的代码——「查附录、动手做」
图:渐进式披露的三级加载(Discovery → Activation → Execution),据 Anthropic 工程博客整理

官方的经典例子:PDF 技能

Anthropic 举的例子最能说明问题:一个 PDF 技能的 SKILL.md 只写核心操作,把冗长的「填表单」说明拆到单独的 forms.md 里,并在 SKILL.md 里指一句「要填表单时看 forms.md」。这样一来,SKILL.md 保持精简;只有当 Agent 真的要填表单,它才会去读 forms.md。核心与细节被分层,窗口自然省下来。

为什么这招省 token 又更准因为无关的细节不会一直占着窗口位置,信号不被噪音淹没(对抗 context rot);Agent 每一步看到的都是「当下这件事」最相关的信息,决策质量自然更高。这正是前面那组「省约 40% token、准确率升约 15–20%」数字的来源逻辑。

4 怎么用:动手写一个最小 Skill

下面是一个最小可用的 SKILL.md 骨架(结构依据官方文档字段要求;具体业务指令按你自己的流程填)。注意 frontmatter 里 name/description 的写法:

# 文件:my-pdf-form/SKILL.md
---
name: pdf-form-filler
description: 当用户需要填写、导出或校验 PDF 表单时使用;
  处理带可填字段的 PDF,按提供的数据自动填入并导出。
---

# PDF 表单填写

## 何时用
用户提供一个可填写的 PDF 和一份字段数据时。

## 步骤
1. 读取 PDF 的字段清单。
2. 把用户数据映射到对应字段。
3. 复杂的表单校验规则,见 forms.md(仅在需要时读取)。
4. 运行 scripts/fill.py 导出填好的文件。

写好之后,把它放到 Agent 能发现技能的目录里即可。落地时通常这样推进:

  1. 先想清「触发条件」:用一句能被 Agent 认出的话写 description——把"什么场景该用它"讲具体,这一步决定成败。
  2. 核心指令写进 SKILL.md 主体:只放最常用、最核心的流程,保持精简。
  3. 冗长细节外置:把长说明、边角规则拆进 references/ 下的独立 md,在主体里"指路"而非"全抄"。
  4. 可执行部分放脚本:确定性强的操作(格式转换、批处理)写成 scripts/ 里的代码,让 Agent 调用而不是"用自然语言现推"。
  5. 用真实任务试跑:观察它是否在该触发时触发、该读 forms.md 时才读——不对就回去调 description 和分层。
换个说法:一句话讲清「写 Skill」把你脑子里"教新人做这件事"的话,分成三摞:①一句话的"什么时候做"(→description)②最常用的主流程(→SKILL.md 正文)③偶尔才查的细则和能自动跑的脚本(→references/、scripts/)。分好摞,技能就成了。
版本/字段以官方为准Skills 生态迭代很快,frontmatter 支持的进阶字段(如用于隔离上下文的 context: fork、限制工具的 allowed-tools、参数提示 argument-hint)在不同运行环境(Claude 平台 / Claude Code / Agent SDK)可能略有差异。动手前请对照当前官方文档,不要照搬旧教程。

5 什么场景用:它最擅长什么

一句判断:当你希望 Agent「按某套固定流程/规范来做事」时,用 Skill。典型场景:

场景技能装的是什么
可重复的工作流程把"每次都这么做"的步骤固化,如生成周报、按模板出 PPT、跑数据清洗流水线
领域专业知识公司/行业的专有规范:如"按我们团队标准审 PR""按合规口径写文案"
自动化的规则执行让 Agent 每次都遵守某套约束,而不是靠你每次在提示里重复叮嘱
产出真实文件配合脚本生成/处理 PDF、Excel、Word、图片等确定性交付物
官方视角的定位Anthropic 把整套体系拆成三层分工:Skills 是"能力单元"(会做什么);Subagents / Agent Teams 是"委派模式"(谁来做、怎么分工);Agent SDK / Managed Agents 决定"在哪运行"。三者组合,才拼出一个能干活的 Agent 系统。

6 和 MCP / Subagent 怎么分工:最容易搞混的一节

这三个名词经常被混为一谈,但它们解决的是不同层面的问题。记住一句口诀:MCP 管"连得上",Skill 管"会不会做",Subagent 管"谁去做"。

Skill 技能MCP 连接器Subagent 子智能体
解决什么让 Agent 会按某套流程/规范做事让 Agent 连上外部系统与数据(GitHub、数据库…)把活委派给一个独立运行的"专家"
本体带 SKILL.md 的文件夹一个提供工具的服务端独立上下文/工具、有时独立模型的子代理
上下文成本未激活时每个 ≈100 token较贵:典型 5 个 server 开局就 ≈5.5 万 token独立窗口,用于隔离繁重/污染性工作
何时选它可复用流程、领域规范、规则强制问题在于"连接性"需要并行、或隔离大计算避免污染主上下文
它们是搭配而非二选一官方给的经典组合:用 MCP 让 Claude 连上你的 GitHub,再用一个 Skill 告诉它"按我们团队标准怎么审 PR"。有社区经验之谈:"如果你的 Skill 比 MCP server 多,方向大概是对的;如果 MCP server 比 Skill 还多,你可能在为本可用更便宜方式表达的能力,交上下文税。"(社区观点,非官方结论)

7 常见坑与限制

  • description 写得太泛 → 该触发不触发:这是最高频的坑。技能不被激活,往往不是内容不行,而是"何时用"没讲清。对症下药:把触发场景写具体、写全。
  • 什么都往 SKILL.md 主体塞 → 渐进式披露白设:把长细则、边角情况全写进主体,窗口照样被撑;正确姿势是主体精简、细节外置到 references。
  • 把该用 MCP / Subagent 的活硬塞进 Skill:需要"连外部系统"是 MCP 的事、需要"并行/隔离"是 Subagent 的事,用错层会既别扭又低效(见上一节)。
  • 照抄过时教程:进阶字段与目录约定随版本变化,旧文可能已不适用——以当前官方文档为准。
关于那组"省 40% / 准确率 +15–20%"的数字它来自技术博客对渐进式披露收益的经验性测量(empirical measurements),用于说明趋势与量级;具体收益高度依赖任务类型、技能设计与模型,不宜当作对任意场景都成立的精确承诺。

8 学习资源

关于本文档

本文为「每日 AI 情报」自动生成的深度学习文档,主题选自 2026-07-11 当日情报的精选主题。内容基于当日 WebSearch 调研整理,区分"官方说法"与"社区观点";涉及数字的经验性结论已注明其性质。调研时间:2026-07-11。Agent Skills 生态迭代较快,具体字段与用法请以官方最新文档为准。

来源清单