期号: 第 03 期

本期主角: Skill 结构 / 渐进式披露

预计阅读: 8 分钟

--- > 不把所有细节塞进一个文件，是这套工作流最反直觉、也最关键的设计。 **本期导读** 在上一期我们跑通了工具，看到它生成了 `skills/` 目录。但“Skill”这个词听起来很玄，它本质上到底是什么？以及，为什么这个目录结构要设计成好几层，而不是一个大一统的提示词文件？这一期，我们就来拆开这个核心概念。 - Skill 的四层结构：`SKILL.md` / `references` / `assets` / `scripts` 各自管什么 - 为什么“全塞一个文件”会让 AI 又贵、又容易迷路、又难维护 - 渐进式披露在真实 skill 里长什么样 - 这套思路你今天就能用在自己的长 prompt 上 先给一个**30秒的速成技巧**：下次写长 prompt 时，别再试图把所有细节一股脑儿地塞进一段话。先写一个“目录页”，列出这件事分几步走；具体每一步怎么做，等 AI 真正走到那一步时再告诉它。这就是本期的核心——**渐进式披露**。 ---

一、先回答一个朴素的问题：Skill 到底是什么

一句话说清楚：**Skill 就是一份写给 AI 看的标准作业流程（SOP），并且是能被逐步执行的。** 它不是一段单纯的提示词，而是一个有组织的**目录结构**。我们可以看一个真实的例子，`opsx-dev-pipeline` 项目里的每个 skill 都长这样： ``` opsx-dev-pipeline/ ├── SKILL.md # 入口、导航、最小执行约束（必读、最短） ├── references/ # 分阶段的执行正文（按需加载） │ ├── phase-0-entrance.md │ ├── phase-1-propose.md │ └── ... ├── assets/ # 跨阶段的规则、护栏、恢复策略（查表用） │ ├── recovery-guardrails-appendix.md │ └── ... └── scripts/ # 可执行的 shell 工具 ├── dev-pipeline-preflight.sh └── ... ``` 这四个部分各司其职，分工非常明确： | 部分 | 职责 | 类比 | |---|---|---| | `SKILL.md` | 入口、导航、最小约束 | 一本书的**目录页** | | `references/` | 每个阶段的详细步骤 | 各个**章节** | | `assets/` | 跨阶段通用规则、护栏 | 书末的**附录/索引** | | `scripts/` | 确定性的工具调用 | 随书附带的**工具光盘** |

二、为什么不把所有内容写进一个文件？

这是整个设计里最反直觉、也最关键的一点。 直觉可能会告诉你：把所有规则、所有步骤、所有边界情况都写进一个大文件，让 AI 一次性读完，不是更省事吗？ 但实践下来，你会被三件事狠狠教育一番。 首先，**上下文是有成本的**。AI 的上下文窗口是有限的宝贵资源。如果每次执行一个简单步骤，都要先读完一份覆盖全流程所有边界的几千行巨型文档，大量 token 就白白浪费在了“此刻用不到的内容”上。上下文越臃肿，AI 就越容易跑偏，甚至遗忘关键约束。 其次，**AI 会“迷路”**。当一份文档同时塞进了“入口判断”、“提案撰写”、“失败恢复”、“schema 适配”等几十个主题时，AI 很难判断“我现在到底该执行哪一段”。信息密度过高，反而会降低执行的准确率。 最后，也是所有开发者都会头疼的——**维护会失控**。全塞一个文件，意味着改任何一处都要在巨型文档里大海捞针，还容易牵一发而动全身。 那解法是什么？就是**渐进式披露（Progressive Disclosure）**：主文件只负责导航，细节按需展开。  ---

三、看真实例子：主文件只做“导航”

在 `opsx-dev-pipeline` 这个技能里，`SKILL.md` 主文件里没有任何具体的执行步骤。它只放了三样东西。 **第一样：最小执行约束摘要**。无论 AI 走到哪一步，这些底线都必须遵守。 > - 高风险决策必须显式确认；推荐项不等于自动代选。 > - 除非用户明确选择终止，否则不得单方结束流程。 > - 详细的护栏、恢复规则、错误处理，以 `assets/recovery-guardrails-appendix.md` 为准。 **第二样：Phase 引用表**。这张表格告诉 AI，哪一步该去读哪个文件。 | Phase | 说明 | 引用文件 | |---|---|---| | 0 | 入口判断 | `references/phase-0-entrance.md` | | 1 | 提案编写 | `references/phase-1-propose.md` | | 2 | 提案应用 | `references/phase-2-apply.md` | | … | … | … | **第三样：权威来源地图**。AI 遇到特定问题时，知道去哪查。 > - 跨阶段规则 / 恢复 / 降级：`assets/recovery-guardrails-appendix.md` > - 决策点导航：`assets/decision-point-index.md` > - 脚本 I/O 契约：`assets/script-io-conventions.md` 注意，这份主文件甚至明确写了“阅读顺序”——先读约束摘要和引用表，再进入当前 Phase 的文件，遇到跨阶段问题才去查 assets。**它是在主动教 AI 如何节约自己的注意力。**

四、细节藏在哪：references 才是执行正文

当 AI 真正走到“入口判断”这一步时，它才会去读取 `references/phase-0-entrance.md`。这个文件里才是密密麻麻的可执行细节，比如： ```bash # 步骤 1：环境预检（在目标仓库根目录执行） bash /scripts/dev-pipeline-preflight.sh # 等价做法（无脚本时） openspec --version git rev-parse --is-inside-work-tree ``` 以及精细到边界的判定逻辑——比如“已有 change”该从哪个 Phase 续接： > - 制品未全部完成 → 从 Phase 1 继续 > - 制品已完成但任务未完成 → 从 Phase 2 继续 > - 任务完成且无审查报告 → 从 Phase 3 开始审查 > - 状态彼此冲突无法判断 → 保守回退到较早阶段，并让用户确认 这些细节重要吗？当然重要，但它们**只在执行到那一步时才有价值**。平时让它们在 references 里“睡觉”，需要时才唤醒——这就是渐进式披露的威力。

五、体量对比：复杂度被“折叠”了

如果把 `opsx-dev-pipeline` 这一个技能摊开来看，它的体量相当可观： - **8 个** phase 文件（`phase-0` 到 `phase-6`，外加一个修复回路 `phase-3.1`） - **8 个** assets（护栏附录、决策点索引、失败恢复索引、维护索引……） - **15 个** shell 脚本（预检、schema 识别、状态查询、归档、校验……） 如果把这些全压进一个文件，那将是一份几乎无法阅读、更无法让 AI 稳定执行的巨型文档。而通过渐进式披露，AI 每个时刻看到的，永远只是“此刻这一步需要的那一小块”。 **复杂度并没有消失，它只是被巧妙地折叠了起来，等待被按需展开。**

六、对你的启发：这套思路你今天就能用

你不需要从头造一个复杂的 CLI 工具才能用上这个思想。任何长 prompt、任何团队 SOP，都可以这样重构： 1. **写一个入口页**：列出“这件事分哪几步”“每步对应哪份说明”。 2. **拆分细节**：把每一步的具体做法拆成独立的小文件或小段落。 3. **沉淀通用规则**：把“无论哪步都要遵守的护栏”单独成篇，供查阅。 4. **让 AI 按需取用**：执行时只喂当前步骤所需的内容。 你会立刻收获三个好处：上下文更省、AI 更不容易跑偏、文档更好维护。 ---

一句话总结

好的 Skill 不靠“写得多”取胜，而靠**结构**取胜：主文件做导航、细节按需展开、护栏单独沉淀——把复杂度折叠起来，让 AI 每一刻只看它当下需要的那一小块。 ---

动手挑战

> 找出你手头一个最长、最复杂的 prompt（或一份团队 SOP 文档）。 > 试着把它拆成“**入口页 + 按需引用的细节**”两层： > - 入口页：3–8 行，只写“有哪些步骤、每步去看哪里”。 > - 细节：每步单独一段或一个文件。 > > 然后对比一下，拆分前后，AI 执行同一个任务时的准确率和你给它的上下文长度，分别有什么变化？ --- **下期预告**：第 04 期《一套模板四处落地：适配器与资产清单》。我们会拆解 `tools.json` 和 `manifest.ts`——看它如何用配置驱动，把同一套技能内容，自动落地到 Claude Code、Cursor、Codex 四种工具各自的目录里。 > 系列导航：①立题 → ②上手 → **③Skill 原理** → ④跨工具落地 → ⑤起逐个精讲 > 项目仍在持续迭代，欢迎试用与反馈。