第 8 章 Chapter Outline：Skills 与可复用能力

本文件是正文写作蓝图。Skill Contract、跨概念边界、生命周期、测试矩阵和 Markdown 审查案例都是本书的工程模型；它们不是 Agent Skills 的完整 schema，也不是 Claude Code、ChatGPT、Codex 或某个 Plugin 的共同实现。正文写作当天必须重新核验 REF-025 至 REF-027 的产品行为；REF-024 只能证明 Agent Skills Specification 所定义的工件与字段范围。

章节契约

读者完成后的能力： 能把一个窄而重复的任务从 Prompt 片段整理成可维护的 Skill Contract；能明确其触发条件、输入、前置条件、所需工具类别、最大副作用、输出、失败表示、证据、维护者和版本；能用固定案例验证选择、阻塞与弃用条件，并说明为什么 Contract 不能授予真实权限。

前置知识： 已完成第 5 章，理解项目规则、任务、资料和输出契约不能混为一层指令；已完成第 6 章，理解进入本次任务的 Context Packet 需要来源、范围和预算。读者能阅读 Markdown、目录结构、简单 YAML front matter、对象和断言。

章节边界： 本章不重新定义一次性 Prompt 的装配原则（第 5 章），不决定工作记忆或长期记忆的读写（第 7 章），不实现规划、检查点、重试或状态恢复（第 9、10 章），不定义 Tool 的协议或副作用接口（第 11 章），不实现 Sandbox、凭证、权限或审计（第 12、14 章），也不描述任何平台的安装、发现优先级、管理后台或插件市场。Skill 只表达可复用任务的说明和支持资源；它不等于授权、执行器、工作流状态机或产品打包格式。

小节蓝图

1. 从反复粘贴 Prompt 到可维护的 Skill

• 读者问题： 为什么一段反复复制、看似有效的审查提示，仍然难以称为团队可复用的能力？
• 叙述任务： 以原创教学场景开场：三位维护者各自复制“审查 Markdown 章节”的提示，得到不同审查范围、不同输出格式和无法追溯的修改建议。先把问题定位在触发、输入、失败表示与验证缺失，而非把问题归因于模型“记忆不足”。说明 Prompt 可成为 Skill 的一部分，但一次请求文本本身没有自动获得版本、发现、边界或验收条件。
• 证据边界： Prompt 与 Skill 的职责划分、教学场景和问题诊断都是本书模型。REF-026 只能支持 ChatGPT 将 Skill 描述为可复用、可共享工作流并可包含说明、示例和代码；不能外推为所有系统的定义或自动执行保证。
• 计划工件： “复制提示 / Skill Contract”对照表，按任务名称、触发、输入、失败输出、证据、版本、维护者和副作用列出可观察差异。
• 验证： 给定两份语义相近但输出要求不同的审查提示，读者能指出它们不能安全互换的契约项，并写出最小的统一任务名和不可选择条件。
• 过渡： 发现缺口后，下一步不是写更长的总提示，而是确定一个 Skill 最少由哪些说明与资源组成。

2. 最小工件与渐进加载：让能力可发现，但不把所有内容塞进上下文

• 读者问题： 一个 Skill 最小需要哪些内容，怎样让 Agent 或人类知道何时值得进一步读取？
• 叙述任务： 从目录而不是“万能提示词”解释本书的最小工件：简短可发现描述、正文工作说明与按需支持资源。再以“发现 → 判断相关性 → 读取正文 → 按需读取脚本或参考资料”的顺序说明渐进加载的目标是控制上下文负担与审查范围，而不是保证自动选择正确。
• 证据边界： REF-024 定义至少含 SKILL.md 的目录、YAML front matter、Markdown 正文、必填的 name 与 description，以及可选的 scripts/、references/、assets/；REF-025 仅在 Claude Code 语境中说明正文按使用时加载。目录分层、加载判定和“最小工件”取舍是本书模型，不能推断其他产品采用相同路径或字段。
• 计划工件： Skill 包分层图和资源责任表：元数据回答“是否候选”，正文回答“怎样完成”，脚本/参考/资产回答“需要时到哪里取”；另列出每层不能证明的事项。
• 验证： 读者能为 Markdown 审查任务拆分出一段用于发现的描述、正文必需步骤和两个按需资源；并能说明为什么只读到描述时不能执行，也不能推断权限。
• 过渡： 目录让能力可发现，但真正可维护的边界必须写入一个可审查的 Contract。

3. Skill Contract：把选择、输入、结果和证据写成可检查接口

• 读者问题： 什么信息缺失时，一个 Skill 即使被选中也不应执行？
• 叙述任务： 定义本书 Skill Contract 的九项：解决的问题、触发与排除条件、输入、前置条件、工具类别与副作用上限、成功输出、失败或阻塞输出、验证证据、维护与版本。用“审查指定章节”对比一份只说“检查质量”的描述与一份能指出章节路径、规则版本、引用登记、只读边界和结构化发现的 Contract。
• 证据边界： 此 Contract、字段名、状态名和默认动作全部是本书设计，不是任何来源的 schema。REF-024 的 allowed-tools 为实验性声明；无论该字段或本书 Contract 如何书写，都不能作为工具授权、Sandbox 规则、凭证或源系统 ACL 的证明。
• 计划工件： Contract 模板与字段责任表：字段回答的问题、缺失时的动作、允许得出的结论和禁止得出的结论。模板会复用 templates/skill-template.md，但正文不把模板示例写成真实产品配置。
• 验证： 五份候选任务中，缺章节路径、缺审查范围、要求写入却无批准、无失败表示或无验证证据的项必须分别输出 blocked 或 requires_approval，而不是补充猜测后继续。
• 过渡： Contract 解决“怎么做”，但尚未说明“何时选它”；选择与前置检查需要独立于模型的主观偏好。

4. 发现、选择与前置检查：相关性不是许可，描述也不是执行证据

• 读者问题： 当多个 Skill 都看似相关时，系统或维护者如何避免选择过宽、过期或不适用的能力？
• 叙述任务： 建立本书选择链：注册或可发现目录 → 描述匹配 → 排除条件 → 输入与环境前置检查 → 明确的选择或阻塞理由。说明 description 只能提供候选线索；选择后仍需读取 Contract、检查任务范围与版本，并保留“为什么未选择”的证据。对高风险或外部副作用任务，要求显式调用或人工批准，而不是仅凭自动发现。
• 证据边界： REF-025 对 Claude Code 的自动相关性使用、目录位置和优先级只限 Claude Code；REF-026 对 ChatGPT 的安装后自动使用说明也只限其产品范围。注册表、匹配规则、排除条件、分流动作和高风险升级都是本书模型，不能描述为产品内部调度器或通用安全机制。
• 计划工件： 选择决策表：候选名称、任务匹配理由、排除条件、缺失前置条件、动作、证据。包含“同样含 Markdown 但其实是发布任务”的反例，避免按关键词误选审查 Skill。
• 验证： 固定输入应覆盖：范围匹配并可只读审查、路径缺失、规则版本不匹配、任务实际要求发布、要求自动修改但没有批准。每种输入必须有可追溯的选择、阻塞或升级原因。
• 过渡： 选中 Skill 不代表它拥有外部能力；下一节把 Skill 与 Tool、Workflow、Hook、Plugin 和权限逐一拆开。

5. 概念边界：Skill、Tool、Workflow、Hook、Plugin 与运行环境权限

• 读者问题： 为什么“安装了 Skill”“声明了工具”或“触发了 Hook”都不能说明外部动作已经被允许或完成？
• 叙述任务： 用同一条 Markdown 审查任务画出职责边界：Prompt 提供一次请求输入；Skill 说明可复用任务与资源；Tool 提供可调用的操作接口；Workflow 编排多步状态；Hook 由事件触发自动化；Plugin 是某些产品的打包单元；运行环境和源系统才判定真实访问与副作用。通过“默认只读审查 / 另行批准的修复任务”展示能否写入不由 Skill 文本决定。
• 证据边界： REF-027 仅说明 OpenAI Plugin 可包含 Skills、Apps 与 App templates，且 App 的角色、动作与源系统权限仍适用；REF-024 的实验性 allowed-tools 不提供授权。跨产品职责图、术语对照和例子均为本书教学模型，不是行业标准分类或任何产品架构图。
• 计划工件： 七列职责矩阵：概念、回答的问题、可包含的内容、不能承担的责任、示例证据、何时升级到相邻章节、常见误读。另有一个权限边界图，外部工具与源系统被画在 Skill Contract 之外。
• 验证： 读者能解释以下命题为何不成立：“Skill 已安装，所以可以读仓库”“allowed-tools 已声明，所以能发送消息”“Plugin 已启用，所以源系统授权完成”“Hook 触发，所以结果已验证”。
• 过渡： 边界清晰后，能力的质量不再取决于描述有多长，而取决于它能否被固定输入和证据检查。

6. 测试、版本与弃用：把 Skill 当作长期维护的接口

• 读者问题： 一个 Skill 如何在规则、工具或任务范围变化后仍能被安全地维护，而不是悄悄退化？
• 叙述任务： 定义本书的最小测试矩阵：选择正确、前置条件阻塞、成功发现、失败表示、证据完整、禁止副作用和版本不兼容。再说明版本与弃用的触发：输入或输出契约改变、规则语义改变、支持工具替换、维护者不再负责或证据无法重建。弃用必须提供替代、适用范围、迁移条件或明确停止理由，而不只是删除目录。
• 证据边界： 测试矩阵、版本规则、兼容性定义、弃用记录和维护动作都是本书工程模型。REF-024 可以支持 Skill 包有说明与可选资源，但不规定本书这些测试或发布策略；任何产品版本、上传扫描和管理行为均须写作日重查。
• 计划工件： 生命周期图：Contract → 发现/选择 → 前置检查 → 受控调用 → 验证证据 → 状态记录 → 反馈 → 修订、替代或弃用，以及版本变更记录模板。图会明确用权限边界隔离外部调用，且不描述真实产品调用链。
• 验证： 读者能为 review-markdown-chapter 列出五条固定测试：正常通过、失效链接、未登记引用、术语不一致、范围不明；并能为“规则从只读改为自动修复”判定为需要新 Contract、审批与迁移说明的破坏性变化。
• 过渡： 最后以一个纯教学案例把 Contract、选择、边界、测试和维护记录串成一条完整可审查路径。

7. 完整工程案例：review-markdown-chapter 的受控审查设计

• 读者问题： 一个可复用的内容审查 Skill 在不自动修改、不假装拥有权限的前提下，如何产生对维护者有用的结果？
• 叙述任务： 展开原创案例 review-markdown-chapter：输入为章节路径、规则版本、引用登记和审查维度；前置条件为路径可读取、范围明确、只读检查可用；输出为按必须修复、应修复、建议分级的 findings、证据和未验证范围。流程只创建发现，不修复文件；真正的修改由另一个经批准的编辑任务负责。用一份规则冲突或工具不可用的输入展示 blocked，避免把“没有问题”作为默认。
• 证据边界： 此案例、字段、判定、分级、输出和测试预期均为本书教学设计。它不读取真实仓库、不安装真实 Skill、不调用模型、网络、文件系统、Hook、MCP、Plugin 或源系统；不证明任何平台的审查能力、权限、扫描效果或自动修复质量。
• 计划示例： 08-skills-and-reusable-capabilities.example-plan.md 将定义纯内存的 evaluateSkillSelection 或同等窄函数。输入是注入的 Contract、任务摘要与前置条件快照；输出只表示 selected、blocked、requires_approval 或 not_applicable，并携带原因与证据。实现不执行审查、不写文件、不调用真实工具。
• 验证： 测试不检查模型文本，而检查固定 Contract 和输入所导出的选择状态、原因、证据与禁止动作。案例结果必须保留“未验证范围”，不得把选择、指令或模拟结果表述为真实审查已完成。
• 过渡： 第 9、10 章会把多个 Skill 的计划与状态恢复组织成工作流；第 11、12、14 章再分别处理工具接口、运行环境和人工批准。本章到此只交付一个可维护 Skill 的接口与验证边界。

章节工件状态

1. 已完成：Research Brief 与候选参考资料。REF-024 至 REF-027 的允许陈述、外推禁区和写作日复核要求已登记。
2. 本阶段完成：Chapter Outline。逐节读者问题、叙述任务、证据边界、计划工件、验证和章节依赖已定义。
3. 已完成：First Draft。正文在写作日重读 REF-024 至 REF-027，并将规范或产品事实、本书 Skill Contract 模型与教学案例分开；图示和示例仍未实现。
4. 已完成：Technical Review。来源范围、概念和权限边界、计划工件状态、相邻章节责任及技能契约（Skill Contract）的首次术语呈现均已复核；记录位于 .memory/reviews/2026-07-15-chapter-08-technical-review.md。
5. 已完成：Example Implementation。纯内存 evaluateSkillSelection 的模块缺失红灯、6 项 Node 内置测试和演示已实际运行；它只处理注入对象，记录位于 .memory/reviews/2026-07-15-chapter-08-example-integration.md。
6. 已完成：Diagram Review。chapter-08-skill-lifecycle.mmd 已导出 SVG/PNG 并实际查看；图中将运行环境与源系统授权保留为独立边界，记录位于 .memory/reviews/2026-07-15-chapter-08-diagram-review.md。
7. 已完成：Fact Check。REF-024 至 REF-027 的允许用途、外推禁区、纯内存示例和图示的非事实边界已记录于 08-skills-and-reusable-capabilities.fact-check.md。
8. 已完成：Language Editing。统一术语首现、来源段落、授权证据主语和图示阶段时态；未改变事实范围、示例接口或 Mermaid 含义，记录位于 .memory/reviews/2026-07-15-chapter-08-language-edit.md。
9. 已完成：Final Review。已重跑 6 项纯内存测试与演示、Mermaid SVG/PNG 渲染、正文图源一致性检查和完整项目校验；记录位于 .memory/reviews/2026-07-15-chapter-08-final-review.md。下一项为第 9 章 Research Brief。

Outline 完成检查

• [x] 每个主要小节包含读者问题、叙述任务、证据边界、计划工件、验证和过渡。
• [x] 覆盖最小工件、渐进加载、Skill Contract、发现与选择、支持资源、测试、版本、弃用与 Markdown 审查案例。
• [x] 明确区分 Prompt、Skill、Tool、Workflow、Hook、Plugin 与运行环境权限，且不把任一声明或安装状态写成真实授权或执行证据。
• [x] 限定 REF-024 的规范事实与 REF-025 至 REF-027 的产品事实，不将目录、优先级、自动调用或管理行为外推为跨产品结论。
• [x] 计划图示、测试矩阵和纯内存示例均标为本书模型或教学设计，未提前写入正文、真实工具实现、安装步骤或运行结果。