Anthropic《Agent Skills》系统解读：渐进式披露与 PPT Master 的分层加载实践
原文：Equipping agents for the real world with Agent Skills
实践项目：PPT Master
前置阅读：《Building effective agents》系统解读
上一篇解读回答的是"如何组织 LLM 与工具"，属于架构问题。这一篇回答的是另一个问题：当一个 Agent 需要掌握的领域知识远超上下文窗口时，这些知识应该以什么形式存在。
对 PPT Master 而言这不是理论问题。以 2026-08-12 的仓库快照 4e6ecbcb 计，references/ 已有 12438 行 Markdown，workflows/、references/ 与 scripts/docs/ 合计 23993 行；系统包含 4 条顶层路由，而 SKILL.md 全文件只有 86 行。这个数量级差异本身就是对渐进式披露机制的一次实测。
本文仍按"基本概念 → 机制 → 判断 → 项目应用 → 形成观点"展开。
一、基本概念：Skill 是什么
Anthropic 对 Skill 的定义是：
Organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.
这个定义里有三个词需要拆开看。
Folders（文件夹）：Skill 不是一段 prompt，也不是一个 API，而是文件系统上的一个目录。这决定了它可以包含任意多的内容，也可以用普通的版本控制和文件工具来维护。
Discover（发现）：Agent 需要能够判断"当前任务是否该用这个 Skill"，而不是由开发者在每次调用时手工指定。
Dynamically（动态加载）：Agent 只在需要时读取内容，而不是启动时全量装入。
三者共同指向同一个约束——上下文窗口。Skill 机制存在的理由，就是让能力的 总量 与单次任务的 上下文占用 解耦。
原文后续更新还说明 Agent Skills 已演进为开放标准。这个变化不影响下面的渐进式披露原理，却进一步说明：Skill 是一种可移植的能力封装方式，不应被理解成只服务于某个单一 Claude 产品的私有目录约定。
最小结构
一个 Skill 至少包含一个 SKILL.md，它必须以 YAML frontmatter 开头，其中 name 和 description 是必填字段。除此之外可以有：
| 组成 | 作用 |
|---|---|
SKILL.md | 入口与主体说明 |
| 附加 Markdown 文件 | 由 SKILL.md 按名称引用的细节文档 |
| 可执行脚本 | Agent 可以直接运行的代码 |
| 其他资源 | 模板、样例、数据文件等 |
二、核心机制：渐进式披露的三个层级
Progressive disclosure 是这篇文章的核心，也是理解 Skill 与"把内容塞进 system prompt"区别的关键。
第一层：元数据
原文的表述是：
The metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context.
只有 name 和 description 会被预加载。它们的唯一职责是让模型判断"这个 Skill 与当前任务是否相关"。
这一层有一个容易被忽略的含义：name 与 description 是预加载元数据，其中 description 承担主要触发语义。Skill 内部写得再完善，如果 description 没能让模型在正确的场景下触发它，后面的所有内容都不会被读到。
第二层：SKILL.md 主体
If Claude thinks the skill is relevant to the current task, it will load the skill by reading its full SKILL.md into context.
一旦判定相关，SKILL.md 全文进入上下文。这意味着它的长度是有代价的——每次触发都要付一次。
原文对此给出的处理方式是：
When the SKILL.md file becomes unwieldy, split its content into separate files and reference them.
第三层及以后：按需导航的附加文件
These additional linked files are the third level (and beyond) of detail, which Claude can choose to navigate and discover only as needed.
关键结论在这里：
Agents with a filesystem and code execution tools don't need to read the entirety of a skill into their context window when working on a particular task. This means that the amount of context that can be bundled into a skill is effectively unbounded.
可打包进 Skill 的内容量实际上是无上限的——前提是 Agent 有文件系统和代码执行能力。
三层的成本模型
下面这张表是笔者按上述机制整理的成本对照，原文没有以表格形式给出，但结论直接来自三层定义：
| 层级 | 何时进入上下文 | 付费频率 | 设计要求 |
|---|---|---|---|
| 元数据 | 始终 | 每次会话 | 极短，且必须准确描述触发条件 |
SKILL.md 主体 | 判定相关时 | 每次触发 | 只放所有路径都需要的内容 |
| 附加文件 | 被显式引用且需要时 | 按实际需要 | 可以很大，但单个文件应可独立消费 |
这个模型解释了一条实用原则：内容应该尽可能往下沉。放在第二层的每一行，都是所有任务共同承担的成本；放在第三层的内容，只由真正需要它的任务承担。
三、为什么要包含可执行代码
原文用一个例子说明代码的必要性：
Sorting a list via token generation is far more expensive than simply running a sorting algorithm.
除了成本，还有可靠性：
Beyond efficiency concerns, many applications require the deterministic reliability that only code can provide.
文中的 PDF Skill 案例把这一点讲得很具体：Skill 内置一个 Python 脚本读取 PDF 并提取全部表单字段，Claude 运行这个脚本时，脚本本身和 PDF 都不需要进入上下文。
这句话值得单独强调。脚本在这里同时省掉了两份上下文开销：指令的（不必用自然语言描述如何解析 PDF）和数据的（不必把 PDF 读进来）。
原文还提醒了一个设计要点：
Code can serve as both executable tools and as documentation. It should be clear whether Claude should run scripts directly or read them into context as reference.
代码有两种用途，必须明确区分。同一个 .py 文件，是让 Agent 执行，还是让它读来理解接口，这两种意图需要在 Skill 里说清楚，否则 Agent 可能把一个几百行的脚本整个读进上下文，只为了知道该怎么调用它。
四、Skill 与 MCP 的关系
原文的定位是互补而非替代：
We'll also explore how Skills can complement MCP servers by teaching agents more complex workflows that involve external tools and software.
可以这样区分：MCP 解决"Agent 能接触到什么外部系统"，Skill 解决"Agent 知道该按什么流程使用它们"。前者提供能力，后者提供方法。一个只有 MCP 没有 Skill 的 Agent，拥有工具但缺少工作流；反过来则是有方法但够不到系统。
五、编写方法：从评估开始，而不是从文档开始
原文给出的开发流程中，第一条最容易被跳过：
Identify specific gaps in your agents' capabilities by running them on representative tasks and observing where they struggle.
先跑代表性任务，观察 Agent 在哪里卡住，再针对性地写 Skill。 这个顺序的意义在于，它保证 Skill 里的每一段内容都对应一个被观察到的真实失败，而不是作者认为"应该说明一下"的内容。
其余几条：
- 主体过长时拆分成独立文件并引用；
- 站在 Claude 的视角审视 Skill，观察真实使用轨迹中是否出现意外路径或对某些上下文的过度依赖；
- 特别重视
name和description，模型据此决定是否触发； - 出错时让 Claude 自我反思哪里出了问题，据此迭代。
原文另外给出一条安全建议：只安装来自可信来源的 Skill；来源可信度不足时，使用前必须彻底审计。
值得注意的顺序
"从评估开始"意味着 Skill 的质量上限由你的观察质量决定。没有跑过真实任务就写出的 Skill，本质上是在猜测 Agent 会在哪里失败。
从概念转入实践
以上五节是对原文的梳理。以下用 PPT Master 检验这套机制：哪些设计与官方意图一致，哪些是项目自创的扩展，以及哪些地方存在真实的偏离。
六、PPT Master 的三层结构实测
先给出体量事实：
| 层级 | PPT Master 的对应物 | 体量 |
|---|---|---|
| 第一层 | SKILL.md frontmatter 的 name + description | description 约 50 个英文词 |
| 第二层 | 完整 SKILL.md | 86 行 |
| 第三层 | workflows/ + references/ + scripts/docs/ | 23993 行 Markdown（当前快照） |
| 资源 | templates/ + references/ 图像资源 | 按需加载，容量随资源集变化 |
第二层与第三层的行数比例接近 1:279。这是当前仓库快照，不是架构不变量；但它足以说明渐进式披露在这里不是可选优化，而是系统能够存在的前提——把这些内容平铺进 system prompt 在任何模型上都不可行。
第二层放了什么
86 行的 SKILL.md 只保留四类内容：
- 强制加载顺序（读本文件 → 跑归属完整性校验 → 读
routing.md→ 选定唯一路由和 profile → 只读对应权威文档）； - 路由/profile 到权威文档的映射表（四条顶层路由及 Generate 的当前 profiles 指向各自 runtime authority）；
- 全局执行纪律与沟通规则（串行执行、阻塞门必须等待确认、不跨阶段打包、不投机执行、失败时回到拥有该制品的源头修复）；
- 仓库兼容与赞助信息边界（不默认创建通用工程结构，赞助/供应商材料只在用户明确请求相关建议时读取）。
这些内容的共同点是：无论最终走哪条路由都必须遵守。这正好符合第二层的设计要求——只放所有路径共同承担的内容。
反过来看，四条路由各自的具体步骤（当前 generate-pptx.md 814 行、create-template.md 999 行）全部下沉到第三层。一次普通 Generate 任务不会读到 Create Template 的 999 行流程。
七、PPT Master 的自创机制：路由作为独立的必读节点
这是 PPT Master 与原文模型最明显的差异，值得单独分析。
按原文的三层定义，第三层文件是"按需导航发现"的。但 workflows/routing.md 不是按需的——SKILL.md 把它列为 强制第 3 步，任何任务都必须读。
于是 PPT Master 实际形成的是一个四段结构：
元数据（常驻）
→ SKILL.md 86 行（触发即读）
→ routing.md（触发即读，负责选路）
→ 选中路由的权威文档（按路由读）
→ 该路由触发的支持文档（按需读）这不是对原文的违背，而是一次合理改造。原因可以推导：如果把四条路由与各 Generate profile 的完整判定矩阵写进 SKILL.md，第二层会从 86 行膨胀到数百行，而其中大部分内容对任何单次任务都是无用的——你只会走一条路和一个活动 profile。把"选路逻辑"独立成一个必读文件，等于在第二层和第三层之间插入了一个 薄的调度层。
routing.md 自身也贯彻了同样的纪律，它明确声明：
If this file conflicts with a route summary elsewhere in the Skill package or in a repository-level user-facing document, this file wins for route selection. After selection, the route authority owns execution.
选路的权威和执行的权威被分开了。 这解决了多文档系统中最常见的问题：同一件事在多处被描述，Agent 不知道该信哪一份。
笔者归纳
当 Skill 存在多条差异极大的执行路径时，"三层"可能不够用。在第二层与第三层之间增加一个只负责调度的薄层，可以让第二层保持最小，同时避免路由逻辑散落在各个路由文档里互相矛盾。
八、description 字段的实际写法
第一层是唯一常驻上下文的部分，PPT Master 的写法是：
name: ppt-master
description: >
AI-driven presentation workflow for generating editable PPTX decks,
reconstructing page visuals, creating reusable Brand/Style/Layout/Deck
workspaces, filling native PPTX templates, and enhancing finished PPTX files.
Use when the user asks to create, reconstruct, regenerate, template, fill, or
enhance a presentation, requests a presentation-authored narrated/self-running
video, or mentions ppt-master.按原文对这一层的要求（"just enough information to know when each skill should be used"）逐条检查：
| 检查项 | PPT Master 的处理 |
|---|---|
| 说明能力范围 | 覆盖生成/重构、可复用工作区、原生填充、原生增强，以及 Generate 路线内的演示文稿视频交付 |
| 给出触发条件 | Use when the user asks to... 显式列举动作，并补充演示文稿创作的视频请求 |
| 覆盖显式调用 | or mentions ppt-master 兜底 |
| 控制长度 | 约 50 个英文词，没有展开任何实现细节 |
值得注意的是 触发动词与路由的对应关系：create / reconstruct / regenerate 和 presentation-authored video 对应 Generate，template 对应 Create Template，fill 对应 Fill Native，enhance 对应 Enhance Native。第一层的措辞覆盖四条制品生命周期；视频仍是 Generate 的条件能力，不被误写成第五条路线。
九、代码的两种角色在 PPT Master 中的落地
原文强调必须区分"运行脚本"和"读脚本作参考"。PPT Master 用目录结构解决了这个问题：
| 位置 | 角色 | 例子 |
|---|---|---|
scripts/*.py | 执行 | attribution_guard.py、batch_validate.py、compact_svg_coordinates.py、finalize_svg.py |
scripts/docs/*.md | 阅读 | svg-pipeline.md（826 行）、confirm_ui.md（599 行）、conversion.md（592 行） |
Agent 读 scripts/docs/ 下的 Markdown 来理解接口，然后执行 scripts/ 下的 Python，而不需要把 Python 源码读进上下文。 这恰好是原文那句提醒的正面实现。
这些脚本承担的也确实是代码擅长而 token 生成不擅长的工作：SVG 坐标压缩、批量校验、完整性校验、导出收尾。它们都是确定性的，且结果可以被检查——这与上一篇解读中"凡是机器能够直接验证的事实，就不要让 LLM 用自然语言宣布成功"是同一条原则。
一个原文没有覆盖的用法
references/ 下有 45 个 PNG 文件，组织在 ai-image-comparison/ 的 palette、rendering、type 三个子目录中，并配有 _manifest.json 与 _manifest.md。
这是把 视觉样本 作为第三层内容。原文讨论渐进式披露时，例子都是文本与脚本；PPT Master 把图像也纳入了按需加载的资源池。不过三个子目录的现行地位并不相同：常规选图流程只使用 rendering/ 参考，palette/ 已退为兼容性诊断资料，不得影响当前决策，type/ 则是内部构图参考。渐进式披露描述的是加载方式，并不意味着目录中的所有样本都参与日常决策。
笔者观点
渐进式披露的对象不限于文本。任何"描述成本低、但精确判断必须看原件"的资源，都适合放在第三层，并在上层保留一份可检索的文字索引。
十、对照原文校准三个差异
以下是笔者基于原文对 PPT Master 现状的检查结论，不是原文内容，也不自动构成项目路线图。是否改变现行机制，应由真实失败、预算压力或明确的比较需求触发。
1. 第三层文件是否过大，需要运行证据判断
原文的建议"当 SKILL.md 变得笨重时拆分"，其逻辑也可以用于审视第三层文件。当前 create-template.md 有 999 行，并已拆出 create-template/ 子目录（create-brand.md 161 行、create-deck.md 130 行、create-layout.md 123 行、create-style.md 187 行）。行数只能提示审计对象，不能单独证明文件需要继续拆分。
是否继续下沉，应检查实际加载路径、模板类型之间共享的契约，以及是否出现上下文预算或执行错误。只有某一类内容确实只服务于单一模板类型且造成真实压力时，拆分才有收益。
同样，svg-effects.md（866 行）和 image-generator.md（776 行）适合列入按需加载审计，但不应只因文件较长就判定为现行缺陷。
2. 没有按原文建立正式任务评估集
原文把"在代表性任务上运行、观察失败点"放在开发流程的第一位。PPT Master 当前有静态 prompt 审计、路线内质量门和展示样例，但没有把它们组织成 可重复运行的跨版本任务集，因此不能用统一成功率回答"补充的这段说明是否降低了失败率"。
这是能力边界，不代表项目现在需要建立通用测试系统。只有要比较顺序生成与并行生成等具体策略，或出现可复现的行为回归时，才需要为该问题整理最小可重放任务；第六篇会继续区分展示样例与正式评估集。
3. 跨任务自我反思没有成为通用机制
原文建议：Agent 用 Skill 出错时，让它自我反思哪里出了问题，并据此迭代。
PPT Master 已经有"失败时回到拥有该制品的源头修复"的运行时纪律，但这是 当次任务内的恢复，不是 跨任务的改进回路。仓库也没有系统性收集所有 Agent 轨迹。新增这类记录会带来维护与数据边界成本，只有反复出现且需要跨任务归因的问题，才足以触发相应机制。
十一、我的理解：Skill 是把上下文预算显式化的手段
从原文到 PPT Master 的实测，我对 Agent Skills 的理解可以概括为一句话：
核心观点
Skill 的价值不在于"能装下更多知识"，而在于 它强迫你为每一段知识标价——放在哪一层，就决定了谁来付这个成本。
三层结构本质上是三种定价：
- 第一层的内容，全会话付费，所以只能放触发判断所需的最小信息；
- 第二层的内容，每次触发付费，所以只能放所有路径共享的部分；
- 第三层的内容，按需付费，所以可以近乎无限。
当一段内容"应该放在哪一层"变得难以决定时，通常说明它承担了多重职责，需要先拆分再归位。PPT Master 把路由逻辑从第二层剥离成独立的调度层，就是这个判断的一次应用。
而"从评估开始"这条建议之所以排在最前面，是因为它决定了这套定价是否建立在事实上。没有观察到真实失败就写下的内容，无论放在哪一层，都是在为想象中的问题付费。
十二、下一步
按照与 PPT Master 的相关度，接下来的学习顺序是：
- Effective context engineering for AI agents— 本篇讨论的是知识如何分层存放，这篇讨论运行时上下文如何管理，两者互补（系统解读）；
- Effective harnesses for long-running agents— 生成一份完整演示文稿是典型的跨上下文窗口任务（系统解读）；
- Writing effective tools for agents— 深化
scripts/这一层的接口设计（系统解读）； - Demystifying evals for AI agents— 补上本文第十节指出的评估缺口（系统解读）。