# Skill 测试与评测规范

> 状态：生效规范
> 适用范围：`agent-example/.claude/skills/*/SKILL.md`、其确定性工具和 Skill 行为评测。
> Owner：`agent-example/harness/`
> 本文件是开发与评测支架规范，不属于任何 Skill 的运行时提示词。

## 1. 三层边界

### 1.1 Skill 运行时指令

`SKILL.md` 只描述 Agent 执行该 Skill 时必须知道的稳定合同：唯一目的、消费者、输入、输出、schema/version、允许读取、允许副作用、禁止动作、数据库读写、授权、预算、raw 和失败关闭规则，以及实际执行所需的业务工具与流程。

`SKILL.md` 不承载开发者测试说明、测试文件路径、测试框架命令、夹具细节或测试结论。

禁止在运行时 Skill 文本中出现：

- `## 自测`、`## 测试`、`## 开发验证` 等开发测试章节；
- `test_*.py`、`*_test.py`、pytest、unittest 等实现测试入口；
- “本测试通过”“测试覆盖 N 项”等开发证据；
- 把测试文件、测试常量或测试输出说成事实源或业务合同。

评测 Skill 的生产/评测执行命令可以保留，但必须是用户请求该评测时实际执行的业务步骤，而不是验证实现代码的开发测试。

### 1.2 确定性工具验证

工具验证回答“Python、数据库或状态机实现是否守住机械合同”，不回答模型是否写得好，也不证明 Skill 的自然语言指令有效。

- 单元测试、离线合同测试和数据库集成测试属于这一层；
- 项目运行时 Skill 的实现测试统一放在 `tests/skills/<skill>/`，领域包保留自己的 `tests/`；两者都必须在 harness 的开发验证清单中登记；
- 测试通过只能证明列出的机械行为，不得升级为模型质量或产品可用性结论；
- 真实数据库、网络、模型和额度探针必须显式标记并单独授权。

### 1.3 Skill 行为评测

行为评测回答“把 Skill 内容交给 Agent 后，Agent 是否按合同行动”。评测由 harness 从外部驱动，不能由 `SKILL.md` 自己宣布通过。

行为评测至少区分：

- 正向触发：应该使用该 Skill 的任务；
- 负向触发：不应该使用该 Skill 的任务；
- 输入缺失与越界；
- 输出合同与失败关闭；
- 关键禁止动作；
- 多样例稳定性和已知混淆项。

行为评测结果必须保留输入、Skill 版本指纹、模型/运行配置、输出摘要、判定证据和失败原因。小样本合同回放不等于文学质量、通用效果或生产完成。

## 2. Harness 职责

Harness 只负责从外部发现、运行、收集和裁决测试/评测证据：

1. 扫描运行时 Skill 文档中的开发测试污染；
2. 登记和分类确定性工具测试、集成测试、fake pipeline 测试和真实探针；
3. 驱动 Skill 行为评测案例；
4. 生成带证据类型和失败原因的结构化报告；
5. 防止空跑、静默跳过、宽泛异常吞错和证据级别越权。

Harness 不负责：

- 修改 `SKILL.md` 或业务代码；
- 判断文学质量；
- 用字符串出现证明自然语言合同有效；
- 把 fake、离线回放或小样本结果升级成生产结论。

## 3. 证据分级

从低到高仅表示证据类型，不允许自动跨级：

1. 静态结构检查：frontmatter、路径、禁用污染模式；
2. 确定性离线测试：纯函数、schema、状态机和失败分支；
3. 真实依赖集成测试：PostgreSQL、文件系统或外部服务；
4. Skill 行为评测：外部 Agent/模型运行与结构化裁决；
5. 人工内容评审：文学质量、声音和语义效果。

任一层通过都不能代替更高层证据。没有行为评测，不得声称 Skill 内容有效；没有真实依赖证据，不得声称生产链路可用。

## 4. 改动门禁

### 只改运行时合同

- 通过 harness 的运行时文档污染扫描；
- 更新受影响的行为评测案例，或记录只改措辞、不改变行为的理由；
- 不新增把测试细节塞回 `SKILL.md` 的说明。

### 只改确定性工具

- 更新针对变更不变量的离线测试；
- 对真实数据库、网络和模型测试单独标记；
- 保留失败关闭和副作用边界证据。

### 改变 Skill 意图或边界

- 更新行为评测清单和正/负向案例；
- 检查消费者、Agent 槽位和 `meta/chains` 映射；
- 重新执行相关层级的验证，不得只跑 Python 单测。

## 5. 明确禁止

- 用 `assertIn` 检查几个词出现，就宣称 Skill 内容正确；
- 用测试文件或测试输出作为运行时事实源；
- 用 `except Exception: pass` 把错误依赖、连接失败或实现错误当成预期拒绝；
- 用任意总入口的“零测试”结果当成通过；
- 把离线 fake、模型探针或小样本合同回放写成真实质量结论；
- 为了让 harness 变绿而修改业务合同、降低断言或静默跳过测试。

## 6. 完成定义

本治理任务只有同时满足以下条件，才可称为完成：

- 运行时 `SKILL.md` 不再携带开发测试说明；
- harness 能机械发现并阻断明显的测试污染；
- 实现测试、集成测试和 Skill 行为评测的证据类型可区分；
- 改动范围内的回归测试真实执行，失败不会被吞掉；
- 报告明确区分已验证事实、推断和未验证的模型质量假设。