第 34 章详细 Outline：团队级 Skill Library

写作契约

本章要完成的学习目标

读者完成本章后应能：

1. 区分一个包含 SKILL.md 的目录、一个可发现的条目和一项可维护的团队资产，不把任一层的存在写成已获信任或可安全执行。
2. 用技能注册记录（Skill Registry Record）和技能契约（Skill Contract）分别表达发现、责任、输入输出、触发和副作用边界。
3. 为候选 Skill 设计准入审查（Admission Review）与质量等级（Quality Tier），并解释结构检查、风险审查、共存评估和运行时授权不能互相替代。
4. 先声明可观察的团队契约，再用兼容性声明（Compatibility Declaration）讨论版本变化与迁移，而不把版本号当作模型行为或安全性的证明。
5. 为所有者变更、评估退化和替代能力设计反馈与弃用记录（Deprecation Record），并指出哪些情况必须停止并交给人工决定。

读者、前置与明确边界

• 读者： 能阅读 Markdown、YAML frontmatter、JavaScript 对象和简单检查表，且需要把个人自动化经验沉淀为可审查团队资产的工程读者。
• 前置： 第 08 章的 Skill 与 Skill Contract、第 17 章的评估规格与证据、第 22 章的仓库级规则、第 23 章的 Skills／Hooks、第 26 章的协作与任务隔离，以及第 33 章的项目记忆与责任信息。
• 本章负责： 在虚构团队案例中说明登记、契约、准入、等级、兼容性、反馈和退役如何组成 Skill Library 的治理接口。
• 本章不负责： 真实 Skill 安装、插件打包、市场发布、产品配置、网络请求、MCP 调用、浏览器、文件读写、凭证、组织授权、生产评估、SLA、安全认证或跨产品迁移。

来源与本书模型的分层

使用位置	可归因材料	本章允许的有限陈述	本书原创内容
第 1、3 节	CH34-REF-01 / REF-024	Agent Skills 规范把目录、必填 name／description、可选字段与渐进加载资源置于格式层。	团队登记字段、契约分层与“格式不等于治理”的判断。
第 1、5 节	CH34-REF-02 / REF-106	Codex 文档说明其 Skill 的发现位置、description 对隐式触发的影响，以及直接 Skill 与可分发 plugin 的用途区别。	多候选的触发范围、共存评估和发现后的保守结论。
第 1、4 节	CH34-REF-03 / REF-107	Anthropic 文档在其产品语境中描述 Skill 的目录形态、不同产品表面的共享与运行约束，并建议审计未知来源。	来源信任记录、风险问题和“不跨表面外推”的停止规则。
第 4、5、7 节	CH34-REF-04 / REF-108	Anthropic 企业指南提出发布前风险审查、触发／隔离／共存／输出质量评估、所有者、版本、监测与弃用等治理建议。	准入审查、质量等级、反馈路由、责任模型和退役门。
第 6 节	CH34-REF-05 / REF-109	SemVer 以清晰 public API 为前提，区分不兼容改动、兼容新增与兼容修复，且已发布版本不应原地修改。	面向 Skill 的可观察契约、兼容性差异表、迁移记录和不确定性出口。

正文必须以“规范说明”“Codex 文档说明”“Anthropic 文档说明”“SemVer 规范说明”“本书工程模型”或“虚构教学输入”标明层次。不得把目录格式、发现说明、指南清单、版本规则或未来示例写成任何团队、产品或 Skill 已被安装、审计、授权、发布、选择或执行的事实。

章节叙事与逐节蓝图

1. 从共享文件夹到可治理的团队资产

• 要回答的问题： 为什么把一段提示词、脚本或 SKILL.md 放进共享仓库，仍不能回答“谁负责、何时触发、何时停止使用”？
• 场景输入： 虚构团队已经收集了多个“好用的” Skill 条目，但成员无法判断两个条目是否重叠、未知来源是否可引入，或失效依赖由谁处理。
• 来源事实： CH34-REF-01 只用于说明 Skill 目录的最小格式和渐进资源；CH34-REF-02、CH34-REF-03 只用于说明各自产品文档中的发现、表面与来源审计语境。
• 核心论证： “文件存在”“可被某个产品发现”“团队应使用”是三种不同主张。前两者都不能推出维护责任、风险结论、运行时权限、效果质量或跨产品可用性。
• 最小证据： 用三列表比较目录、候选条目和团队资产各能回答、不能回答的问题；所有字段均为本章教学输入。
• 预期验证： 读者能指出把 description 写得更宽泛不能解决冲突，反而可能扩大不恰当触发的范围。
• 过渡： 先给三个不同风险面的候选能力命名，才能让治理字段不再停留在抽象名词。

2. 教学场景：三个候选 Skill，三种不能直接发布的原因

• 要回答的问题： 团队怎样从具体候选开始，而不是先设计一个空泛的“Skill 平台”？
• 教学案例： 一个虚构团队准备登记 API 契约测试、文档事实核验和发布检查三个候选 Skill；每个候选都只是注入的记录，不包含真实仓库、服务、用户、URL、凭证或运行结果。
• 候选差异：
  1. API 契约测试缺少维护者和依赖声明，只能保持提案状态。
  2. 文档事实核验声明了只读边界和评估样例，可进入受限评审，但并未访问任何资料或网站。
  3. 发布检查把写入描述成无条件动作，必须先拆出审批与副作用边界，不能发布。
• 最小证据： 用“用途／触发条件／非触发条件／依赖／副作用／所有者／当前缺口”表格逐项列出三个教学输入；不展示真实 Skill 内容或产品配置。
• 预期验证： 读者能为每个候选写出最小停止理由，而不是把“团队以前用过”当作准入证据。
• 过渡： 候选有了可比输入后，下一节把“登记”和“执行说明”拆成两个不能互相代替的工件。

3. 两份独立工件：Skill Registry Record 与 Skill Contract

• 要回答的问题： 发现一个候选与理解其允许行为，为什么必须有不同的字段和审查问题？
• 本书 Skill Registry Record： 包含稳定标识、用途、触发范围、所有者、契约版本、依赖、评估状态、生命周期状态与相关证据指针；它只让人发现和追溯候选，不安装、不授权、不执行。
• 本书 Skill Contract： 包含输入前提、触发条件、非触发条件、允许输出、工具边界、副作用类别、失败路径、所需证据与维护范围；它不能保证模型选择正确或运行环境允许执行。
• 来源事实： CH34-REF-01 的 name 和 description 只说明格式的必填元数据；CH34-REF-02 对 description 的隐式触发语境不支持本书的全部契约字段或跨产品匹配承诺。
• 最小证据： 用字段归属表将“所有者”归入登记记录、将“允许写入吗”归入契约、将“已做过一次评估”归入评估状态；对无法归属的陈述要求先澄清问题。
• 失败分支： 缺稳定标识、所有者、非触发条件、依赖、效果边界或失败路径时，不进入准入审查，而是返回 missing_registry_evidence 或 missing_contract_boundary 一类的教学停止结论。
• 预期验证： 读者能拒绝“有 README，所以知道怎么运行”与“有版本号，所以知道该何时触发”两种替代推理。
• 过渡： 工件齐全只说明能够审查；下一节定义审查时应检查什么及谁不能自行宣布通过。

4. 准入审查与质量等级：把可用性、风险和责任拆开

• 要回答的问题： 为什么同一个作者不能仅凭结构正确就把候选提升为团队基础能力？
• 来源事实： CH34-REF-03 只支持未知来源需要审计的产品文档建议；CH34-REF-04 只支持其企业治理指南中的风险、触发、隔离、共存、输出质量、所有者和版本等评估维度。
• 本书 Admission Review： 以独立审查者、审查范围、来源与依赖、风险、触发准确性、共存、输出质量、责任和未决项组成；它不替代运行时权限、沙箱、密钥管理、业务验收或安全认证。
• 本书 Quality Tier： 定义 proposal、limited、maintained 三个教学等级。每级必须说明进入条件、可见限制、维护责任、重新评估触发和降级出口；等级不是 SLA、合规标签或效果保证。
• 最小证据： 为三候选分别展示“缺字段退回提案”“可读但受限地进入审查”“副作用未分离而被阻止”的路由表。
• 预期验证： 读者能解释结构检查、依赖审查、风险审查、共存评估和输出评估各自减少什么不确定性，以及任何一项通过仍不能证明真实执行安全。
• 过渡： 即使候选进入某一等级，发现和选择仍会发生冲突；下一节把触发、隔离与反馈从“自动选择”中拆开。

5. 发现、触发、共存与使用反馈：不把被选择当作成功

• 要回答的问题： 多个 Skill 面向相近任务时，团队如何减少抢占与误用，而不声称模型一定会选对？
• 来源事实： CH34-REF-02 的发现位置和 description 语境只说明 Codex 的有限产品行为；CH34-REF-04 的触发、隔离、共存和输出质量评估只提供组织层的受限参考。
• 本书触发规则： 登记记录中的触发范围必须同时写出非触发条件、互斥或优先关系、所需输入和证据缺口；过宽描述或不可解释的相似度不能直接作为选择规则。
• 本书共存评估： 为同一任务准备多个候选的教学输入，分别记录被选原因、未选原因、冲突、隔离假设、输出边界和人工覆盖条件；它不调用模型、浏览器、网络或工具。
• 本书 Feedback Record： 只关联候选版本、场景类别、观察、限制、责任人和重新评估触发；一次正面反馈不等于质量已稳定，负面反馈也不自动禁用条目。
• 最小证据： 比较“文档事实核验”和“发布检查”面对“更新公开说明”的不同非触发条件，要求读者指出为何后者不能因名称相似而被选择。
• 失败分支： 触发重叠、缺少隔离假设、评价不完整、输入包含未知来源或副作用边界不清时，路由为 requires_review，而不是重试选择或默认执行。
• 过渡： 选择规则与反馈变化会影响团队对外承诺；下一节说明版本如何承载可观察差异，而不是为模型行为背书。

6. 版本与 Compatibility Declaration：先说清什么会变

• 要回答的问题： 为什么“从 1.2.0 升到 2.0.0”本身无法说明一个 Skill 会如何改变？
• 来源事实： CH34-REF-05 仅支持 SemVer 以清晰 public API 为前提，以及主／次／补丁改动与发布不可原地修改的规范语义。
• 本书 Compatibility Declaration： 对每次候选变更列出触发条件、输入、输出、依赖、工具边界、副作用、评估样例、迁移路径与未覆盖范围的前后差异；版本意图必须能回到这张差异表。
• 兼容性案例： 收紧文档事实核验的来源范围、改写 API 契约测试的必需输入、或为发布检查增加审批字段，分别可能影响触发、输入或效果边界。案例只说明应审查的差异，不声称任何实现已升级或兼容。
• 最小证据： 用“变动字段／受影响调用方类别／需要的迁移信息／必须重评估的场景”表替代只写版本号的变更说明。
• 停止规则： 未定义可观察契约、依赖版本未知、迁移路径不明、评估不能覆盖重要变动或存在未审副作用时，版本状态保持 not_ready_to_publish。
• 预期验证： 读者能指出 SemVer 不能直接证明自然语言指令、模型触发、外部工具结果或安全属性兼容。
• 过渡： 版本说明仍不能处理维护责任消失或替代能力出现，下一节把所有权、监测和退役写成可交接的生命周期。

7. 所有权、反馈与弃用：让团队有可撤回的生命周期

• 要回答的问题： 当维护者离开、依赖失效或更安全的替代条目出现时，怎样防止旧 Skill 被静默继续使用？
• 来源事实： CH34-REF-04 的监测、所有者、版本和弃用建议只能作为本节的治理背景，不能扩大为任何组织已经具备监测平台、审批链或保留策略。
• 本书责任模型： 作者提交候选与已知限制；维护者维护契约、依赖和弃用决定；评审者维护准入证据；使用者反馈观察与缺口；集成者只处理已经通过独立门的共享登记变更。
• 本书 Deprecation Record： 包含原因、受影响的契约版本、替代项、迁移期限、维护终点、风险提示、保留证据和删除门；它不迁移调用方、不删除旧资源、不撤销权限。
• 最小证据： 对“发布检查”候选模拟维护者不可用与副作用边界变更两个事件，分别路由到降级、停止推荐或人工复核，而不直接删除条目。
• 预期验证： 读者能区分“停止推荐”“停止维护”“停止执行”“删除文件”这四种状态，并解释为什么它们需要不同证据和负责人。
• 过渡： 生命周期规则应有最小、可反驳的实现，但实现只能检验注入材料，不能充当真实的 Skill 管理平台。

8. 最小示例：纯内存的团队 Skill 准入评估器

• 要回答的问题： 如何把登记、契约和审查的停止规则写成可测试接口，而不创建、安装或运行 Skill？
• 示例边界： Example Implementation 阶段将为注入的候选记录建立纯内存评估器；函数名称、测试数量、红灯记录和 npm 入口均留待该阶段决定。实现不得读取仓库、调用产品 API、安装插件、请求网络、访问凭证、执行脚本、修改文件或改变注册表。
• 计划输入： 登记记录、Skill Contract、Admission Review、Quality Tier、Compatibility Declaration 与可选 Deprecation Record；每一项仅为教学对象。
• 计划路由： 证据齐全的候选可返回“可在隔离示例中实现”的保守状态；缺所有者、依赖、非触发条件、风险审查、共存评估、副作用边界或迁移说明的候选返回具名停止码；未知来源或写入边界未审时返回 requires_approval。
• 计划测试： 至少覆盖一个完整受限候选、一个缺维护者候选、一个触发冲突候选、一个未分离副作用候选、一个兼容性不明候选与一个弃用但仍试图推荐的候选；断言只检查公开返回结构。
• 预期验证： 提纲阶段不记录任何测试命令、红灯、绿灯或演示输出；只有 Example Implementation 阶段实际执行后，才能报告相应结果。
• 过渡： 纯函数可表达规则，但图示必须让登记、审查、选择、反馈和退役的断点一眼可见。

9. 图示与完整教学案例：Skill 治理生命周期的断点

• 要回答的问题： 怎样在一张图中保留生命周期顺序，又不画出“登记即执行”或“反馈即批准”的错误箭头？
• 图示内容： Proposal → Registry Record + Skill Contract → Admission Review → Quality Tier → Discover / Select → Feedback Record → Compatibility Declaration → Maintain or Deprecation Record；结构缺失、风险未审、触发冲突和副作用不清分别指向 stopped 或 requires_approval。
• 关键箭头解释： 作者、维护者、评审者与使用者进入不同节点；没有从 Registry Record 指向“已安装”、没有从 Select 指向“外部效果已发生”、没有从 Feedback Record 指向“下一版已批准”的箭头。
• 工件与验收： 正文 Mermaid 块后续必须与 diagrams/mermaid/chapter-34-team-skill-library-lifecycle.mmd 一致；图源、导出图、替代描述、读图说明和视觉检查留到 Diagram Review。
• 完整案例表： 以三候选为行，以登记缺口、契约边界、审查结论、质量等级、版本影响、反馈事件和弃用出口为列；所有结果都标为教学路由。
• 预期验证： 读者能对任何一条箭头说明它需要的最小证据，并指出图没有证明的运行时事实。
• 过渡： 图表达一次可审查路由；下一节说明当团队确实需要连接真实系统时，应如何每次只增加一种控制。

10. 逐步增强：何时离开纯内存治理模型

• 要回答的问题： 团队从一张登记表走向真实 Skill 分发与执行时，哪些新风险要求新增控制？
• 渐进表：

新需求	必须新增的控制	升级触发	本章为何不实现
扫描真实仓库中的 Skill	只读范围、来源清单、路径规则和敏感文件边界。	需要从教学目录判断真实材料。	示例不读取文件。
分发或安装 Skill／plugin	发布源、签名或来源验证、版本锁定、回滚与受影响范围。	需要改变其他人的可用能力。	本章不打包或安装。
让 Skill 调用工具	环境契约、最小权限、审批、前后观察、超时和效果处理。	产生网络、文件或业务副作用。	登记与契约不授予权限。
收集实际使用反馈	数据分类、保留策略、匿名化或同意、观测质量和人工解释。	要记录真实用户或任务数据。	Feedback Record 不采集数据。
跨团队或跨租户治理	身份、策略、隔离、预算、审计与人工升级。	Skill 触及企业共享系统。	留给第 35 章的企业控制平面。

• 预期验证： 每个升级条件必须回答“纯内存工件缺少哪一种真实证据或控制”，不能因“团队变大”就直接引入工具、平台或权限。
• 过渡： 最后一节回收团队库的可迁移边界，并把规模化控制与模式复用留给后续章节。

11. 总结、练习与后续连接

• 总结回收： 团队 Skill Library 的核心不是让更多条目被发现，而是让每个条目的用途、触发、责任、风险、评估、兼容性和退出路径可分别审查。格式、登记、评审、版本和反馈都只能产生受限结论。
• 练习：
  1. 为一个“变更日志核验”候选写出登记记录和契约中各自必须出现的三个字段。
  2. 给两个触发描述重叠的候选写出一个共存评估问题和一个停止出口。
  3. 为收紧输入范围的 Skill 改动写一条 Compatibility Declaration，并列出不能从版本号推出的两项事实。
  4. 为失去维护者的条目写出 Deprecation Record 的最小字段，区分停止推荐与删除文件。
• 后续连接： 第 35 章把共享能力放入企业控制与执行平面的边界；第 37 章把项目记忆与 Skill 的接口抽象为设计模式；第 43、44 章再将可治理资产用于书稿与工厂复用。任何后续章节都不能倒过来把本章的教学登记写成真实部署、权限或组织治理证明。

后续阶段的交付与验证契约

阶段	计划产物	本阶段不应提前声称的事实
First Draft	原创正文、三候选教学案例、术语首现、表格和交叉章节连接。	真实 Skill、plugin、注册表、评估或治理流程已经运行。
Technical Review	写作日重读 CH34-REF-01 至 CH34-REF-05，核对来源限定、术语边界与案例时态。	当前产品发现路径、跨表面共享或企业指南已被普遍实现。
Example Implementation	纯内存评估器、红灯记录、实际 Node 测试与演示。	任何候选已安装、已发布、已调用工具或已得到真实反馈。
Diagram Review	Mermaid 源、导出图、替代描述、图文一致性和视觉检查记录。	图示描述真实团队的审批、执行或退役事件。
Fact Check	来源映射、写作日复核、允许陈述和外推禁区。	规范或产品文档证明本书模型、教学案例或读者组织正确。
Language Editing	术语、主语、时态、表格和章节衔接的一致性编辑。	编辑本身完成了技术、事实、图示或运行验证。
Final Review	章节工件、状态、引用、示例、图示和项目校验的最终核对。	外部安装、授权、生产使用、SLA 或安全认证已发生。

提纲完成检查

• [x] 每一节都说明了读者问题、最小证据、教学工件、预期验证和与下一节的关系。
• [x] Agent Skills、Codex、Anthropic 与 SemVer 的限定陈述同本书治理模型和虚构案例已分层。
• [x] 注册、审查、等级、触发、版本、反馈和弃用的边界均未扩大为真实执行、权限或效果结论。
• [x] 与第 08、23、26、33、35、37、43、44 章的连接与不重复范围明确。
• [x] 后续阶段不会把计划、图示、版本、评审或纯内存示例写成已安装、已发布、已授权或已运行。