Skill是什么：渐进式披露的艺术权威指南

2026-06-23阅读 0热度 0

skill

期号: 第 03 期

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

预计阅读: 8 分钟

--- > 将全部细节塞入一个文件，恰恰是这套工作流最违背直觉、也最具决定性的设计选择。 **本期导读** 上一期我们打通了工具链，观察到它自动生成了 `skills/` 目录。但“Skill”一词听起来抽象，它本质上究竟指什么？为何目录要设计成多层嵌套，而非一个单一的大提示词文件？本期，我们就深入剖析这个核心概念。 - Skill 的四层结构：`SKILL.md` / `references` / `assets` / `scripts` 各自承担的职责 - “全塞一个文件”为何导致AI成本飙升、决策迷失、维护困难 - 渐进式披露在真实Skill中的落地形态 - 这套方法今天就能迁移到你自己的长提示词上先给一个**30秒速成技巧**：下次编写长提示词时，不要再试图把全部细节塞进一段话。先拟定一个“目录页”，列出任务分解步骤；当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）**：主文件只负责导航，细节按需展开。 ![iShot_2026-06-22_21.05.33.jpg](https://developer.qcloudimg.com/http-sa ve/yehe-4011037/23bdd89277eec2854472e7437a0e3f9c.jpg) ---

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

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

一句话总结

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

动手挑战

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