外观
第 8 章 Research Brief：Skills 与可复用能力
任务与读者问题
同一段审查、发布或排错提示被反复复制时，团队通常只得到一批难以发现、难以验证、也无法说明权限边界的文本碎片。第 8 章要回答的不是“怎样写一个万能 Agent”，而是：怎样把一个重复任务封装为可发现、可组合、可测试且可弃用的 Skill，同时不把指令文本误写成真实权限或工具实现。
读者完成本章后，应能为一个小而明确的任务写出 Skill Contract：触发条件、输入、前置条件、允许的工具类别、输出、失败表示、证据、维护者和版本。该 Contract 是本书工程模型；它不是某个产品的配置格式。
范围与非范围
范围： Skill 的最小接口、发现与选择、渐进加载、支持资源、测试、版本和弃用；Skill 与 Prompt、Tool、Workflow、Hook、Plugin 及运行环境权限的边界；以“审查 Markdown 章节”为教学案例。
非范围： 不定义任何产品的完整安装步骤、固定目录优先级或动态管理后台；不实现真实 Skill、Hook、MCP、插件市场、凭证管理或企业权限系统；不把 Agent Skills 规范的可选字段写成所有产品都支持的能力；不将 Skill 的 allowed-tools 声明、上传扫描或插件安装视为外部系统授权。
研究问题
| 问题 | 需要的证据 | 当前结论 |
|---|---|---|
| 一个跨工具 Skill 的最小工件是什么？ | 一手规范。 | REF-024 规定 Skill 是至少含 SKILL.md 的目录；该文件有 YAML front matter 和 Markdown 内容，name、description 是必填字段。 |
| 为什么不把所有说明都塞进一个文件？ | 一手规范与产品文档。 | REF-024 定义元数据、正文、资源的渐进加载；REF-025 说明 Claude Code 仅在 Skill 使用时加载正文。具体加载机制必须按产品限定。 |
| Skill 的文本能否直接授予工具或外部数据权限？ | 规范与产品权限文档。 | 不能。REF-024 的 allowed-tools 是实验性声明；REF-027 说明插件中的 App 仍继承工作区和源系统权限。Skill Contract 也只能表达需要的能力，不能授权。 |
| 如何区分 Skill、Tool、Workflow、Hook 和 Plugin？ | 一手规范、产品文档与本书设计。 | REF-024、REF-025、REF-026、REF-027 只限定各自语境下的定义或产品组合；本书将给出跨概念的教学边界，不将其伪装为统一行业术语。 |
| 哪些产品行为必须在正文当天重查？ | 官方产品文档。 | Claude Code 的发现与优先级、ChatGPT 的创建/共享/管理和 OpenAI Plugin 的可用性、角色、App 配置均为动态产品事实，正文当天必须重查。 |
已核验来源与可用陈述
| ID | 可在本章使用的陈述 | 证据边界 | 复核状态 |
|---|---|---|---|
| REF-024 | Agent Skills 规范将 Skill 定义为至少包含 SKILL.md 的目录；前置 YAML 元数据中的 name、description 必填；可选 scripts/、references/、assets/ 支持按需资源；元数据、正文和资源可渐进加载。 | 只归因给规范；不宣称每个 Agent 完整实现其字段或加载策略。allowed-tools 是实验性字段，不能作为权限证明。 | 2026-07-15 已复核规范。 |
| REF-025 | Claude Code 的 Skill 使用 SKILL.md，可在相关时自动使用或直接调用；其项目、个人和插件位置及优先级属于 Claude Code 的产品行为。 | 只用于 Claude Code；不外推为 Codex、ChatGPT 或其他 Agent 的目录/优先级。 | 2026-07-15 已复核官方文档。 |
| REF-026 | ChatGPT 将 Skill 描述为可复用、可共享的工作流，可包含说明、示例和代码；产品页面说明上传前扫描不能替代使用者的审查、政策或判断。 | 仅限该页面所述 ChatGPT 与相关 OpenAI 产品；不将扫描写成安全保证，也不外推其工作区控制到 Codex。 | 2026-07-15 已复核官方帮助页。 |
| REF-027 | OpenAI Plugin 可打包 Skills、Apps 与 App templates；App 的角色、动作和源系统权限仍适用，Plugin 本身不覆盖源系统访问权限。 | 只用于该 OpenAI 产品范围；不推断所有 Plugin 或 MCP 实现具有相同结构。 | 2026-07-15 已复核官方帮助页。 |
本书的工程扩展
以下内容是为软件工程读者建立的 Skill Contract，不属于任何来源的原文、产品 schema 或标准接口：
| Contract 项 | 本书定义 | 不表示什么 |
|---|---|---|
| 解决的问题与触发条件 | 一个窄、可重复、可验收的任务，以及应该和不应该选择它的条件。 | 不保证模型一定自动发现它。 |
| 输入与前置条件 | 所需任务数据、上下文、环境、版本和禁止输入。 | 不自动读取全部仓库或自动补足缺失信息。 |
| 工具与权限边界 | 需要的工具类别、最大副作用和升级条件。 | 不是授权令牌、Sandbox 规则或源系统 ACL。 |
| 输出与失败契约 | 成功、阻塞、拒绝和未证实分别如何表示，及每种结论的证据。 | 不把自然语言“已完成”当作验证。 |
| 验证、版本与维护 | 可重复检查、兼容性、维护者、变更记录和弃用条件。 | 不要求每个小任务都引入复杂发布系统。 |
本书采用的概念边界如下：
- Prompt 是一次请求中的指令或输入，不等于可维护能力单元。
- Skill 是围绕一个任务的可发现说明与支持资源；它可以指导使用 Tool 或 Workflow，但不等于二者。
- Tool 定义一个外部操作的输入、输出、错误和副作用接口；第 11 章处理其具体契约。
- Workflow 组织多个步骤、状态和恢复；第 10 章处理状态机，不让第 8 章把多步骤流程偷换成单一 Skill。
- Hook 是由事件触发的自动化机制；第 23 章讨论触发风险和 CI，避免把每个自动执行都称为 Skill。
- Plugin 是特定产品中可包含 Skill、App 或模板的打包单位；它的发现和权限行为必须按产品资料核验。
计划叙述与工件
- 用“反复粘贴 Markdown 审查提示”的场景说明 Prompt 碎片为何不能形成可复用能力。
- 给出 Skill、Prompt、Tool、Workflow、Hook、Plugin 与运行环境权限的职责表，先排除“Skill 等于授权”的误解。
- 以 Skill Contract 组织触发、输入、前置条件、工具边界、输出、失败、证据、维护和弃用。
- 用生命周期图表达注册、选择、前置检查、受控执行、验证、记录、反馈与版本变更；该图是本书模型，不代表产品调用链。
- 以“审查 Markdown 章节”示例展示只读输入、引用/链接/语言检查、结构化发现和人工升级；不在第 8 章自动修改正文或创建真实外部权限。
计划图示
Skill 生命周期图（计划）： Skill Contract → Registry/Discovery → 任务匹配 → 前置条件检查 → 受控工具调用 → 验证与证据 → 结果状态 → 反馈、版本或弃用。
图中会用独立的权限边界包围外部工具：Skill 的选择和指令不能越过它；任何写入或外发动作必须由第 11、12、14 和 41 章定义的工具、运行环境、审批和审计机制另行决定。
计划示例
名称： review-markdown-chapter（教学设计，不是已安装 Skill）。
| 项目 | 计划内容 |
|---|---|
| 触发 | 用户请求审查一篇指定 Markdown 章节，且提供可读取的章节与项目规则。 |
| 输入 | 章节路径、引用登记、适用写作规则和所需审查维度。 |
| 前置条件 | 文件存在；审查范围明确；只读检查工具可用。 |
| 正常输出 | 结构化 findings，按必须修复、应修复、建议分级，并链接相关证据。 |
| 阻塞输出 | 缺少来源、无法读取文件、规则冲突或校验工具不可用时，说明原因和未验证范围。 |
| 副作用 | 默认无；修复应另由批准的编辑任务执行。 |
| 验证 | 构造通过、失效链接、未登记引用、术语不一致和范围不明五种固定输入；检查每种状态、证据和禁止动作。 |
风险与正文当天复核
- 自动发现、安装范围、目录优先级、管理后台、角色控制和 Plugin/App 的具体可用性会变化；正文编写当天重新访问 REF-025 至 REF-027。
description是发现线索而非安全边界；高风险任务应在 Contract 中要求显式调用、前置检查或人工批准。- Skill 包可含说明、支持文件或代码。使用外部包前需要审查来源、资源和副作用；任何产品扫描只可视为一层信号，不替代人工或组织政策。
TODO(verify)：若正文需要引用特定平台的 Skill 安装、调用、权限、版本或日志行为，应以写作日官方页面重新建立针对该陈述的证据卡。
Research 完成检查
- [x] 明确了读者问题、范围、非范围与后续章节边界。
- [x] 核验了一个开放规范与三个产品一手来源，并分别限定可用陈述。
- [x] 将 Skill Contract、概念边界、图示和案例标明为本书工程模型或教学设计。
- [x] 明确 Skill、Plugin 或
allowed-tools声明不等于真实运行环境或源系统权限。 - [x] 未写入正文、产品安装步骤、未验证运行结果或性能主张。