永无岛
你将学到
- 用"图书馆"类比理解渐进式披露（progressive disclosure）。
- 看清 Skill 的三层加载：metadata → instructions → resources。
- 理解 description 字段为什么决定一切。
- 知道为什么 Skill 永远不会"塞爆"AI 的脑子。
- 了解 Skill 和"长 Prompt"在原理上的区别。
你需要准备
- 一杯水。这一章是原理章，不需要打开电脑。
- 5 分钟连贯的阅读时间。
一、先抛出一个困惑
第二章你跑了一个简单 Skill。但你脑子里大概有这些问题：
- 我开了 Skills 总开关后，xlsx、docx、pptx、pdf 4 个 Skill 都默认加载了。如果我装到 100 个 Skill，AI 不会直接被"撑爆"吗？
- 为什么我说"帮我处理这份 Excel"它就知道用 xlsx Skill，而不是 pptx Skill？它是怎么挑的？
- 为什么我那个 hello-skillbook Skill 我说"测试 skillbook"它能召唤；说"你好"它就不召唤？
这三个问题，是 Skill 的全部秘密。
我们一个一个回答。
二、用"图书馆"类比理解 Skill 的工作流
想象一座小镇图书馆。它的读者（你）走进去借书：
0. 进门
读者走到柜台说："我想找一本书。"
馆员（Claude 大模型）问："想找什么主题的？"
1. 看书目卡片（metadata）
馆员先去翻书目卡片柜。每本书在卡片上只有最基本信息：
- 书名（name）
- 一句话简介（description）
馆员根据卡片快速判断"这本书可能跟读者要的有关"。10 秒内扫过 100 张卡片不费力。
2. 把书取出来读目录和正文（instructions）
馆员锁定一本可能合适的书后，跑去书架取下来翻正文——这才是真的内容，几千字。
读完正文，他知道"这本书具体怎么用"。
3. 按需翻附录（resources）
如果这本书还有附带的"参考资料""图表集""音频材料"，馆员只在用得到的时候才翻。比如读者问到"第 30 页那张图能不能帮我打印一份"，他才去翻图集。
把这个图书馆翻译回 Skill 的世界：
| 图书馆 | Skill |
|---|---|
| 一本书 | 一个 Skill 文件夹 |
| 书目卡片 | YAML frontmatter 里的 name + description |
| 正文 | SKILL.md 主体内容（Markdown 指令） |
| 附录 / 图集 / 音频 | scripts/、templates/、references/、assets/ 目录 |
| 馆员 | Claude 大模型 |
| 读者 | 你 |
| 进门时的对话 | 你给 Claude 的提示词 |
这套机制有个学名：Progressive Disclosure（渐进式披露）。
白话解释：渐进式披露 = "先看一眼，需要再细看，需要再翻配套资料"。
三、Skill 的三层加载（Three-Tier Loading）
按 Anthropic 官方文档：
Level 1: Metadata (~100 tokens) 始终常驻
Level 2: Instructions (<5,000 tokens) 触发时才加载
Level 3: Resources (无上限) 按需加载
每一层都对应文件里的一段：
Level 1 —— Metadata（约 100 token，始终常驻）
就是 SKILL.md 顶部的 YAML frontmatter，例如：
---
name: weekly-report
description: 帮用户按公司四段格式（完成/计划/风险/求助）写周报。当用户提到"周报""周一汇报""this week summary"时触发。
---
这两行就是"书目卡片"。Claude 在每次对话开始时把所有 Skill 的 metadata 都加载到内存里。
每个 Skill 大约只占 100 token——这是为什么你装 100 个 Skill 也不会"撑爆 AI 的脑子"。
白话解释：100 个 Skill × 100 token = 1 万 token。Claude 4.5 的上下文是 20 万 token，1 万只占 5%，完全无感。
Level 2 —— Instructions（小于 5000 token，触发时加载）
只有当 Claude 决定"我要用这个 Skill"时，它才会去读 SKILL.md 的主体内容——也就是 frontmatter 之后的所有 Markdown。
这部分通常是几千字的工作流说明：
# 周报生成器
## 第一步：收集数据
1. 从 Notion 拉…
2. 从 GitHub 拉…
## 第二步：写四段
- 本周完成…
- 下周计划…
## 第三步：风格
- 句句给数字…
这部分官方建议不超过 5000 token——大致 2500–3000 个汉字。超过这个长度，Skill 就开始变"重"，会拖慢 Claude 的反应。
Level 3 —— Resources（无上限，按需加载）
如果 Skill 文件夹里还有别的文件——脚本、模板、参考文档、图片——它们只在需要时才被加载。
举个例子：
weekly-report/
├── SKILL.md
├── references/
│ ├── notion-fields.md # 1 万字，介绍 Notion 字段
│ └── tone-guide.md # 5000 字，公司语气规范
├── scripts/
│ └── fetch_notion.py # Python 脚本
└── templates/
└── weekly.docx # 公司模板
- 当 Claude 需要拉 Notion 数据时，才会去打开
fetch_notion.py。 - 当 Claude 需要参考语气时，才会去打开
tone-guide.md。 - 当 Claude 需要套模板时，才会去打开
weekly.docx。
平时这些文件就静静躺着，不占任何 token。
白话解释：Resources 就像图书馆里的"参考资料区"——读者不主动问到，馆员不会主动翻给你看。
四、为什么这套机制是"革命性"的
第一章我们对比过 Skill 和"长 Prompt"。这里更深入一点：
长 Prompt 的问题
你可能想过："那我自己写一份超长的 system prompt，把所有任务说清楚不就行了？"
不行。原因有三个：
- token 消耗炸裂：你的 system prompt 在每次对话里都会被完整加载。如果你想覆盖 100 种工作场景，那就是 100 × 几千字 = 几十万 token——超出几乎所有模型的上下文。
- AI 注意力被稀释：研究表明，长 prompt 里 AI 容易"漏看"细节。你藏在第 8000 字处的"重要规则"它看不到。
- 维护噩梦：100 种场景写在一份文件里，你哪天想改"周报格式"得翻半天。
Skill 的解法
Skill 用渐进式披露把这三个问题全解决了：
- token 消耗可控：metadata 只占 100 token，instructions 按需加载。
- AI 注意力集中：当一个 Skill 被触发，Claude 只看那一份 5000 token 的指令——注意力 100% 在这个任务上。
- 维护清晰：100 个场景对应 100 个 Skill 文件夹，你想改哪个就开哪个。
这就是为什么 Anthropic 把 Skill 称作 "the future of AI applications"——它把过去靠"长 prompt + 反复试错"才能勉强解决的事，变成了一个工程问题。
五、Skill 是"怎么被召唤"的——description 是灵魂
回到第二章那个问题："Claude 是怎么挑出 xlsx Skill 的？"
答案就在每个 Skill 的 description 字段里。
我们看一下 xlsx Skill（Anthropic 官方版）的 description（简化版）：
description: >
Read, analyze, and modify Excel (.xlsx) files. Use this skill when the user
asks about spreadsheets, Excel files, .xlsx files, data analysis on tabular
data, calculating sums/averages/pivots, adding/removing rows or columns,
formatting cells, or generating Excel reports.
注意这段描述：
- 它列出了所有触发关键词：spreadsheet、Excel、.xlsx、data analysis、tabular、pivot、rows、columns、cells、reports……
- 它列出了适用动作：read、analyze、modify、calculate、add、remove、format、generate……
当你说"帮我处理这份 Excel"，Claude 在毫秒级匹配你说的话和所有 Skill 的 description——发现 "Excel" 这个词高度对应 xlsx Skill 的描述，于是召唤它。
如果你说"帮我画一张趋势图"——里面没有 "Excel"，但有 "图"，Claude 可能会判断"这跟图表生成有关"，仍然有可能触发 xlsx（因为它里面也提到 charts）。
如果你说"你好"——所有 Skill 描述里都没这个词，Claude 一个都不召唤，按聊天模式走。
description 的 6 个金标准
写好 description 是 Skill 成功的 80%。Anthropic 官方推荐：
- 直接说"做什么"：开头 1–2 句话讲清这个 Skill 解决什么问题。
- 列触发关键词：用户可能用的中英文词汇都要写进去。比如"周报""weekly report""周一汇报""week summary"。
- 覆盖典型场景：用户在什么场合会用到这个 Skill？写出来。
- 避免歧义：不要写"通用文档处理 Skill"——这种描述会跟所有 Skill 冲突，AI 不知道选哪个。
- 控制长度：≤ 1024 字符（约 350 中文）。太短不够触发，太长拖慢匹配。
- 避免过度承诺：不要写"能解决所有 PPT 问题"——AI 真的会按这个标准召唤它，结果做不到就翻车。
第八章我们会带你按这 6 条原则写出第一份合格的 description。
六、为什么有的 Skill"叫不来"
理解了上面机制，"我的 Skill 怎么没被触发"这个问题就有答案了：
原因 1：description 太笼统
❌ 反例：
description: A helpful skill.
这描述跟没写一样，Claude 没法判断什么时候该用。
✅ 正例：
description: Help users write weekly status reports in the company's four-section format (Done / Plan / Risks / Asks). Use when user mentions "周报", "weekly report", "周一汇报", "week summary", or asks for a status update.
原因 2：用户的提示词里没有任何触发关键词
如果你写的 Skill description 里只有"周报""weekly report"两个词，但你跟 Claude 说："帮我汇总一下这周做了啥"——里面一个关键词都没命中，Skill 不会被召唤。
解决：要么把更多说法加到 description（"汇总周工作""this week summary"），要么改你自己的口头禅（直接说"帮我写周报"）。
原因 3：和别的 Skill 撞描述
如果你装了两个 Skill，描述长得很像：
- Skill A: "Generate PowerPoint presentations from data."
- Skill B: "Create slide decks based on tabular input."
两个都跟"PPT + 数据"有关，Claude 可能会"两个都想用又拿不定主意"，最后表现奇怪。
解决：让两个 Skill 的描述明确各自专属场景。比如 A 加上"专注英文工作汇报"，B 加上"专注中文销售提案"。
原因 4：Skill 文件夹位置不对
Claude 只会扫描特定目录：
- Claude.ai 网页版：你在 Settings 里上传的 Skill。
- Claude Desktop：上传后保存到云端。
- Claude Code：
~/.claude/skills/全局，或当前项目下的.claude/skills/。
放别的地方它根本看不到。
原因 5：YAML 写错了
YAML 对格式很严格。常见错误：
---
name:weekly-report # ❌ 冒号后面没空格
description: 我的描述 # ✅ 这样是对的
---
或者：
---
name: weekly report # ❌ name 不能有空格
---
name 必须是 kebab-case：小写字母 + 短横线，比如 weekly-report、hello-skillbook、pdf-toc-builder。
七、把 Skill 工作流画一张完整的图
你说一句话 Claude 大模型 执行结果
│ │ ▲
│ "帮我读这份 Excel" │ │
├───────────────────────────►│ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ 1. 在 metadata 库 │ │
│ │ 匹配触发关键词 │ │
│ │ 命中: xlsx │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ 2. 加载 xlsx 的 │ │
│ │ SKILL.md 主体 │ │
│ │ (~3000 token) │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ 3. 按指令执行 │ │
│ │ - 写 Python 代码 │ │
│ │ - 在沙箱里跑 │ │
│ │ - 必要时去翻 │ │
│ │ references/ │ │
│ │ 或 templates/ │ │
│ └─────────┬─────────┘ │
│ │ │
│ └────────────────────────────────┘
│
│ 返回: 处理后的 .xlsx 文件 + 一段总结
◄────────────────────────────
八、Skill 的"沙箱"——脚本到底在哪跑
最后讲一件你需要知道的事：Skill 里那些 Python 脚本到底跑在哪？
简单说：
- Claude.ai 网页版 / Desktop：跑在 Anthropic 的云端沙箱里（每个对话独立、隔离、用完销毁）。沙箱可以联网（受限）、可以读你上传的文件、可以输出新文件。
- Claude Code：跑在你本地电脑上。这意味着 Skill 能力更强（能读你硬盘里的任何文件、能跑系统命令），但也更敏感（恶意 Skill 可能伤害你的系统）。
关键安全准则（第十章详讲）：
- 网页版 / Desktop 的 Skill 风险相对低——沙箱有边界。
- Code 里运行的 Skill 必须只装来源可信的。
九、本章一图回顾
+---------------------------------------------------------+
| Agent Skill 三层架构 |
+---------------------------------------------------------+
| |
| Level 1: Metadata ~100 tokens, 始终常驻 |
| ┌──────────────────────────────────┐ |
| │ name: weekly-report │ |
| │ description: ...触发关键词... │ |
| └──────────────────────────────────┘ |
| ▲ |
| │ Claude 用它"匹配该不该召唤" |
| |
| Level 2: Instructions <5000 tokens, 触发时加载 |
| ┌──────────────────────────────────┐ |
| │ # 第一步：收集数据 │ |
| │ # 第二步：按四段写 │ |
| │ # 第三步：风格规范 │ |
| └──────────────────────────────────┘ |
| ▲ |
| │ Claude 用它"知道怎么干" |
| |
| Level 3: Resources 无上限, 按需加载 |
| ┌──────────────────────────────────┐ |
| │ scripts/ templates/ │ |
| │ references/ assets/ │ |
| └──────────────────────────────────┘ |
| ▲ |
| │ Claude 用它"真正动手做事" |
+---------------------------------------------------------+
灵魂: description
最容易踩坑: name 写法 / description 太笼统 / 触发词缺失
给你 3 句话提醒
- 学 Skill 的"原理"不是为了炫技，是为了让你写的每一个 Skill 都能被真正召唤。
- 一个被"叫不动"的 Skill = 一个不存在的 Skill。description 写法决定一切。
- 渐进式披露不是奇技淫巧，它是 AI 工程化的转折点。理解这件事，你就理解了"AI 不是聊天框，是一个能装 1000 件能力的容器"。
下一章预告
下一章 第四章 从官方 Skill 开始，我们要正式动手了。
我会带你完整跑通 Anthropic 官方 4 个最常用的 Skill：xlsx、docx、pptx、pdf——每一个都有 1 个完整实战。最后做一个综合实战：从一份 Excel 数据，一句话生成完整的 12 页 PPT。
做完那一章，你就掌握了"用 Skill 替代 80% 文档操作"的能力。
走，进第四章。