evaluation-methodology

评估方法

PluginEval 通过组合最多三个层级，对技能或插件进行 0 到 100 的打分。静态层级相当于一次 lint。它快速且确定性强，适合检查结构。LLM 评委层级和蒙特卡洛层级是实验性的，未经过人工标注验证，因此请将其数值视为粗略信号。关于基于 trace 的评估程序，请参阅仓库根目录下的 evals/README.md。

评委评分标准的锚点在 references/rubrics.md。针对每种反模式的修复方法以及每个维度的提示位于 references/improving-scores.md。

评估深度

深度	层级	置信度标签
quick	静态	估算
standard（score 的默认值）	静态和评委	已评估
deep（由 certify 使用）	静态、评委，以及 50 次运行的蒙特卡洛	已认证
thorough	静态、评委，以及 100 次运行的蒙特卡洛	已认证+

该标签表示实际运行的深度，而不是对照人工判断进行的检查。无论你要求何种深度，插件目录都只会应用静态层级。

静态层级（lint）

静态层级读取 SKILL.md，不进行任何模型调用。它计算七个子分数，前六个构成复合维度：

• frontmatter_quality（构成 triggering_accuracy）
• orchestration_wiring（构成 orchestration_fitness）
• progressive_disclosure、structural_completeness、token_efficiency、ecosystem_coherence
• harness_portability

harness_portability 不对应任何维度，因此它不会改变技能的复合分数。它确实占静态层级自身分数的 6%。插件的分数是基于该层级分数构建的，因此可移植性发现可能会略微降低插件的分数。其发现不计为反模式。

静态层级会标记六种反模式：OVER_CONSTRAINED、EMPTY_DESCRIPTION、MISSING_TRIGGER、BLOATED_SKILL、ORPHAN_REFERENCE 和 DEAD_CROSS_REF。每个标记会使分数降低 5%，最低降至 50% 的下限：

penalty = max(0.5, 1.0 - 0.05 * anti_pattern_count)

报告会为每个标记打印严重程度，但扣分按标记计数并忽略严重程度。

LLM 评委层级（实验性）

评委层级进行四次模型调用，并返回四个 0 到 1 的整体分数：

• triggering_accuracy：Haiku 读取描述并编写 10 个测试提示词，5 个应当触发，5 个不应当触发。它预测每个提示词的结果并报告自身的 F1。没有任何东西将这些预测与真实触发情况进行核对。
• orchestration_fitness 和 scope_calibration：Sonnet 按照五点评分标准对技能进行评分。
• output_quality：Sonnet 设想三个任务，并对其预期的输出进行评分。

三次 Sonnet 调用只会看到 SKILL.md 的前 3,000 个字符。只有一位评委运行，因为没有任何东西读取 judges 设置。

蒙特卡洛层级（实验性）

Haiku 编写 15 个应当触发该技能的提示词，该层级重复它们以达到 50 次运行（thorough 时为 100 次）。每次运行都会将 SKILL.md 文本和一个提示词发送给模型，该层级记录四项指标：

• 激活率是任何非空回复的运行占比，因此它显示的是模型是否作答，而不是该技能是否本应触发。
• 输出质量是回复长度除以 500，上限为 1.0。
• 失败率是出错的运行占比。
• Token 效率为 1 - median_tokens / 8000。

每个提示词都是应当触发的提示词，因此该层级从不检查该技能是否在不相关的请求中保持不触发。该层级的 JSON 包含其自身指标的 Wilson、bootstrap 和 Clopper-Pearson 区间。复合的 ci_lower 和 ci_upper 字段始终为 null。

综合得分

首先，对于每个维度，引擎会混合存在的层得分，并在这些层上重新归一化混合权重。其次，它会对加权后的维度得分求和，并在有得分的维度上重新归一化维度权重。第三，它将总和乘以 100 再乘以反模式惩罚。

维度	权重	静态	Judge	Monte Carlo
triggering_accuracy	0.25	0.15	0.25	0.60
orchestration_fitness	0.20	0.10	0.70	none
output_quality	0.15	none	0.40	0.60
scope_calibration	0.12	none	0.55	none
progressive_disclosure	0.10	0.80	none	none
token_efficiency	0.06	0.40	none	0.50
robustness	0.05	none	none	0.80
structural_completeness	0.03	0.90	none	none
code_template_quality	0.02	none	none	none
ecosystem_coherence	0.02	0.85	none	none

当某个层未对该维度产生得分时，单元格显示 "none"，即使 LAYER_BLENDS 列出了权重也是如此。没有任何层会产生 code_template_quality，因此它始终未被测量。对于插件目录，综合得分是静态层在该插件的技能和 Agent 上的平均得分，乘以 100，再乘以该插件反模式数量的惩罚。

徽章与等级

徽章仅由综合得分决定。Platinum 至少需要 90，Gold 至少需要 80，Silver 至少需要 70，Bronze 至少需要 60。Badge.from_scores 接受 Elo 评分，但没有任何命令会计算它。插件级徽章，包括每周 CI 报告中的徽章，仅来自静态层。在 standard 深度或更深层级下的技能级徽章也包括实验层。

每个被测量的维度都会在 0 到 100 的尺度上获得一个字母等级，从 97 的 A+ 一直到 60 的 D-，60 以下为 F。

用法

plugin-eval score ./path/to/skill --depth quick     # static lint only
plugin-eval score ./path/to/skill                   # static and judge
plugin-eval certify ./path/to/skill                 # deep depth
plugin-eval compare ./skill-a ./skill-b             # quick depth by default
plugin-eval score ./path/to/skill --depth quick --output json --threshold 70

在 standard 深度或更深层级下，score、certify 和 compare 会在 stderr 上打印一条说明，指出 judge 和 Monte Carlo 层是实验性的。对于插件目录，CLI 会改为打印一条警告，指出仅运行静态层。使用 --threshold 时，当综合得分低于该值时，命令会以代码 1 退出。plugin-eval init 会写入一个语料库索引，但没有任何其他命令会读取它。

示例

以下是一个 JSON 输出的精简示例。脚本可以从中读取 composite.score：

{
  "layers": [{"layer": "static", "score": 0.75, "sub_scores": {}, "anti_patterns": []}],
  "composite": {"score": 76.9, "ci_lower": null, "ci_upper": null, "badge": "silver",
                "confidence_label": "Estimated", "dimensions": []},
  "elo": null
}

故障排除

• 当你添加内容后得分下降时，请检查 JSON 中的 layers[0].anti_patterns。
• 如果在 quick 深度下 triggering_accuracy 较低，请在描述中添加一个触发短语，例如 "Use this skill when"，后跟几个以逗号分隔的上下文。
• Judge 得分在多次运行之间会发生变化，因为模型每次都会编写新的测试提示词和任务。如果你希望比较结果可重复，请使用静态层。
• 如果 stderr 提示 judge 无法测量某些维度，请使用 uv sync --extra llm 安装 LLM 附加组件。

相关

eval-judge Agent 会在 Claude Code 内对四个 judge 维度进行评分，而 eval-orchestrator Agent 会运行 CLI 并合并结果。