Skill 是什么：渐进式披露的技艺

系列: SDD 系列 ·《搭建你自己的 AI 研发工作流》

期号: 第 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 --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 原理** → ④跨工具落地 → ⑤起逐个精讲

> 项目仍在持续迭代，欢迎试用与反馈。

::: center

????欢迎大家加入成都同盟????

:::


","createTime":1782133567,"ext":{"closeTextLink":0,"comment_ban":0,"description":"","focusRead":0},"favNum":0,"html":"","isOriginal":0,"likeNum":0,