附录 B：Skill Library

本附录给出可复制的技能（Skill）接口、登记方式和测试清单。Skill 是一个窄任务的可维护契约，不是更长的 Prompt，也不是权限授予。完整概念边界见第 8 章，团队治理见第 34 章。

最小 Skill Contract

复制下面的骨架时保留所有责任字段；不适用项写 not_applicable 并说明理由，不要删除安全、证据或失败槽位，也不要用占位文字伪装已经完成的设计。

# Skill 名称

## 解决的问题

用一句话描述可重复、可验收的窄任务，并列出不适用场景。

## 输入与前置条件

- 必需输入：
- 触发条件：
- 非触发条件：
- 需要读取的上下文：
- 环境和依赖：
- 权限来源：
- 工具与副作用边界：
- 禁止或敏感输入：

## 输出契约

- 成功输出：
- 阻塞/拒绝/未知输出：
- 可观察证据：
- 每种状态的验证方式：
- 允许的副作用：

## 执行步骤

1. 验证输入、范围和新鲜度。
2. 执行最小动作。
3. 验证可观察结果。
4. 记录未覆盖范围和交接。

## 测试与维护

- 正常场景：
- 缺输入、过期输入和冲突场景：
- 权限不足和外部失败场景：
- 契约版本、维护者、兼容范围：
- 废弃和迁移条件：

仓库中的可编辑源模板见 templates/skill-template.md。本附录是面向读者的扩展说明；项目内契约应从源模板创建，模板字段变化时先更新源模板及受影响 Skill，再刷新本附录。

注册表样例

注册表负责发现和治理，不复制 Skill 的全部正文。

字段	示例	审查问题
id	<stable-skill-id>	稳定标识能否定位同一候选？
name	review-markdown-chapter	名称是否对应一个窄任务？
purpose	只读审查指定章节	是否描述结果而非宣传能力？
trigger_scope	已提供章节、规则和审查维度	什么时候可以进入选择？
non_trigger_conditions	发布、翻译或未经授权写入	什么时候必须拒绝或转交？
owner	<named-owner>	谁负责更新、停用和回应失败？
contract	<skill-contract-path>	登记是否只指向契约而不复制全文？
contract_version	<contract-version>	版本变化是否对应可观察契约变化？
dependencies	Markdown 规则与引用登记	缺失或变化时是否停止并复核？
evaluation_status	<actual-evaluation-status>	是否只描述已执行评估的有限范围？
evidence_pointer	<evaluation-evidence-path>	证据能否独立复核？
quality_tier	<proposal | limited | maintained>	推荐范围是否与证据和限制一致？
lifecycle_status	<draft | active | deprecated | retired>	是否存在 deprecated/retired 出口？

Skill Card 1：只读章节审查

问题： 在不修改正文的前提下，定位技术、结构、引用和边界问题。

输入： 明确章节路径、规则版本、引用登记和审查维度。

输出： 分级 findings、证据路径、未验证范围；没有发现时记录检查范围。

副作用： 默认无。自动修改、发布或全仓重写必须进入另一任务。

状态：

条件	结果
输入和规则齐全	selected
章节或维度不明	blocked
请求同时要求未经授权写入	requires_approval
任务是发布或翻译	not_applicable

这些状态是本附录的教学输出，不是产品 API 枚举，也不证明真实 Skill 已被发现、选择、授权或执行。

最小测试： 固定一份有已知断链和无来源断言的 Markdown 输入；断言输出定位正确、未修改文件，并在缺少引用登记时停止。

Skill Card 2：来源事实核验

问题： 判断一个陈述是否被给定的一手来源直接支持。

输入： 原陈述、来源 URL 或文档定位、访问日期、允许陈述和禁止外推。

输出： verified、narrow、unverified 或 inaccessible，以及支持片段的定位和解释。

副作用： 可读取来源；不自动修改正文，不把来源访问成功等同于结论正确。

最小测试： 至少覆盖完全支持、部分支持、来源不可达、访问日期缺失和动态事实过期五类输入。

选择、执行与批准分层

阶段	回答的问题	需要的证据	不能替代什么
发现	哪些 Skill 可能相关？	名称、描述、注册状态	输入检查
选择	哪个契约与任务匹配？	范围、排除条件、前置	权限批准
执行	最小动作是否完成？	工具结果、状态、错误	结果验收
验证	输出是否满足契约？	独立检查、测试、观察	外部责任
批准	是否允许影响共享或外部状态？	风险、权限、责任者	执行本身

测试矩阵

一个 Skill 至少检查以下行为轴；不需要为每个字段创建独立测试类。

1. 正常输入： 输出满足契约且证据完整。
2. 缺失输入： 停止并列出缺项，不猜测路径、ID、版本或凭证。
3. 过期与冲突： 不用新文本掩盖旧证据或状态冲突。
4. 权限不足： 返回可交接的批准请求，不绕过运行环境。
5. 外部失败： 保存错误边界，不伪造降级成功。
6. 副作用： 只读 Skill 在测试中证明没有写入；有副作用的 Skill 验证幂等、回滚和目标范围。

生命周期

生命周期状态与质量等级回答不同问题：active 只表示条目仍在发现入口中，不表示它达到 maintained、安全、获授权或适合当前任务。

• Draft： 契约可读，但尚未用固定输入验证。
• Active： 维护者、版本、测试和适用范围已登记。
• Deprecated： 保留迁移说明，不再用于新任务。
• Retired： 从发现入口移除，历史工件仍可追溯。

升级 Skill 版本时，应比较输入、输出、状态、权限和副作用契约。只改措辞但不改行为可视为文档修订；扩大写入范围、改变失败语义或新增外部依赖则必须重新验证使用者。