03 · 一个 Skill 的解剖
一个 Skill 分三层：① 触发描述（很小，一直在）、② 正文说明书（被触发时才读）、③ 附件（用到才读）。这个"用多少读多少"的设计有个名字叫渐进式披露，它是 Skill 能存在的前提。
为什么必须分层
回到上下文窗口那张桌子：桌面就那么大。
如果每个 Skill 的全文都常驻，你装五个就把桌子占满了，正事没地方摆。所以设计成这样：
| 层 | 什么时候进上下文 | 大小 | 装什么 |
|---|---|---|---|
| ① 触发描述 | 一直在（开机就加载） | 极小，一两句话 | 名字 + 一句"我是干嘛的、什么时候用我" |
| ② 正文 | 被触发时才读 | 建议控制在几页之内 | 流程、规矩、模板、示例 |
| ③ 附件 | 正文提到、且真的需要时才读 | 不限 | 参考资料、长模板、脚本 |
结果就是：你可以装几十个 Skill，平时的代价只是几十行说明文字。
这个设计对你写作的直接影响
每一层的"读者"不同，写法也不同：
- 第 ① 层是写给"要不要用你"这个判断看的 → 关键词要全，要说清适用场景。
- 第 ② 层是写给"已经决定用你了，接下来怎么做"看的 → 只写它不知道的，别科普。
- 第 ③ 层是写给"需要查某个细节"看的 → 可以长，但要好检索。
第 ① 层：触发描述
以最标准化的那种形式为例，它是文件开头 --- 之间的两个字段：
---
name: meeting-notes
description: 把零散的会议记录整理成结构化纪要，输出结论、带责任人的待办、
遗留问题三块。当用户提供会议记录、会议纪要草稿、会议录音转写稿，
或要求整理纪要、提取会议待办时使用。
---name 是标识，description 是判断依据。这一格最关键，也最多人写坏，下一章整章讲它。
常见的字段约束（以这套标准为例，其他平台大同小异）：
| 字段 | 约束 |
|---|---|
name | 最长 64 个字符；只能用小写字母、数字和连字符；不能带 XML 标签；不能含保留词 |
description | 不能为空；最长 1024 个字符；不能带 XML 标签 |
具体数字会变
这些限制以你所用平台的官方文档为准。要记的不是数字，是形状：一个短标识 + 一段说明"是什么 + 什么时候用"。这个形状在各家都一样。
第 ② 层：正文
触发之后才被读进来的部分。一份好正文通常有这几节：
# 会议纪要整理
## 什么时候用
（简单情况可省略，复杂 Skill 建议写清适用与不适用）
## 流程
1. 通读材料，标出已定事项、待办、未定事项三类
2. 按下面的模板输出
3. 输出后对照"检查清单"自查一遍
## 输出模板
（直接给模子让它填空）
## 规则
- 只用用户给的材料
- 人名沿用原文称呼，不要补全
- 负责人或时间不明确的写「待确认」
- 前后矛盾的两个都列出来并标「原文冲突」
## 示例
输入：……（一段脏材料）
输出：……（对应的成品，含一处「待确认」）
## 检查清单
- [ ] 三个章节齐全
- [ ] 无原文之外的人名 / 日期 / 金额
- [ ] 每条待办有负责人与截止（或「待确认」）三条写作原则：
一、只写它不知道的。 别在 Skill 里科普"会议纪要是一种记录会议内容的文档"。它知道。你要写的是"我们这儿的纪要跟别人的不一样在哪"。
二、松紧要配得上任务。 这一条很实用：
| 任务性质 | 怎么写 |
|---|---|
| 多种做法都对，看情况判断 | 给方向："审阅时重点看逻辑矛盾和缺失信息" |
| 有偏好做法，但允许变通 | 给模板 + 说明可调："默认按这个结构，内容差异大时可增减章节" |
| 顺序不能错、错了代价大 | 写死步骤："严格按以下顺序，每步完成后确认再进入下一步" |
打个比方：独木桥两边是悬崖，就得给护栏；空地上怎么走都行，就别画格子。 该松的地方写太死，它会僵；该紧的地方写太松，它会飘。
三、控制长度。 正文太长会挤掉真正的材料。常见建议是把正文控制在几百行以内（一套标准里的说法是 500 行以下）；再长就该往第 ③ 层拆。
第 ③ 层：附件
正文放不下的东西，拆成同目录下的独立文件，正文里指过去：
meeting-notes/
├── SKILL.md 主说明（触发描述 + 流程 + 规则）
├── TEMPLATES.md 三种会议类型的完整模板
├── EXAMPLES.md 五组输入输出示例
└── STYLE.md 我们公司的措辞禁忌正文里这么引：
## 模板
常规项目会用下面的默认模板。
客户会 / 评审会 / 复盘会的专用模板见 [TEMPLATES.md](TEMPLATES.md)。
## 措辞
对外文档的措辞禁忌见 [STYLE.md](STYLE.md)。两条硬规矩：
引用只能一层深。 SKILL.md → TEMPLATES.md 可以；SKILL.md → A.md → B.md 不行——嵌套太深时它可能只扫一眼就走了，拿到的是残缺信息。所有附件都从主文件直接指过去。
长附件在开头放个目录。 超过一百行的参考文件，开头列一份小目录，这样它即使只扫开头，也知道里面有什么、值不值得读完。
附件可以是脚本（可选，不会编程可跳过）
有些平台允许 Skill 带可执行脚本。好处是：脚本的代码不进上下文，只有运行结果进——又省钱又比让它现写代码可靠。
适合固定的、容易出错的操作：格式校验、批量转换、数据核对。不会编程完全不影响前面所有内容。
一张图收口
渐进式披露：用多少读多少
- name
- description
- 几十个字
- 流程
- 输出模板
- 规则
- 示例 / 检查清单
- TEMPLATES.md
- EXAMPLES.md
- scripts/
你写 Skill 的功夫，应该按这个顺序分配：第 ① 层花的时间不比第 ② 层少。 因为第 ② 层写得再好，第 ① 层没写对，它一次都不会被用上。