Skill 是什么：渐进式披露的技艺
期号: 第 03 期
本期主角: Skill 结构 / 渐进式披露预计阅读: 8 分钟
---
> 不把所有细节塞进一个文件，是这套工作流最反直觉、也最关键的设计。
**本期导读**
- Skill 的四层结构：SKILL.md / references / assets / scripts 各自管什么- 为什么"全塞一个文件"会让 AI 又贵、又容易迷路、又难维护
- 渐进式披露在真实 skill 里长什么样- 这套思路你今天就能用在自己的长 prompt 上
**30 秒能用上**：下次写长 prompt 时，别再把所有细节塞进一段话。先写一个"目录页"，列出有哪些步骤；具体每步怎么做，等 AI 真正走到那一步再给它。这就是本期的核心思想——渐进式披露。
---
一、先回答一个朴素的问题：Skill 到底是什么
前两期我们跑通了工具，看到了它生成的 `skills/` 目录。但"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 一次读完不就行了？
但实践会狠狠教育你三件事。
### 1. 上下文是有成本的
AI 的上下文窗口是有限且昂贵的资源。如果每次执行一个简单步骤，都要先读完一份几千行、覆盖全流程所有边界情况的巨型文档，大量 token 被浪费在"此刻用不到的内容"上。上下文越臃肿，AI 越容易跑偏、遗忘关键约束。### 2. AI 会"迷路"当一份文档同时塞进"入口判断""提案撰写""失败恢复""schema 适配"几十个主题时，AI 很难判断"我现在到底该执行哪一段"。信息密度过高，反而降低了执行的准确率。
### 3. 维护会失控
全塞一个文件，意味着改任何一处都要在巨型文档里大海捞针，还容易牵一发而动全身。**解法就是渐进式披露（Progressive Disclosure）：主文件只负责导航，细节按需展开。**---## 三、看真实例子：主文件只做"导航"`opsx-dev-pipeline` 的 `SKILL.md` 主文件里，没有任何具体的执行步骤。它只放三样东西。**第一样：最小执行约束摘要**（无论走到哪一步都必须遵守的底线）> - 高风险决策必须显式确认；推荐项不等于自动代选。> - 除非用户明确选择终止，否则不得单方结束流程。
> - 详细的护栏、恢复规则、错误处理，以 `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` || … | … | … |
**第三样：权威来源地图**（遇到特定问题去哪查）
> - 跨阶段规则 / 恢复 / 降级：`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 --versiongit 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 原理** → ④跨工具落地 → ⑤起逐个精讲
> 项目仍在持续迭代，欢迎试用与反馈。::: center????欢迎大家加入成都同盟????
:::
","createTime":1782133567,"ext":{"closeTextLink":0,"comment_ban":0,"description":"","focusRead":0},"favNum":0,"html":"","isOriginal":0,"likeNum":0,
