
系列: 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）：主文件只负责导航，细节按需展开。**

![iShot_2026-06-22_21.05.33.jpg](https://developer.qcloudimg.com/http-save/yehe-4011037/23bdd89277eec2854472e7437a0e3f9c.jpg)

---

## 三、看真实例子：主文件只做"导航"

`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 <SKILL_ROOT>/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  
👇👇👇👇欢迎大家加入成都同盟👇👇👇👇
:::
![图片](https://developer.qcloudimg.com/http-save/yehe-4011037/e06b5bb1907515a089943d5c51f095f4.webp)


系列: SDD 系列 ·《搭建你自己的 AI 研发工作流》期号: 第 03 期本期主角: Skill 结构 / 渐进式披露预计阅读: 8 分钟

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

**本期导读**
- Skill 的四层结构：SKILL.md / references / assets / scripts 各自管什么
- 为什么"全塞一个文件"会让 AI 又贵、又容易迷路、又难维护
- 渐进式披露在真实 skill 里长什么样
- 这套思路你今天就能用在自己的长 prompt 上

人工智能

开发工具

学习如何搭建高效AI研发工作流，掌握Skill四层结构设计，通过渐进式披露优化长prompt，让AI执行更精准、上下文更节省。拆分细节、沉淀规则，提升文档可维护性，今天就能实践这套方法。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Skill 是什么：渐进式披露的艺术-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐