理解渐进式披露（progressive disclosure），是写好 skill 的”第一性原理”
一个常见错觉
很多人第一次接触 skill 时，会把它理解成”一条保存下来的复杂提示词”。这个理解并不算错，但它会让我们写出糟糕的 skill——因为它忽略了 skill 真正的本质：skill 是一个文件夹，文件夹本身就是上下文工程（context engineering）。
Anthropic 的 Claude Code 团队在内部跑了几百个 skill 之后，总结的原话是：
原文引用You should think of the entire file system as a form of context engineering and progressive disclosure.
渐进式披露（progressive disclosure）的三层加载
一个 agent 在启动时，可能已经装了几十个甚至上百个 skill。如果把每个 skill 的完整内容都塞进上下文，上下文窗口有可能会立刻爆掉。所以 skill 的设计者做了一件非常聪明的事情：把信息分三层，按需加载。
第一层 · 元数据层（~100 tokens，启动即加载）
┌──────────────────────────────────────┐
│ 每个 skill 只有 name + description │
│ 进入系统提示词 │
│ → agent 凭它判断"这个 skill 和我 │
│ 当前任务有关吗？" │
└──────────────────────────────────────┘
↓ 命中才触发
第二层 · 指令层（SKILL.md 正文，触发时加载）
┌──────────────────────────────────────┐
│ SKILL.md 的完整 Markdown 正文 │
│ 被读入上下文 │
│ 建议 < 5000 tokens │
└──────────────────────────────────────┘
↓ 正文里引用了才加载
第三层 · 资源层（references / scripts / assets）
┌──────────────────────────────────────┐
│ 被 SKILL.md 显式引用的文件 │
│ 按需读取（read on demand） │
│ 这一层的容量"实际上无上限" │
└──────────────────────────────────────┘关键推论：我们在 skill 里写的每一个字都不是平等的。description 里的内容会一直占用上下文，且对所有会话都生效；SKILL.md 正文里的内容只在技能触发后占用上下文；references 里的内容只在被引用时占用上下文。因此，写得”全”，不如放得”对”。
渐进式披露（progressive disclosure）决定了你怎么写 skill
- description 是触发器，而不是摘要：它是写给模型看的，告诉模型”什么时候该唤醒我”，里面要包含用户可能提到的关键词。如果写成”帮我处理 PDF”这种模糊描述，skill 装了等于没装。
- SKILL.md 是路由器，而不是知识仓库：官方规范的建议是，主文件要保持精简，详细资料要拆进
references/，正文里使用链接指过去。 - 脚本优于文字描述：能用 20 行 Python 完成的事，不要写 200 字的自然语言让模型每次重新理解（还有可能每次理解的都不一样）。脚本可以被执行，具备确定性，甚至脚本本地执行还不占用上下文。
检验一下
检索练习 · 不看上文，凭记忆回答
一个 skill 启动时，agent 的系统提示词里，立即加载的是哪一层？
检索练习 · 机制理解
我们写了一个 skill，正文里有 3000 字详细的 API 字段说明。更好的做法是什么？
检索练习 · 写出判断
description 字段的本质是什么？
先在心里用一句话回答，再点开对照。
本课一手来源
大伙如果想深挖一层，读这篇：Anthropic · Equipping agents for the real world with Agent Skills
这是 skill 机制的原始设计文档，本课的三层加载图（沈剑用AI画的，虽然有点丑，表达清楚就行，将就着看吧）就来自它。20 分钟阅读量，值得（图非常精美）。
渐进式披露（progressive disclosure）速查卡
写 skill 时贴在手边的一张纸 · 对应第 1 课
三层加载模型
层 1 元数据 name + description 启动即加载 ~100 tok
层 2 正文 SKILL.md body 触发才加载 <5000 tok
层 3 资源 references/scripts/ 链接才加载 无上限三个位置的写法判断
- description= 触发器，写给模型。回答”什么时候唤醒我”，含用户关键词。它永远在线，内容对所有会话都生效。
- SKILL.md 正文= 路由器。步骤、判断规则、指向第三层的链接。细节不往这放。
- references/= 知识仓库。完整 API 说明、领域知识、模板格式——必须被正文显式链接才会被加载。
- scripts/= 确定性执行。能写成代码的事不写散文；脚本可执行，不占上下文。
- assets/= 产出物料。模板、样板文件，被复制进最终产出，不被读入上下文。
一句话记忆
口诀触发看 description，干活看正文，细节住 references，重复劳动写成脚本。
官方规范要点（agentskills.io）
name：1-64 字符，小写字母+数字+连字符，必须与父目录同名description：1-1024 字符，必填，写清 what + when- 可选：
license、compatibility、metadata、allowed-tools（实验性） - 正文无格式限制——但”长则拆”是官方建议