091b66a9bb
将角色与 Skill 从 .claude 迁入 .agent，移除 Claude CLI 运行时并接入固定 Opus 角色 profile、完整 schema、预算 deadline、raw 与回执证据链。 同步拆分 Skill 职责、复利 lesson、Gate 回放、Dashboard 人审入口、数据库登记和机械门禁；候选设计正文不包含在本提交中。
257 lines
14 KiB
Markdown
257 lines
14 KiB
Markdown
# Skill 分类与质量评分标准
|
||
|
||
> 状态：生效规范
|
||
> 适用范围：`agent-example/.agent/skills/*/`
|
||
> Owner：`agent-example/harness/`
|
||
> 本文件是开发与治理支架规范，不属于任何 Skill 的运行时提示词。
|
||
|
||
## 1. 本文件回答什么
|
||
|
||
本文件回答两个问题：**一个 Skill 站在作品创建周期的哪一段**，以及**按什么维度判断它写得好不好用**。
|
||
|
||
它拥有：Skill 分类字段的定义与取值、八个质量维度的评分锚点、严重度定义、按属性裁剪的必备章节清单。
|
||
|
||
它不拥有，只引用：
|
||
|
||
| 主题 | Owner |
|
||
|---|---|
|
||
| 证据分级、测试与行为评测边界、`SKILL.md` 禁止携带的开发测试内容 | [`skill-testing.md`](skill-testing.md) |
|
||
| 何时审、谁审、审查产出格式 | [`../../AGENTS.md`](../../AGENTS.md) 第 11 节 |
|
||
| 合同责任方与领域 SoT | `AGENTS.md` 第 3 节与 `.agent/docs/architecture/domains/` |
|
||
| 经验升格链与升格判据 | [06-质量与复利领域](../../.agent/docs/architecture/domains/06-质量与复利领域.md) §6 |
|
||
| 范式生命周期与消费合同 | [03-范式领域](../../.agent/docs/architecture/domains/03-范式领域.md) |
|
||
| 业务字段合同 | `meta/schemas/` |
|
||
|
||
评分本身属于证据分级的第一层（静态结构检查）。**高分不等于 Skill 有效**：维度 D1 的真实触发效果、D3 的实际不重叠，只能由行为评测证明。
|
||
|
||
## 2. Skill 分类
|
||
|
||
四个正交属性，全部在 [`../manifests/skills.json`](../manifests/skills.json) 逐个 Skill 声明，由 `skill_harness.py` 机械校验。
|
||
|
||
**分类不按"是不是系统运行时"划分。** 一个 Skill 当前有没有数据库合同、有没有接入复利，是它的**实现成熟度**，不是它的本质。把成熟度写成类别，等于给未完成的 Skill 发永久豁免证——曾经的 `craft` 标签就是这样让 15 个创作方法 Skill 长期停在纯文档状态的。本节的四个属性都描述可变状态，其中 `compounding` 明确记录差距，由维度 D8 计分推动补齐。
|
||
|
||
`craft` 不再作为任何分类标签使用。该词在本仓只有一个含义：公共范式库的**范式型之一**（`draft_payload->>'型' = 'craft'`，技法型，见 03-范式领域 §2）。
|
||
|
||
### 2.1 `lifecycle` —— 作品创建周期定位
|
||
|
||
取值与 [`.agent/skills/_index.md`](../../.agent/skills/_index.md) 的九个分域一一对应，每个 Skill 归它主用的那一段；跨阶段取用在索引维护，不改归属。
|
||
|
||
| 取值 | 周期段 |
|
||
|---|---|
|
||
| `platform` | 平台底座（贯穿全周期的运行支撑，不属单一创作阶段） |
|
||
| `ingest` | 素材导入与拆解 |
|
||
| `knowledge` | 知识与上下文供给 |
|
||
| `concept` | 概念与前期设计 |
|
||
| `planning` | 结构与规划 |
|
||
| `writing` | 正文写作与呈现 |
|
||
| `review` | 检测、评分与诊断 |
|
||
| `humanization` | 去 AI 味与人感 |
|
||
| `sovereignty` | 候选主权与落库 |
|
||
|
||
### 2.2 `invocation` —— 谁决定调用
|
||
|
||
| 取值 | 含义 | frontmatter 必须 |
|
||
|---|---|---|
|
||
| `orchestrated` | 只能由主会话或上游 Skill 显式调用 | 有 `disable-model-invocation: true` |
|
||
| `model_routed` | 模型读 `name` + `description` 自行决定是否使用 | 没有该字段 |
|
||
|
||
机械规则：manifest 的 `invocation` 与 frontmatter 必须一致，不一致即阻断。
|
||
|
||
**推论（重要）**："不得由 Agent 自行触发""必须由用户明确指令启动"这类禁令，只有 `orchestrated` 才算生效。写在 `description` 或红线段落里而 `invocation` 仍是 `model_routed` 的，属于合同与机制两张皮，按 D7 判 0。
|
||
|
||
### 2.3 `side_effects` —— 副作用面
|
||
|
||
数组，取值 `none` / `db_write` / `external_call`。`none` 不得与其它值并列。
|
||
|
||
声明**本 Skill 直接产生**的副作用。通过其它 Skill 间接产生的（例如经 `call-content-model` 调模型）不计入本字段，写进 `collaborates_with`。
|
||
|
||
该字段决定 D4 的必备节与 D5 的适用性和阻断性。
|
||
|
||
### 2.4 `compounding` —— 复利接入
|
||
|
||
复利指**把"这次怎么做、效果如何"的观察沉淀成可被后续运行消费的经验资产**：范式卡、AI 味规则、声音账、`example_lesson` 登记。作品事实（实体、知识卡、正文）不算经验资产，搬运素材也不算。
|
||
|
||
| 取值 | 含义 |
|
||
|---|---|
|
||
| `closed_loop` | 两侧都通：既读库内已确认 / active 的经验资产作为输入，又把本次观察或证据写回库 |
|
||
| `partial` | 只通一侧：只消费，或只产出 |
|
||
| `none` | 两侧都不通：方法与判断只活在 `SKILL.md` 与 `references/`，用过之后什么都不留下 |
|
||
|
||
判据是"读写的是不是库内经验资产"，不是"有没有 `scripts/`"。既有闭环范本是去 AI 味五技能：案例卡 → 规则候选 → holdout 评测 → active 规则 → 生成前注入。
|
||
|
||
`compounding = none` 不是合法终态，是待补齐的债，由 D8 计分。
|
||
|
||
## 3. 质量维度
|
||
|
||
八维，每维 0 / 1 / 2 分。按属性裁剪适用性，不适用的维度不计入分母。
|
||
|
||
| 维度 | 适用范围 | 阻断性 |
|
||
|---|---|---|
|
||
| D1 可发现性 | `invocation = model_routed` | 否 |
|
||
| D2 单一目的 | 全部 | 0 分阻断 |
|
||
| D3 边界与不重叠 | 全部 | 否 |
|
||
| D4 合同完整性 | 全部（必备节按属性不同） | 0 分阻断 |
|
||
| D5 失败关闭 | `side_effects ≠ [none]` 或存在 `scripts/` | 含 `db_write` 时 0 分阻断 |
|
||
| D6 上下文经济 | 全部 | 否 |
|
||
| D7 机制优先 | 全部 | 0 分阻断 |
|
||
| D8 复利接入 | `lifecycle ≠ platform` | 否 |
|
||
|
||
### D1 可发现性
|
||
|
||
模型只能读到 `name` 与 `description`，这两个字段决定该用时会不会用、不该用时会不会误用。
|
||
|
||
`description` 必须三段齐全：**做什么**（能力）、**何时用**（触发场景）、**何时不用**（交给谁）。
|
||
|
||
- **2**：三段齐全；触发场景写成用户会说的话或可观察征兆；"何时不用"点名接手的 Skill。
|
||
- **1**：缺"何时不用"，或触发场景只有抽象名词（"需要受控上下文时"）而没有可识别征兆。
|
||
- **0**：只有能力描述没有触发条件；或出现内部代号、schema 名、阶段编号而没有当场用白话解释。
|
||
|
||
长度预算：≤ 200 字符；`lifecycle` 属创作方法密集段（`concept` / `planning` / `writing` / `review`）且需要列同义触发说法的，放宽到 ≤ 1000 字符。超预算不直接扣分，但必须有行为评测证据支撑，否则该维度上限记 1。
|
||
|
||
**触发词堆砌不等于可发现性。** 同一周期段内两个 Skill 的触发词互相覆盖、而各自的"何时不用"没有点名对方的，按 D3 记问题。
|
||
|
||
### D2 单一目的
|
||
|
||
- **2**：一个动作、一个产出。
|
||
- **1**：多个动作，但共享同一产出与同一失败边界（例如同一状态机的几个入口）。
|
||
- **0**：功能并列（"备份 / 恢复 / 重置 / 修复 / 迁移"各自独立），或同时充当编排者与执行者。
|
||
|
||
### D3 边界与不重叠
|
||
|
||
单个 Skill 的纯度不等于集合无冲突。本维度同时看两件事。
|
||
|
||
- **2**：显式写出"不做什么"，并对每个易混的相邻 Skill 点名交接。
|
||
- **1**：写了"不做什么"，但没点名接手方。
|
||
- **0**：没有边界声明；或与集合内另一个 Skill 存在未声明的职责重叠。
|
||
|
||
### D4 合同完整性
|
||
|
||
必备节按属性裁剪。本节是 `SKILL.md` **必备内容**的唯一 Owner；**禁止内容**（开发测试污染）的 Owner 是 `skill-testing.md` 第 1.1 节。
|
||
|
||
全部 Skill 必备：
|
||
|
||
1. 唯一目的
|
||
2. 消费者（谁调用它）
|
||
3. 输入（字段或入参合同）
|
||
4. 输出（返回结构或产物位置）
|
||
5. 红线（禁止动作）
|
||
|
||
`side_effects` 含 `db_write` 或 `external_call` 时追加：
|
||
|
||
6. 读写的表或外部资源清单
|
||
7. 授权与预算前置
|
||
8. 落库位置与失败时的状态
|
||
|
||
`compounding` 不是 `none` 时追加：
|
||
|
||
9. 复利合同：消费哪些 active 经验资产、把什么观察写回哪张表、按什么判据进入升格链
|
||
|
||
评分：
|
||
|
||
- **2**：必备节齐全，且每节内容可直接执行。
|
||
- **1**：缺 1 节；或内容存在但散在正文，没有可定位的标题。
|
||
- **0**：缺 2 节及以上；或输出、红线之一缺失。
|
||
|
||
### D5 失败关闭
|
||
|
||
- **2**：每条失败路径有明确且可区分的失败类别，不静默降级、不返回假成功；确定性步骤明确声明不调模型。
|
||
- **1**：写了"失败时停止"，但失败类别不可区分。
|
||
- **0**：没有失败路径描述；或存在"失败时回退到 X"这类静默降级。
|
||
|
||
### D6 上下文经济
|
||
|
||
`SKILL.md` 每次被加载都占用上下文，只该放执行时必须常驻的内容。
|
||
|
||
- **2**：大块方法、样例与清单在 `references/`，可执行逻辑在 `scripts/`，正文在预算内。
|
||
- **1**：超预算不足 50%；或有明显可外移的内容仍留在正文。
|
||
- **0**：超预算 50% 以上；或正文复述了 `references/`、`scripts/` 已有的内容。
|
||
|
||
行数预算：≤ 120 行（含 frontmatter）。
|
||
|
||
`scripts/` 只放运行时确定性实现与机械门：测试归 `tests/skills/<skill>/`，工作表、清单与模板归 `references/`。
|
||
|
||
### D7 机制优先
|
||
|
||
能由 frontmatter、schema、adapter 或 `scripts/` 强制的约束，不该写成散文叮嘱。这是 `AGENTS.md` 第 11.1 节问 3 在 Skill 层的落地。
|
||
|
||
- **2**：所有可机制化的约束都已交给机制，散文只留执行者必须自行判断的部分。
|
||
- **1**：存在与机制重复的叮嘱（机制在，散文也反复写）。
|
||
- **0**：存在**只靠散文**的高危约束。典型：声明"不得由 Agent 自行触发"却是 `model_routed`；声明"只读"却提供了写库脚本；声明输出格式却没有 schema 校验。
|
||
|
||
### D8 复利接入
|
||
|
||
一个创作 Skill 用过一次之后，系统应该比上一次更强。判据不是它有多少方法，而是这些方法有没有变成库里可被后续运行消费、可被证据修正的资产。
|
||
|
||
- **2**：`compounding = closed_loop`，且 `SKILL.md` 的复利合同写清了消费什么、回写什么、按什么判据升格。
|
||
- **1**：`compounding = partial`，或虽是 `closed_loop` 但回写路径只写在散文里、没有落库位。
|
||
- **0**：`compounding = none`，方法只活在 `SKILL.md` 与 `references/`。
|
||
|
||
D8 不设阻断：接入复利是增量工程，不是正确性缺陷。但 0 分必须在审查清单里带改造方案登记，不能只记一笔。
|
||
|
||
## 4. 计分与判定
|
||
|
||
得分率 = 实得分 ÷ 适用维度满分。
|
||
|
||
| 得分率 | 判定 |
|
||
|---|---|
|
||
| ≥ 0.85 | 良好 |
|
||
| 0.70 – 0.85 | 可用待修 |
|
||
| < 0.70 | 不合格 |
|
||
|
||
任一阻断项命中，直接判**不可用**，不看得分率。
|
||
|
||
## 5. 严重度
|
||
|
||
| 级别 | 定义 | 处理时限 |
|
||
|---|---|---|
|
||
| **阻断 blocking** | 会造成错误执行、数据损坏、越权，或合同与机制两张皮 | 修复前不得继续使用该 Skill |
|
||
| **严重 major** | 会造成该用时不触发、不该用时误触发，或执行者需要反复猜测 | 下一次改动该 Skill 时必须一并修复 |
|
||
| **一般 minor** | 只增加阅读成本或未来漂移风险 | 登记，可批量修 |
|
||
|
||
阻断级别由第 3 节的阻断性列决定，不由审查者临场判断。
|
||
|
||
## 6. 机械判定范围
|
||
|
||
`skill_harness.py` 覆盖下列检查；其余维度靠人工审查，不得因为审计跑绿就声称 Skill 质量合格。
|
||
|
||
| 检查 | 对应维度 | 严重度 |
|
||
|---|---|---|
|
||
| 分类字段存在且取值合法 | 第 2 节 | 阻断 |
|
||
| `invocation` 与 frontmatter 一致 | D7 | 阻断 |
|
||
| `contract_owner` 非空 | 第 2 节 | 阻断 |
|
||
| manifest 与磁盘一一对应 | 第 2 节 | 阻断 |
|
||
| frontmatter 完整、`name` 等于目录名 | D4 | 阻断 |
|
||
| `SKILL.md` 携带开发测试内容 | `skill-testing.md` 1.1 | 阻断 |
|
||
| 必备节标题缺失 | D4 | 严重 |
|
||
| 引用的文档路径不存在 | D3 / D4 | 严重 |
|
||
| 落空的内部代号引用（`XXX §N` 而无对应文档） | D1 / D3 | 严重 |
|
||
| `description` 点名的 Skill 不存在 | D1 | 严重 |
|
||
| 同 `lifecycle` 触发词重合且双方都不点名对方 | D3 | 严重 |
|
||
| `references/*.md` 未被 `SKILL.md` 引用 | D6 | 严重 |
|
||
| `scripts/` 内存放测试文件 | D6 | 严重 |
|
||
| `scripts/` 目录存在但无可执行实现 | D6 | 严重 |
|
||
| 正文行数超预算 | D6 | 严重 / 一般 |
|
||
| `description` 超长度预算 | D1 | 严重 / 一般 |
|
||
| 单个 `references` 文件超 20 KB | D6 | 一般 |
|
||
| 同一案例范本出现在两个 Skill | D3 | 一般 |
|
||
| `compounding = none` | D8 | 严重 |
|
||
|
||
判定口径的三条边界，避免误判：
|
||
|
||
- **触发词重合**只取 `不适用于` 之前那半段。两个 Skill 都声明自己不做某事是共识，不是冲突。任一方在 `description` 里点名对方即消解。
|
||
- **代号引用**只认全大写加节号（`MERGE_PLAN §4`）这一形态。带连字符的编号（`DDL-111`）与普通业务词不在范围内；确有外部规范用该形态的登记进 `_CODENAME_ALLOWLIST`。
|
||
- **孤儿参考文件**豁免下划线开头的包内记账文件（`_coverage.md`）与 `references/` 子目录下的夹具。
|
||
|
||
明确**不做**跨 Skill 文本相似度检查：本仓 15 个方法 Skill 由 7 本写作书分批蒸馏而来，真重复是改写而非复制（实测跨 Skill 最高 Jaccard 0.223，且全部来自 `_coverage.md` 记账文件）。能命中真重复的阈值一定会被噪声淹没。共享案例范本检查是同一关切的正确工具。同理不设 `references/` 每 Skill 总量预算——那会惩罚"把大块内容外移"这个 D6 本就奖励的行为，只对单文件设上限。
|
||
|
||
严重与一般级发现记入报告的 `advisories`；默认模式不阻断退出码，**`--strict` 时一并阻断**。存量清零后仓库门禁长期开启 `--strict`（见 `AGENTS.md` §11 与本目录 `README.md`）。
|
||
|
||
## 7. 改动门禁
|
||
|
||
新增、改名或调整 Skill 分类时，必须在同一次改动内完成：
|
||
|
||
1. 同步 `harness/manifests/skills.json` 的四个分类字段；
|
||
2. 同步 `.agent/skills/_index.md`；
|
||
3. 同步 `AGENTS.md` 第 3 节领域表；绑创作 scenario 的同步 `meta/chains/`；
|
||
4. 运行 `skill_harness.py`，阻断级问题为零。
|