agents 插件市场中的 PluginEval 质量评估方法论：三层评分、十维度加权、质量徽章与 Elo 排序

agents 插件市场中的 PluginEval 质量评估方法论：三层评分、十维度加权、质量徽章与 Elo 排序

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents

本文以 agents 仓库中plugins/plugin-eval插件的评估方法论为核心，系统讲解 PluginEval 如何度量一个 skill 的质量：三层评估流水线（静态分析、LLM 评审、Monte Carlo 模拟）、十个评分维度的权重与混合公式、质量徽章阈值、反模式惩罚与 Elo 排名算法。读完之后，你可以独立解读任何一份 PluginEval 评分报告，知道某个低分维度对应哪一层、哪些源码逻辑，并据此有针对性地改进 SKILL.md 的触发描述、结构与内容组织。

PluginEval 是 agents 这个多 harness 插件市场（面向 Claude Code、Codex、Cursor、OpenCode、GitHub Copilot 与 Google Antigravity）内置的插件质量评估框架。其方法论的权威定义位于 SKILL.md，配套的评审量规位于 rubrics.md，而本文结合plugins/plugin-eval/src/plugin_eval/下的实现源码，把文档中的公式、阈值与 CLI 操作落到可验证的源码事实上。

三层评估流水线的总体设计

PluginEval 把质量评估拆成三个互补的层。每一层对适用的维度各产生一个 0.0–1.0 的分数，后层按维度混合权重与前层叠加或混合：

• Layer 1 — 静态分析：耗时 2 秒以内，无 LLM 调用，完全确定性；
• Layer 2 — LLM 评审（Judge）：耗时 30–90 秒，一次或多次 LLM 调用（默认 Sonnet），非确定性；
• Layer 3 — Monte Carlo 模拟：耗时 5–20 分钟，默认 N=50 次 Agent SDK 真实调用，统计性质。

源码中这三层的组织关系在 EvalEngine 中得到印证：evaluate_skill()先无条件执行静态层，再依据Depth决定是否加入 judge 层与 Monte Carlo 层。深度等级与层的映射定义在 models.py：quick只有 static，standard为 static + judge，deep与thorough为三层全开——其中thorough会把 Monte Carlo 的模拟次数从 50 提升到 100（见 engine.py），这是方法论文档未展开、但从源码结构中可以确认的一个更高深度档位。每一档深度还对应一个置信标签：Estimated / Assessed / Certified / Certified+。

Layer 1 — 静态分析：六个子检查与反模式惩罚

静态分析器（layers/static.py）直接对解析后的 SKILL.md 做六个子检查：

这六个子检查通过STATIC_TO_DIMENSION映射直接喂给十个最终维度中的六个（映射定义见 engine.py）。其余四个维度——output_quality、scope_calibration、robustness以及triggering_accuracy的一部分——不接收静态层贡献，完全依赖 Layer 2 和/或 Layer 3。从源码看，static.py中还额外包含第七个子分数harness_portability（权重约 6%），用于评估 skill 在不同 harness 间的可移植性，且刻意不把它推入anti_patterns以避免同一缺陷被重复扣分（子分数损失 + 乘法惩罚双重计算）。

反模式惩罚以乘法形式作用于 Layer 1 分数：

penalty = max(0.5, 1.0 − 0.05 × anti_pattern_count)

每多检测到一个反模式，分数减少 5%，下限 50%。该函数在源码中实现为 anti_pattern_penalty()，与文档公式逐字一致。

Layer 2 — LLM 评审：四个维度的锚定量规打分

eval-judgeagent（定义于 agents/eval-judge.md）读取 SKILL.md 及references/文件后，用锚定量规（完整量规见 references/rubrics.md）对四个维度打分：

1. 触发准确性（Triggering accuracy）— 基于 10 条心理测试提示（5 条应触发、5 条不应触发）推算 F1 分数；
2. 编排适配度（Orchestration fitness）— 评估 skill 是否为纯 worker（0–1 量规）；
3. 输出质量（Output quality）— 模拟 3 个真实任务，评估指令质量；
4. 范围校准（Scope calibration）— 判断深度与广度是否匹配其类别。

评审者返回结构化 JSON（不允许 markdown 围栏），由评估引擎合并进综合分；当judges > 1时取平均并报告 Cohen's kappa 作为评审间一致性指标。从源码看，judge 层通过query_llm()（judge.py）以 Agent SDK 调用 Claude，模型分 haiku/sonnet/opus 三档，默认 sonnet；调用失败时降级为unmeasured标记而不抛出异常，保证整场评估不会因单次 LLM 故障崩溃。配置项EvalConfig.judges限定在 1–5 之间（models.py）。

Layer 3 — Monte Carlo 模拟：统计可靠性

Monte Carlo 层把 N 条真实提示（默认 50 条，由 engine.py 确认）跑过 skill 并记录四项统计：

• 激活率（Activation rate）— 触发 skill 的提示占比，附 Wilson 置信区间；
• 输出一致性（Output consistency）— 质量分数的变异系数 CV，附 bootstrap 置信区间；
• 失败率（Failure rate）— 错误/崩溃占比，附 Clopper-Pearson 精确置信区间；
• Token 效率（Token efficiency）— 中位 token 数、IQR、离群值数量。

Layer 3 的综合公式：

mc_score = 0.40 × activation_rate + 0.30 × (1 − min(1.0, CV)) + 0.20 × (1 − failure_rate) + 0.10 × efficiency_norm

其中efficiency_norm = max(0, 1 − median_tokens / 8000)。monte_carlo.py 中的实现与公式完全一致，token 上限 8000 定义在 monte_carlo.py 的TOKEN_CAP常量。一个值得注意的实现细节：出错的运行不会计入“激活”——错误运行携带的是诊断文本而非 skill 输出，若计入会虚高激活率，使该指标与输出一致性、token 效率两项（均已剔除错误运行）产生矛盾。

十维度综合评分公式

最终分数是对每个维度先做跨层加权混合、再加权求和：

composite = Σ(dimension_weight × blended_dimension_score) × 100 × anti_pattern_penalty

维度权重

这组权重在源码中是模块级常量 DIMENSION_WEIGHTS，与文档表格逐项一致，权重和为 1.0。

各维度的层混合权重

每个维度从不同层以不同比例取分。三层全开时（--depth deep或certify）的混合比例为：

--depth standard（静态 + 评审）时，Monte Carlo 列被丢弃并对剩余权重归一化；--depth quick（仅静态）时权重全部落在 Layer 1。源码中这组比例即 LAYER_BLENDS 常量。

混合分的归一化计算

对给定深度下维度d的混合分为：

blended[d] = Σ( layer_weight[d][layer] × layer_score[d][layer] ) ───────────────────────────────────────────────────── Σ( layer_weight[d][layer] for available layers )

分母只统计“当前深度下实际有分数的层”，保证 standard 深度跳过 Monte Carlo 时不会人为压低分数。EvalEngine._blend_layer_scores() 实现了这一归一化，并且对“所有可用层混合权重之和为 0”的维度退化为简单平均；对完全无数据的维度用 -1.0 哨兵标记为“未测量”，在综合分时被剔除并对其余维度的权重再做一次归一化（engine.py），这解释了为什么 quick 深度下的分数不会因为缺少 judge/MC 数据而被拉低。

如何解读维度分数

每个维度分数是[0.0, 1.0]区间内的浮点数，CLI 将其转换为字母等级：

从源码结构看，引擎实际使用的 _score_to_grade() 是更细的 12 档刻度（A+ ≥ 97，A ≥ 93，A- ≥ 90，B+ ≥ 87，B ≥ 83，B- ≥ 80，C+ ≥ 77，C ≥ 73，C- ≥ 70，D+ ≥ 67，D ≥ 63，D- ≥ 60，其余为 F），上表是其按 10 分档归并后的粗粒度视图；两种解读结论一致：先看“低分 × 高权重”的组合。

读报告时应优先关注权重最高且等级最低的维度。triggering_accuracy（权重 0.25）的一个 D，代价远大于ecosystem_coherence（权重 0.02）的一个 D。

置信区间在 Layer 2 或 Layer 3 运行时出现在报告中。窄 CI（±5 分以内）表示分数稳定；宽 CI 提示不一致性——常见原因是描述含糊，或指令只适配某些提示风格。

质量徽章

徽章要求同时满足综合分阈值和Elo 阈值（当 Elo 可用时）。Badge.from_scores() 的逻辑是先检查综合分，若提供了 Elo 再检查 Elo：

当 Elo 尚未计算时（即 quick 或 standard 深度、未经certify），Elo 阈值检查被跳过——elo is None时仅凭综合分即可获得徽章，这一分支直接体现在from_scores()的(elo is None or elo >= elo_min)条件中。

反模式标志：触发条件、问题与修复

静态分析器检测到的反模式各自携带严重度系数，进入惩罚公式。文档正文提到“five anti-patterns”并随后逐一展开；对照 static.py 的_detect_skill_anti_patterns()，实际落地的标志有六个，全部逐一说明。

OVER_CONSTRAINED

触发：SKILL.md 中 MUST、ALWAYS、NEVER 出现超过 15 次（阈值常量_OVER_CONSTRAINED_THRESHOLD = 15，severity 0.10）。

问题：过度规定性的指令降低模型灵活性、增加 token 开销，并暴露作者在试图 micromanage 每一次输出，而不是给出原则性指引。

修复：审计每一处 MUST/ALWAYS/NEVER，尽可能把指令式语言换成解释式表述；把硬约束留给真正的安全或正确性需求。目标是每 100 行少于 10 条此类指令。

EMPTY_DESCRIPTION

触发：frontmatter 的description字段去除空白后少于 20 字符。

问题：没有有意义的描述，Claude Code 插件系统无法判断何时调用该 skill，skill 对自动调用而言等于隐形。

修复：写至少 60–120 字符的描述，包含一个 “Use this skill when...” 或 “Use when...” 触发子句，以及两个以上用逗号或 “or” 分隔的具体场景。

MISSING_TRIGGER

触发：描述中不含 “use when”、“use this skill when”、“use proactively” 或 “trigger when”（大小写不敏感）。

问题：即使描述再长，若缺少明确的触发信号，对自动调用也无用——路由模型需要显式线索。

修复：在描述开头加上 “Use this skill when...”，后接具体场景，例如："Use this skill when measuring plugin quality, interpreting score reports, or explaining badge thresholds to a team."

从源码看，实际的正则比文档列举的更宽：_TRIGGER_PATTERN 还接受第三人称规范形式（“This skill should be used when...”、“Used when...”）、时间前置形式（“Use after...”、“Use before...”）、自文档化形式（“Auto-loads when...”）等；同时 _skill_uses_description_trigger() 会跳过声明disable-model-invocation: true（仅斜杠调用）或带paths:frontmatter（路径触发自动加载）的 skill——这些 skill 的触发机制不走描述，不应因缺少描述级触发短语被罚分。

BLOATED_SKILL

触发：SKILL.md 超过 800 行（常量_BLOATED_LINE_THRESHOLD = 800）且没有references/目录。

问题：单文件巨石 skill 迫使每次调用都把整份文档塞进上下文，把 token 浪费在只有边界情况才需要的内容上。

修复：创建references/目录，把支撑材料移出去：详细量规 →references/rubrics.md、扩展示例 →references/examples.md、配置参考 →references/config.md。SKILL.md 用text链接到这些文件，让模型按需取用。

ORPHAN_REFERENCE

触发：SKILL.md 包含形如text的 markdown 链接，但filename在references/目录中不存在。检测逻辑即对正文做(references/...)正则提取后与现存文件比对（static.py）。

问题：死链浪费本就不会解析成功的上下文 token，并混淆模型。

修复：要么创建缺失的参考文件，要么删除死链。

DEAD_CROSS_REF

触发：SKILL.md 通过相对路径引用了另一个 skill 或 agent，且该路径无法从skills/目录解析（含sub-skills/前缀的回退解析）。

问题：断掉的生态链接损害插件的连贯性分数，并可能导致模型尝试导航到不存在的文件。

修复：确认被引用 skill 存在；更新路径或移除引用。

Elo 排名

PluginEval 用 Elo/Bradley-Terry 评分系统让一个 skill 与 gold corpus 做两两对比排名。核心参数与公式在 elo.py 中实现：

• 初始评级：1500（按惯例取语料库中位数）；
• K 因子：32（中等 stakes 评级的标准值，EloCalculator默认参数）；
• 期望得分公式（标准 Elo）：

E(A vs B) = 1 / (1 + 10^((B_rating − A_rating) / 400))

• 每场对比后的评级更新：

new_rating = old_rating + 32 × (actual_score − expected_score)

其中actual_score在胜、平、负时分别为 1.0、0.5、0.0。

置信区间通过 500 次 bootstrap 重采样对比对计算，报告为 95% CI（compute_rating_with_ci() 取排序后样本的 2.5% 与 97.5% 分位）。语料库百分位反映对 gold corpus 的两两胜率。位置偏差检查：每对以两个顺序各评估一次，不一致的对会被标记（EloMatchup.position_bias_check字段定义于 models.py）。

plugin-eval init命令从 plugins 目录构建语料库索引：

plugin-eval init ./plugins --corpus-dir ~/.plugineval/corpus

CLI 实现见 cli.py，初始化成功后会打印语料库中的 skill 数量。Elo 排名可用之前必须先完成该步骤。

CLI 实战参考

以下命令与 README.md 的 Quick Start 一致；在plugins/plugin-eval目录下通过uv sync安装依赖后，可用uv run plugin-eval ...或直接使用plugin-eval。

只跑静态分析的快速评分

plugin-eval score ./path/to/skill --depth quick

2 秒内返回 Layer 1 结果，适合写作过程中获取快速反馈。

带 LLM 评审的评分（默认）

plugin-eval score ./path/to/skill

跑静态 + LLM 评审（standard 深度），耗时 30–90 秒。

以 JSON 输出完整结果

plugin-eval score ./path/to/skill --output json

输出结构化 JSON，含composite.score、composite.dimensions与layers[0].anti_patterns，适合 CI 集成：

plugin-eval score ./path/to/skill --depth quick --output json --threshold 70 # 分数低于 70 时以退出码 1 结束

--threshold选项的行为在 cli.py 中实现：result.composite.score < threshold时返回退出码 1。

完整认证（三层 + Elo）

plugin-eval certify ./path/to/skill

跑静态 + LLM 评审 + Monte Carlo（50 次模拟）+ Elo 排名，耗时 15–20 分钟，并分配质量徽章（certify 内部以 deep 深度调用 score 流程）。发布 skill 到市场之前应使用。

头对头对比

plugin-eval compare ./skill-a ./skill-b

以 quick 深度评估两个 skill 并打印逐维度对比表，适合在两种实现之间做取舍，或度量重写前后的改进。

初始化 Elo 语料库

plugin-eval init ./plugins

在~/.plugineval/corpus构建本地语料库索引。Elo 排名可用之前必须先执行。

用脚本复现综合分公式

在 pre-commit hook 或 CI 门禁中离线复现综合分：

def composite_score(dimension_scores: dict, anti_pattern_count: int = 0) -> float: """Replicate the PluginEval composite formula.""" WEIGHTS = { "triggering_accuracy": 0.25, "orchestration_fitness": 0.20, "output_quality": 0.15, "scope_calibration": 0.12, "progressive_disclosure": 0.10, "token_efficiency": 0.06, "robustness": 0.05, "structural_completeness":0.03, "code_template_quality": 0.02, "ecosystem_coherence": 0.02, } raw = sum(WEIGHTS[d] * s for d, s in dimension_scores.items()) penalty = max(0.5, 1.0 - 0.05 * anti_pattern_count) return round(raw * 100 * penalty, 2) # Example: a skill with a weak triggering score scores = { "triggering_accuracy": 0.65, # D — needs description work "orchestration_fitness": 0.85, "output_quality": 0.80, # … fill in remaining 7 dimensions … } # composite_score(scores, anti_pattern_count=1) → ~76.5

JSON 输出结构

--output json的顶层形状：

{ "composite": { "score": 76.5, "badge": "Silver", "elo": null }, "dimensions": { "triggering_accuracy": { "score": 0.65, "grade": "D", "ci_low": 0.60, "ci_high": 0.70 }, "orchestration_fitness": { "score": 0.85, "grade": "B", "ci_low": 0.80, "ci_high": 0.90 } }, "layers": [ { "name": "static", "duration_ms": 1243, "anti_patterns": ["OVER_CONSTRAINED"] }, { "name": "judge", "duration_ms": 48200, "judges": 1, "kappa": null } ] }

在 CI 中解析composite.score做部署门禁：

score=$(plugin-eval score ./my-skill --output json | python3 -c "import sys,json; print(json.load(sys.stdin)['composite']['score'])") if (( $(echo "$score < 70" | bc -l) )); then echo "Quality gate failed: score $score < 70" exit 1 fi

提升 skill 分数的指南

按权重顺序处理各维度，最大收益来自先修最高权重的维度。

该先修哪个维度

当评分报告出现多个 D/F 等级时，用这张表排定努力优先级：

经验法则：永远先修triggering_accuracy——权重 0.25 意味着它每小时带来的综合分收益超过所有低权重维度之和。

分维度修复要点

触发准确性（0.25）

• 包含 “Use this skill when...” 加 3–4 个逗号分隔的具体场景；
• 若 skill 应在无显式请求时自动激活，加上 “proactively”；
• 心理测试：写 5 条应触发、5 条不应触发的提示——你的描述能区分开吗？不能就增补或收紧场景短语。

编排适配度（0.20）

• 文档化 skill接收什么、返回什么——而不是它编排什么；
• 避免在 SKILL.md 中出现 “orchestrate”、“coordinate”、“dispatch”、“manage workflow”；
• 包含 “Output format” 章节与 2+ 个展示具体 worker 行为的代码块。

输出质量（0.15）

• 给具体、可执行的指令，而不只是目标；
• 至少显式覆盖一个边界情况（空输入、畸形数据等）；
• 包含展示代表性输入与预期输出的 examples 章节；
• 指令越具体，judge 在该维度打分越高。

范围校准（0.12）

• 目标 200–600 行；低于 100 行是空壳，高于 800 行且没有references/是臃肿；
• 把背景阅读、扩展示例、参考表移到references/；
• 过窄的 skill 应与兄弟 skill 合并，过宽的应拆分。

渐进披露（0.10）

• 加references/目录（得 0.15–0.25 加分），SKILL.md 聚焦执行路径；assets/目录再加一分。从源码看，行数落在 200–600 甜点区得 0.60 基础分，references/加分随文件规模变化（>400 行得 0.25，否则 0.15），assets/固定 0.15（_score_progressive_disclosure()）。

Token 效率（0.06）

• 审计 MUST/ALWAYS/NEVER 计数，目标每 10 行少于 1 条；
• 合并近重复的 bullet 与重复结构表格。

健壮性（0.05）

• 加 “Troubleshooting” 或 “Edge Cases” 章节，覆盖至少 3 种失败模式；
• 说明任务无法完成时 skill 返回什么。

结构完整性（0.03）

• 确保至少 4 个 H2/H3 标题、3 个代码块、Examples 章节与 Troubleshooting 章节。

代码模板质量（0.02）

• 所有代码块语法有效、带语言标签、可直接复制粘贴运行。

生态连贯性（0.02）

• 加 “## Related” 章节，用相对路径列出兄弟 skill 或 agent；
• 不要复制已存在于其他 skill 的内容——改为链接。

常见问题的故障排查

“加了内容之后分数反而比预期低”

反模式惩罚是乘法复合的。用--output json运行并检查layers[0].anti_patterns。若有 5 个以上反模式，乘数可把分数压到原始值的 75%——无论内容多好。先修标志，再看内容。

“描述写得很长，triggering_accuracy 却很低”

_description_pushiness打分器寻找的是特定句法模式，而非仅仅是长度。源码中 _description_pushiness() 的得分构成是：规范触发短语 0.25、含 “proactively” 0.15、含 automatically/invoke 等触发关键词 0.10、3 个以上具体场景（以逗号或 “or” 分隔）0.20、具体上下文/文件类型 0.15、长度 ≥ 40 字符 0.10。确认描述含 “Use this skill when” 或 “Use when”（正则匹配，措辞要精确），并检查是否有多个以逗号或 “or” 分隔的用途以拿到具体性加分。

“LLM judge 的分数在多次运行之间波动很大”

对含糊的 skill 这是预期行为。judge 非确定性地生成 10 条心理测试提示。收紧描述、增加具体示例可提高分数稳定性；judges > 1时平均分更稳；也可以--depth deep配合certify跑 Monte Carlo 得到统计上有界分数。

“文件长度合适，progressive_disclosure 分数却低”

确认文件是否在 200–600 行甜点区——低于 100 行的文件该子检查只得 0.20。同时确认references/文件非空：打分器检查的是非空的参考文件，而不只是目录存在。

“compare 显示我的重写版比原版分低”

quick 深度只跑静态分析。如果重写把内容移进了references/并大幅缩短 SKILL.md，结构完整性的静态分可能下降，尽管总体质量提升了。跑--depth standard做包含 LLM 评审的内容质量评估，对比更公平。

延伸阅读

• SKILL.md（方法论权威定义） — 本文的主体文档，含三层结构、权重表、徽章与反模式定义；
• rubrics.md（四维度完整锚定量规） — judge 四个维度 0.0–1.0 的五个锚点，以及各 skill 类别的行数校准基准；
• engine.py — 维度权重、层混合、归一化与综合分组装的完整实现；
• static.py / judge.py / monte_carlo.py — 三个评估层的实现；
• eval-judge.md — Layer 2 评审 agent 的定义，需要单独重跑 judge 层或查看其推理时直接调用；
• eval-orchestrator.md — 顶层编排 agent，负责串联三层、合并结果、分配徽章并写最终报告；
• docs/plugin-eval.md — 仓库级完整参考文档，覆盖层、维度、公式、反模式与统计方法。

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents