第 34 章 Research Brief：团队级 Skill Library

要解决的工程问题

个人把一段有效提示词、脚本或检查步骤叫作 Skill，并不意味着团队已经获得可复用资产。另一个成员仍可能不知道它何时该触发、谁会修复失效依赖、升级是否破坏输入输出，或何时该停止使用它。本章研究如何把“一个可发现的 Skill 目录”扩展为“一个可治理的团队库”：每个条目都有可审查的契约、维护责任、版本、证据和退役路径，而不是建立一个只会越堆越大的共享文件夹。

读者问题与范围

读者问题	本章研究的回答	本章不回答
为什么把 SKILL.md 提交到仓库还不够？	目录和元数据解决部分格式与发现问题；团队还需登记用途、所有者、依赖、评估状态和生命周期。	某个仓库、市场或产品已经自动完成审查、发现或发布。
如何让两个相似的 Skill 不互相抢任务？	把触发范围、非触发条件、输入输出、依赖与评估样例放入可审查的 Skill Contract，并用共存评估检查冲突。	描述文字本身能保证任何模型都准确选择 Skill。
版本和弃用该如何表达？	先声明团队对外承诺的契约，再以兼容性变化、迁移说明和替代项组织版本与退役记录。	所有 Skill 都适用 SemVer，或版本号本身能证明兼容性。
为什么安全审查是库的一部分？	脚本、工具、网络、文件范围和凭证都属于发布前应检查的风险面；登记必须能指出审查证据和风险边界。	审查清单替代运行时权限、沙箱、密钥管理或真实安全认证。

已核验的一手资料

| 本地键 | 来源明确表达的内容 | 允许用途 | 不可外推 | | --- | --- | --- | | CH34-REF-01 | Agent Skills 规范把 Skill 定义为至少含有 SKILL.md 的目录；其 YAML frontmatter 要求 name 和 description，并列出可选的兼容性、元数据与实验性允许工具字段。规范还说明指令、引用资料与资源可以按需渐进加载。 | 区分格式层的最小目录、发现元数据与可选资源。 | 任一客户端都实现全部字段、加载顺序或验证器，或格式本身已完成团队治理。 | | CH34-REF-02 | Codex 文档说明 Skill 可位于仓库、用户、管理员和系统位置；description 影响隐式触发，直接 Skill 更适合本地／仓库创作，而可复用分发可以打包为 plugin。 | 说明一个产品中的发现范围、触发描述与本地创作／可分发打包的区别。 | 其他产品具有相同扫描路径、插件格式、工作区分享方式或上下文预算。 | | CH34-REF-03 | Anthropic 的 Agent Skills 概览说明 Skill 是含指令、元数据和可选资源的文件系统目录，且不同产品表面的自定义 Skill 共享范围与运行环境约束不同；文档还要求把来自未知来源的 Skill 当作需审计的软件。 | 说明产品表面、运行环境与来源信任不能被“Skill”一词抹平。 | 任何团队都可集中管理所有表面，或一次上传会自动跨表面同步。 | | CH34-REF-04 | Anthropic 的企业治理指南给出发布前风险审查、触发准确性／隔离／共存／输出质量评估、所有者与版本登记、源码控制、监测及弃用等组织层建议。 | 为本章的审核证据、评估门、所有权、登记和退役模型提供受限背景。 | 该清单是通用合规标准；其中产品 API 的数量限制、部署方式或分析能力适用于其他平台。 | | CH34-REF-05 | Semantic Versioning 2.0.0 以清晰声明的 public API 为前提，并约定不兼容改动、兼容新增和兼容缺陷修复对应的主／次／补丁版本语义；已发布版本内容不可原地修改。 | 讨论“先定义对外契约，再让版本号传达变化”的软件包类比。 | Skill 的自然语言指令、模型行为、外部工具或输出质量天然满足 SemVer 的兼容性定义。 |

访问日期均为 2026-07-16。CH34-REF-01 已复用 REF-024，CH34-REF-02 至 CH34-REF-05 已分别登记为 REF-106 至 REF-109；完整 URL、限定语义和登记提示见本章参考资料。这些产品与规范页面会变化；First Draft、Technical Review 和 Fact Check 必须在各自写作日重新读取，尤其不能把产品分发、权限、表面隔离或默认行为写成跨产品事实。

本书工程模型

下列工件是本书提出的团队治理模型，不是 Agent Skills、Codex、Claude 或 Semantic Versioning 的固定 schema、产品功能或已运行系统。

工件或角色	要解决的问题	最小证据	关键边界
Skill Registry Record	让读者能发现一个候选 Skill 的用途、触发条件、所有者、版本、依赖与生命周期。	标识、用途、维护者、契约版本、依赖、评估状态和当前状态。	登记记录不安装、不授权也不执行 Skill。
Skill Contract	将“何时使用”拆成输入前提、触发／非触发条件、允许输出、工具与副作用边界。	可读的输入、输出、权限和失败路径。	文字契约不保证模型选择或执行正确。
Admission Review	在发布前分开检查结构、依赖、风险、评估和责任，而不是由作者单独宣布可用。	评审者、审查范围、风险结论和缺项。	通过审查不等于获得运行时权限或业务验收。
Quality Tier	让团队显式区分实验、受限可用和受维护条目，避免把一次性脚本误当基础能力。	每级进入条件、可见限制和升级门。	等级不是安全认证、SLA 或效果保证。
Compatibility Declaration	说明某次改动影响的是触发条件、输入、输出、依赖、工具边界还是迁移路径。	前后契约差异、版本意图和迁移说明。	未执行的兼容性声明不能替代回归评估。
Deprecation Record	在停止推荐或移除前保留原因、替代项、迁移期限和维护终点。	弃用日期、替代条目、影响范围和删除门。	弃用记录不自动迁移调用方或删除旧副作用。

为避免把这些名称误认作外部产品字段，后续正文首次出现时应使用“技能注册记录（Skill Registry Record）”“技能契约（Skill Contract）”“准入审查（Admission Review）”“质量等级（Quality Tier）”“兼容性声明（Compatibility Declaration）”和“弃用记录（Deprecation Record）”。其中 Skill Contract 与第 8 章的单 Skill 契约保持概念连续性；第 34 章只增加团队资产的登记和责任边界。

教学案例、图示与示例计划

教学案例是一个虚构团队准备登记三个候选能力：API 契约测试、文档事实核验和发布检查。三者都只是一份待审查的注入记录：它们不请求网络、不读取仓库、不调用 MCP、不开启浏览器、不创建 plugin，也不代表这些能力已经被安装或运行。案例应刻意呈现三种不同结论：

• API 契约测试缺少维护者和依赖声明，只能停在提案；
• 文档事实核验有明确的只读边界和评估样例，可以进入受限评审；
• 发布检查将写入操作描述为无条件动作，必须先拆出审批与副作用边界，不能发布。

后续图示应从提案开始，依次经过契约、风险／质量评审、版本化发布、发现／选择、反馈与弃用，并明确两类断点：登记或发布不等于执行；使用反馈不等于批准下一版。图中还需把作者、维护者和评审者的职责分开，避免把“团队拥有”误画成“所有人都能发布”。

后续最小示例应仅评估一个注入的 Skill Registry Record 是否具备进入隔离实现阶段的证据，例如是否同时声明契约、维护者、依赖、风险审查、共存评估和副作用边界。Example Implementation 阶段才决定函数名、测试数量、红灯记录和 npm 入口；本阶段不创建 Skill、脚本、插件、注册表服务、外部连接、凭证、网络请求或产品配置。

风险、非范围与后续核验

• 不能把统一目录、漂亮的 catalog 页面或版本标签写成团队已经拥有可信 Skill Library；可信度需要能定位到契约、责任、风险和评估证据。
• 对带脚本、网络、MCP 引用、宽泛文件访问或凭证的 Skill，应把风险写在审查对象中；不得把静态检查说成隔离、授权或数据防泄漏的证明。
• 避免用过宽的 description 换取“更容易触发”：它可能与其他能力冲突，且不同模型和产品的匹配行为不相同。
• 不把 SemVer 的规则直接施加到自然语言指令；只有先定义了团队可观察的公共契约，版本增量才有可审查含义。
• 不讨论真实公司的组织结构、人员身份、客户数据、生产凭证、采购流程、产品价格、平台许可、SLA、审计认证或实际发布记录。
• TODO(verify)： First Draft 写作当天重读 CH34-REF-01 至 CH34-REF-05，核对格式字段、Codex 的发现／分发位置、各产品的共享范围、企业指南中的风险与评估表述，以及 SemVer 原文；未重读前不得写为当前产品事实。
• TODO(verify)： Chapter Outline 前检查 .ai/glossary.md 与第 8、23、35、37 章的术语和边界；若新增团队治理术语，先由主线程统一登记，避免将本章私有字段扩散成全书标准。
• TODO(verify)： Example Implementation 前确认仓库的既有纯内存示例约定；若没有受控目标，示例只评估注入对象，并明确 executionPerformed: false 一类的未执行边界。

下一阶段

Chapter Outline 应把个人 Skill 到团队资产的差异、Skill Registry Record、Skill Contract、准入审查、质量等级、兼容性声明、使用反馈和弃用记录拆成逐节蓝图。每节都要标注：允许引用的外部事实、本书新增的治理规则、虚构三 Skill 案例，以及不能从登记、评审或纯内存示例推出的运行结论。