muse-agent-example/harness/specs/skill-quality-rubric.md

Skill 分类与质量评分标准

状态：生效规范 适用范围：agent-example/.agent/skills/*/ Owner：agent-example/harness/ 本文件是开发与治理支架规范，不属于任何 Skill 的运行时提示词。

1. 本文件回答什么

本文件回答两个问题：一个 Skill 站在作品创建周期的哪一段，以及按什么维度判断它写得好不好用。

它拥有：Skill 分类字段的定义与取值、八个质量维度的评分锚点、严重度定义、按属性裁剪的必备章节清单。

它不拥有，只引用：

主题	Owner
证据分级、测试与行为评测边界、SKILL.md 禁止携带的开发测试内容	skill-testing.md
何时审、谁审、审查产出格式	../../AGENTS.md 第 11 节
合同责任方与领域 SoT	AGENTS.md 第 3 节与 .agent/docs/architecture/domains/
经验升格链与升格判据	06-质量与复利领域 §6
范式生命周期与消费合同	03-范式领域
业务字段合同	meta/schemas/

评分本身属于证据分级的第一层（静态结构检查）。高分不等于 Skill 有效：维度 D1 的真实触发效果、D3 的实际不重叠，只能由行为评测证明。

2. Skill 分类

四个正交属性，全部在 ../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 的九个分域一一对应，每个 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，阻断级问题为零。