Anthropic《Agent Skills》系统解读：渐进式披露与 PPT Master 的分层加载实践

原文：Equipping agents for the real world with Agent Skills
实践项目：PPT Master
前置阅读：《Building effective agents》系统解读

上一篇解读回答的是"如何组织 LLM 与工具"，属于架构问题。这一篇回答的是另一个问题：当一个 Agent 需要掌握的领域知识远超上下文窗口时，这些知识应该以什么形式存在。

对 PPT Master 而言这不是理论问题。以 2026-09-09 的仓库快照 3ad8052e 计，references/ 已有 9151 行 Markdown，workflows/、references/ 与 scripts/docs/ 合计 18308 行；系统包含 3 条顶层路由，而 SKILL.md 全文件只有 142 行。这个数量级差异本身就是对渐进式披露机制的一次实测。

对比 2026-08 的上一次快照有个值得注意的方向：第三层从 23993 行降到 18308 行，第二层却从 86 行涨到 142 行。总量在收缩，入口在变厚——后文第六、七节会说明这两个方向各自换来了什么。

本文仍按"基本概念 → 机制 → 判断 → 项目应用 → 形成观点"展开。

一、基本概念：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` 约 67 个英文词
第二层	完整 `SKILL.md`	142 行
第三层	`workflows/` + `references/` + `scripts/docs/`	18308 行 Markdown（当前快照）
资源	`templates/` + `references/` 图像资源	按需加载，容量随资源集变化

第二层与第三层的行数比例接近 1:129。这是当前仓库快照，不是架构不变量；但它足以说明渐进式披露在这里不是可选优化，而是系统能够存在的前提——把这些内容平铺进 system prompt 在任何模型上都不可行。

第二层放了什么

142 行的 SKILL.md 保留这几类内容：

强制加载顺序（保留宿主给的绝对 SKILL_DIR → 读本文件 → 跑归属完整性校验 → 读 routing.md → 选定唯一路由和 profile → 只读对应权威文档）；
路由/profile 到权威文档的映射表（三条顶层路由，加上 Generate 的 Image to PPTX、Beautify、Default、显式 Quick 四个入口，各自指向 runtime authority）；
可表达范围（Authored Expression Range：一页可以承载的文本、几何、图像、涂装与母题形式，明确标注为"参考而非约束"）；
术语表（Vocabulary：约 20 个词的唯一释义，例如 Reference、Composition、carrier、page job、pptx_structure.mode，并点名哪些词有多义、由哪份文件指定当前义项）；
阶段框架（Phase Frame：每条路由都是一次 Plan → Do·Check·Act，并给出 Default、Quick、Edit Native、Create Template 四个运行时各自的步骤区间）；
全局执行纪律（七条：串行执行、阻塞门必须等待确认、不跨阶段打包、进入前校验前置、不投机执行、路由确定性、失败时在拥有该故障的最浅层修复）；
全局沟通规则与仓库兼容边界（跟随用户语言、角色切换前先声明读了哪份角色定义；不默认创建通用工程结构，赞助/供应商材料只在用户明确请求相关建议时读取）。

这些内容的共同点是：无论最终走哪条路由都必须遵守。这正好符合第二层的设计要求——只放所有路径共同承担的内容。

反过来看，三条路由各自的具体步骤（当前 generate-pptx.md 376 行、create-template.md 380 行、edit-native-pptx.md 171 行）全部下沉到第三层。一次普通 Generate 任务不会读到 Create Template 的 380 行流程。

入口变厚的那 56 行装了什么

上一次快照的 SKILL.md 是 86 行，现在是 142 行。多出来的部分几乎全是第 3、4、5 三类——可表达范围、术语表和阶段框架。这三类都不是"步骤"，而是跨路由的共享语义。

这是一个有意思的调整方向。原文对第二层的要求是"只放所有路径共有的内容"，通常被理解成共有的规则；PPT Master 把共有的词义也放了进去。理由可以推导：当第三层有几十份文件、同一个词（Layout、mode、anchor、carrier）在不同文件里指不同东西时，术语歧义会在跨文件加载时爆发，而这恰恰是按需加载最难自查的一类错误——Agent 只读了其中一份文件，根本看不到冲突。把释义提到常驻的第二层，相当于用固定成本换取所有第三层文件之间的语义一致。

代价是第二层不再最小。是否划算取决于第三层的规模：文件少的时候这是纯浪费，文件多到互相引用时它才开始回本。

七、PPT Master 的自创机制：路由作为独立的必读节点

这是 PPT Master 与原文模型最明显的差异，值得单独分析。

按原文的三层定义，第三层文件是"按需导航发现"的。但 workflows/routing.md 不是按需的——SKILL.md 把它列为 强制第 3 步，任何任务都必须读。

于是 PPT Master 实际形成的是一个四段结构：

text

元数据（常驻）
  → SKILL.md 142 行（触发即读）
    → routing.md（触发即读，负责选路）
      → 选中路由的权威文档（按路由读）
        → 该路由触发的支持文档（按需读）

这不是对原文的违背，而是一次合理改造。原因可以推导：如果把三条路由与各 Generate profile 的完整判定矩阵写进 SKILL.md，第二层会从 142 行膨胀到数百行，而其中大部分内容对任何单次任务都是无用的——你只会走一条路和一个活动 profile。当前 routing.md 有 115 行，其中光是 Generate 的 profile/stage 触发条件表就有近 20 行判定；这些内容留在调度层，才不会污染入口。把"选路逻辑"独立成一个必读文件，等于在第二层和第三层之间插入了一个 薄的调度层。

routing.md 自身也贯彻了同样的纪律，它明确声明：

Hard rule: when this file conflicts with a route summary elsewhere in the Skill package or a repository-level document, this file wins for route selection. After selection, the active runtime authority owns execution.

选路的权威和执行的权威被分开了。 这解决了多文档系统中最常见的问题：同一件事在多处被描述，Agent 不知道该信哪一份。

笔者归纳

当 Skill 存在多条差异极大的执行路径时，"三层"可能不够用。在第二层与第三层之间增加一个只负责调度的薄层，可以让第二层保持最小，同时避免路由逻辑散落在各个路由文档里互相矛盾。

八、`description` 字段的实际写法

第一层是唯一常驻上下文的部分，PPT Master 的写法是：

yaml

name: ppt-master
description: >
  AI-driven presentation workflow for generating editable PPTX decks and slides,
  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, generate, reconstruct, regenerate, beautify,
  redesign, template, fill, or enhance a presentation, PPT, PPTX, slide deck, or
  courseware — including adding narration or animation to one — 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` 兜底
控制长度	约 67 个英文词，没有展开任何实现细节

值得注意的是 触发动词与路由的对应关系：create / generate / reconstruct / regenerate / beautify / redesign 和 presentation-authored video 对应 Generate，template 对应 Create Template，fill / enhance（含"加旁白""加动画"）统一对应 Edit Native PPTX。第一层的措辞覆盖三条制品生命周期；视频仍是 Generate 的条件能力，不被误写成第四条路线。

这里能看到第一层与路由结构的一个不对称：顶层路线从四条并成三条，description 反而变长了（约 50 词 → 约 67 词），新增的是 generate / beautify / redesign 这类同义触发词，以及 PPT / PPTX / slide deck / courseware 这类同义制品名。方向是清楚的——第一层要匹配的是用户怎么说，不是系统怎么分路；路由合并属于内部结构收敛，不该反过来收窄触发面。第一层按语言覆盖度写，第二层往下才按结构写。

九、代码的两种角色在 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`（1255 行）、`svg-contract.md`（807 行）、`conversion.md`（685 行）

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 变得笨重时拆分"，其逻辑也可以用于审视第三层文件。这一节在上一次快照里点了四个审计对象，一个月后的结果值得记录，因为三个缩了、一个反而涨了：

文件	2026-08 快照	当前快照	方向
`workflows/create-template.md`	999 行	380 行	↓ 大幅下沉
`references/svg-effects.md`	866 行	602 行	↓
`references/image-generator.md`	776 行	430 行	↓
`scripts/docs/svg-pipeline.md`	826 行	1255 行	↑

值得注意的是 create-template.md 少掉的 619 行没有落进子目录：四个子工作流现在是 create-brand.md 94 行、create-deck.md 63 行、create-layout.md 57 行、create-style.md 97 行，加起来 311 行，比上一次快照的 601 行还少。父子相加从 1600 行降到 691 行，减了 57%。

所以这一轮做的不是"再拆一层"，而是压缩：路由判定回到 routing.md，共享契约合并，剩下的才按 kind 分。这提示上一节的审计标准要补一句——当一份第三层文件显得过大时，先问它是不是重复了别处已有的内容，再问要不要拆。拆分会增加导航跳数，去重不会。

反方向的 svg-pipeline.md 涨到 1255 行，成为整个 Skill 里最大的单个 Agent-facing 文件。它属于 scripts/docs/，即"读来理解接口"而非"共同承担"的那一类，所以变大本身不构成第二层的压力；但它确实是当前最该拿运行证据检查的对象——问题不是"1255 行太长"，而是"一次典型任务是否需要读完这 1255 行，还是只需要其中某几节"。

这也让上一次的结论要修正一半：当时把行数增长当作待审计信号，现在看，行数变化的方向和位置比绝对值更有信息量。工作流层在收缩（三条路由的权威文档现在分别是 376、380、171 行），脚本文档层在增长——这符合"判断下沉到工具、说明留给工具文档"的分工，不是失控。

是否继续下沉，仍应检查实际加载路径、路由之间共享的契约，以及是否出现上下文预算或执行错误。只有某一类内容确实只服务于单一路径且造成真实压力时，拆分才有收益。

2. 没有按原文建立正式任务评估集

原文把"在代表性任务上运行、观察失败点"放在开发流程的第一位。PPT Master 当前有静态 prompt 审计、路线内质量门、展示样例，以及 scripts/tests/ 下 18 个 unittest 模块，但没有把它们组织成 可重复运行的跨版本任务集，因此不能用统一成功率回答"补充的这段说明是否降低了失败率"。

这里要注意单元测试并不填补这个缺口，而且仓库把理由写进了规则。docs/rules/code-style.md §11 明确划了三条线：

测试只覆盖脚本，不覆盖提示词——"Tests for prompt text, workflow documents, or templates" 属于禁止项，那部分交给 prompt_audit.py 和人工评审；
没有 CI、没有 pytest、没有覆盖率、没有合并门，测试的定位是"下一个修复落地后能在几秒内重跑的回归网"；
绿色测试不算验证——改动转换行为仍必须在真实项目上跑一次冒烟并把输出贴出来，只声称"测试通过"的 PR 按未测试处理。

第三条尤其值得记下来：它把"测试通过"和"确实可用"显式解耦了。 这套 Skill 的核心产物是模型行为，而模型行为不在 unittest 的射程内；把单元测试的绿灯当成质量证据，恰恰是原文警告的那种自欺。

所以这仍是能力边界，不代表项目现在需要建立通用测试系统。只有要比较顺序生成与并行生成等具体策略，或出现可复现的行为回归时，才需要为该问题整理最小可重放任务；第六篇会继续区分展示样例与正式评估集。

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— 补上本文第十节指出的评估缺口（系统解读）。

← 返回 Anthropic 学习地图

Anthropic《Agent Skills》系统解读：渐进式披露与 PPT Master 的分层加载实践 ​

一、基本概念：Skill 是什么 ​

最小结构 ​

二、核心机制：渐进式披露的三个层级 ​

第一层：元数据 ​

第二层：SKILL.md 主体 ​

第三层及以后：按需导航的附加文件 ​

三层的成本模型 ​

三、为什么要包含可执行代码 ​

四、Skill 与 MCP 的关系 ​

五、编写方法：从评估开始，而不是从文档开始 ​

六、PPT Master 的三层结构实测 ​

第二层放了什么 ​

入口变厚的那 56 行装了什么 ​

七、PPT Master 的自创机制：路由作为独立的必读节点 ​

八、description 字段的实际写法 ​

九、代码的两种角色在 PPT Master 中的落地 ​

一个原文没有覆盖的用法 ​

十、对照原文校准三个差异 ​

1. 第三层文件是否过大，需要运行证据判断 ​

2. 没有按原文建立正式任务评估集 ​

3. 跨任务自我反思没有成为通用机制 ​

十一、我的理解：Skill 是把上下文预算显式化的手段 ​

十二、下一步 ​