让 Skill 真正好用：渐进加载与文件分工
上一篇文章写出了第一个 Skill：一个文件夹、一个 SKILL.md，name 和 description 写准，正文是步骤加通过标准。跑起来之后，下一个问题很快就会出现：步骤越加越多，SKILL.md 越写越长，Agent 每次触发都要从头读到尾，又慢又费 token，重点还越来越难找。
先把结论放在前面：Skill 的好用程度，取决于 Agent 每次只读到它当时需要的那部分。 做到这一点的办法有两个：渐进加载，和文件分工。前者决定读多少，后者决定东西放哪。
一、渐进加载：三层，越往下读得越少
Agent 读一个 Skill，分三层，一层比一层晚，一层比一层少：
- 第一层是元数据。 就是 SKILL.md 顶部的 name 和 description，大概 100 个 token。Agent 启动时就全读了，靠这一层判断哪个 Skill 该触发。这一层越短越准越好，上一篇已经讲过。
- 第二层是正文。 只有 Skill 被触发了，Agent 才会读正文。一般控制在 5000 个 token、500 行以内。正文只写步骤和通过标准，不写长篇细节。
- 第三层是附件。 scripts、references、assets 里的文件，只有正文明确引用到，Agent 才会在执行到那一步时去读。用不上的，一次都不读。
可以把它想成一本书：元数据是目录，告诉你这本书讲什么、什么时候翻它；正文是章节，告诉你按什么顺序做什么；附件是附录，平时不看，查到某一条再翻。目录常驻，章节按需，附录随查随用——这就是渐进加载。
这里有个常见的误解：以为把所有东西都写进正文，Agent 掌握得更全。恰恰相反。正文越长，Agent 越难抓住重点，也越容易在不重要的细节上浪费 token。 该拆出去的东西留在正文里，不是更全，是更乱。
二、文件分工：三个文件夹，各干各的
一个 Skill 的文件夹，完整长这样：
publish-checklist/
SKILL.md
scripts/
check-links.py
references/
link-check-rules.md
assets/
report-template.md
三个文件夹的分工，按一句话区分：
- scripts 放能跑的代码。 步骤里凡是每次都要机械执行的操作，比如逐一打开链接、批量检查图片是否缺失，就写成脚本。脚本的好处是结果稳定：人跑十次可能漏一次，脚本跑十次结果都一样。正文里只留一句话：“运行 scripts/check-links.py，逐一检查文中的链接”，具体怎么检查，让脚本去做。
- references 放长篇的资料。 详细的规则、例外情况、背景说明，比如“哪些链接不用检查”“图片缺失的几种常见原因”，放进 references。正文里需要的时候写一句“细节见 references/link-check-rules.md”，Agent 查到那一步才会去读，平时不占正文的篇幅。
- assets 放模板和素材。 检查完要输出的报告格式、固定措辞的表格模板，放进 assets。Agent 对照模板填结果，输出格式每次都一致，不用每回重新想。
分工的判断标准很简单：正文只留判断和步骤。 需要 Agent 动脑筋、做判断的，留在正文；能交给代码跑的，进 scripts；很长但很少用的，进 references；照着抄的，进 assets。
三、什么时候拆，什么时候不拆
不是每个 Skill 一上来就要拆成四个文件夹。拆，有三个信号：
- 正文超过 500 行了。 读起来已经费劲，重点埋在长篇里，说明有些内容该搬出去了。
- 某一步每次都要跑同一条命令。 比如每次检查都要手动打开十几个链接，这种重复机械的操作，写成脚本最划算。
- 某段细节很长，但很少用到。 比如例外清单有三页，但十次里只用上一次，这种内容放进 references，正文只留一句话引用它。
反过来，以下两种情况先别拆：
- 第一版还没跑顺。 流程本身还在改，今天加一步、明天删一步，这时候拆文件只会让改动更麻烦。先把流程跑顺，拆是第二步的事。
- 拆完要来回翻三个文件才能看懂。 如果一个步骤的理解需要同时打开正文、脚本和参考资料，说明拆过头了。拆的目的是让每一部分更清楚，不是让整体更难拼起来。
记住这个顺序：先写短的正文，跑几次，痛点出现再拆。 拆是为了解决具体的问题，不是为了让文件夹看起来完整。
四、动手：把上一篇的 publish-checklist 拆一次
拿上一篇的发文章检查 Skill 举例。拆之前，正文里有五步，其中“逐一打开链接”这一步最花时间，拆完之后是这样：
publish-checklist/
SKILL.md
scripts/
check-links.py
references/
link-check-rules.md
assets/
report-template.md
拆完的 SKILL.md 正文，变短了，但步骤一点没少：
---
name: publish-checklist
description: 发文章前的检查流程，在用户说要发布文章、或者要检查一篇文章能不能发时使用。
---
# 发文章前检查
按以下步骤逐一检查，每条都要给出通过或不通过的结果，不要跳过任何一条。
1. 核对标题有没有错别字，标题和正文内容是否一致。
2. 检查描述有没有写，描述是否准确概括了文章内容。
3. 核对分类和标签是否符合这篇文章的主题。
4. 运行 scripts/check-links.py 检查文中的链接；有一条打不开就列出来。哪些链接不用检查，见 references/link-check-rules.md。
5. 确认图片都已上传、没有缺失，图片说明没有错位。
检查完成后，按 assets/report-template.md 的格式汇总哪条通过、哪条不通过。最后发不发，由用户决定，不要直接发布。
注意第四步的写法：正文里只写“做什么”和“用什么”，“怎么做”和“例外”都指到附件里。 Agent 执行到这一步，才去读脚本和规则；前三步完全不受影响。整个 Skill 还是一个意思，但每次触发要读的内容少了一大截。
写脚本和参考资料时，各有一条纪律。脚本要写清楚输入和输出：输入是什么、输出是什么、失败了怎么报错，别让 Agent 猜。参考资料要写清楚什么时候查：开头就写“在第几步、遇到什么情况时读这份资料”，别让 Agent 在不需要的时候把它翻出来。
练一次：给你的第一个 Skill 做一次拆分
拿上一篇练手写出的那个 Skill，照下面四步拆一次：
- 把它的 SKILL.md 从头读一遍，圈出最长、最机械、最少用的三处。
- 机械重复的那一处，写成 scripts 里的一个小脚本，正文只留一句“运行它”。
- 很长但很少用的那一处，挪进 references，正文只留一句“细节见这里”。
- 如果检查完要输出固定格式的结果，把格式写成 assets 里的一个模板。
拆完之后再读一遍正文：如果正文变短了，步骤没少，每一步还是一眼能看懂，这次拆分就成功了。如果正文反而更难懂了，把刚拆出去的东西搬回来，等流程再跑顺一点再拆。
下一篇，我们讲一个 Skill 怎么跨工具复用：在一个工具里写好，到别的工具里接着用，同一套做法不用每个地方重写一遍。
