evaluation-methodology

用途

Evaluation methodology 技能用于理解 PluginEval 如何衡量插件或技能的质量，包括评估的维度、评分标准（rubric）和评分公式。它面向希望了解“插件质量如何被度量”、以及希望改进自身评分的用户。

总体评分方式

PluginEval 对一个技能或插件按 0 到 100 打分，最多组合三层。静态层（static）是 lint，速度快、确定性强，适合检查结构。LLM 评审层（judge）与 Monte Carlo 层是实验性的，未经人类标注验证，因此其数值只能当作粗略信号。基于 trace 的评估程序见仓库根目录的 evals/README.md。评审的评分标准锚点位于 references/rubrics.md，针对每种反模式的修复方法与每个维度的提示位于 references/improving-scores.md。

评估深度

quick：仅静态层，置信度标签为 Estimated
standard（score 的默认值）：静态层 + 评审层，标签为 Assessed
deep（certify 使用）：静态层 + 评审层 + 50 次运行的 Monte Carlo，标签为 Certified
thorough：静态层 + 评审层 + 100 次运行的 Monte Carlo，标签为 Certified+

标签名称表示运行了哪个深度，而不是与人类判断的对照。插件目录无论请求哪种深度，都只运行静态层。

静态层（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 设置。

Monte Carlo 层（实验性）

Haiku 写出 15 条应触发该技能的提示，该层将其重复以达到 50 次运行（thorough 为 100 次）。每次运行把 SKILL.md 文本和一条提示发给模型，记录四项度量：

Activation rate：任何非空回复的运行占比，反映模型是否作答，而非技能是否本应触发。
Output quality：回复长度除以 500，上限为 1.0。
Failure rate：出错的运行占比。
Token efficiency：1 - median_tokens / 8000。

每条提示都是应触发的，因此该层从不检查技能是否回避了无关请求。该层的 JSON 包含其自身度量的 Wilson、bootstrap 和 Clopper-Pearson 区间。合成分数中的 ci_lower 与 ci_upper 字段始终为 null。

合成分数

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

各维度权重及静态/评审/Monte Carlo 层混合权重：

triggering_accuracy：权重 0.25，静态 0.15、评审 0.25、Monte Carlo 0.60
orchestration_fitness：权重 0.20，静态 0.10、评审 0.70、Monte Carlo 无
output_quality：权重 0.15，静态无、评审 0.40、Monte Carlo 0.60
scope_calibration：权重 0.12，静态无、评审 0.55、Monte Carlo 无
progressive_disclosure：权重 0.10，静态 0.80、评审无、Monte Carlo 无
token_efficiency：权重 0.06，静态 0.40、评审无、Monte Carlo 0.50
robustness：权重 0.05，静态无、评审无、Monte Carlo 0.80
structural_completeness：权重 0.03，静态 0.90、评审无、Monte Carlo 无
code_template_quality：权重 0.02，三层均无
ecosystem_coherence：权重 0.02，静态 0.85、评审无、Monte Carlo 无

单元格为“无”表示该层不为该维度产生分数，即使 LAYER_BLENDS 列出了权重。没有任何层产生 code_template_quality，因此它始终未被度量。对于插件目录，合成分数是插件各技能与代理的静态层平均分乘以 100，再乘以插件反模式数量的惩罚。

徽章与等级

徽章仅来自合成分数：Platinum 至少 90，Gold 至少 80，Silver 至少 70，Bronze 至少 60。Badge.from_scores 接受 Elo 评分，但没有命令会计算它。插件级徽章（包括每周 CI 报告中的徽章）仅来自静态层。标准深度及更深的技能级徽章还包含实验性层。

每个被度量的维度在 0 到 100 分区间获得字母等级，从 97 的 A+ 直到 60 的 D-，60 以下为 F。

使用方式

plugin-eval score ./path/to/skill --depth quick # 仅静态 lint plugin-eval score ./path/to/skill # 静态 + 评审 plugin-eval certify ./path/to/skill # deep 深度 plugin-eval compare ./skill-a ./skill-b # 默认 quick 深度 plugin-eval score ./path/to/skill --depth quick --output json --threshold 70

在标准深度或更深时，score、certify 和 compare 会在 stderr 打印提示，说明评审层与 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”，后接若干以逗号分隔的上下文。
评审分数会在不同运行之间变化，因为模型每次都会写出新的测试提示和任务。需要可重复比较时使用静态层。
若 stderr 提示评审无法度量某些维度，用 uv sync --extra llm 安装 LLM 附加组件。