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 分钟默认 N50 次 Agent SDK 真实调用统计性质。源码中这三层的组织关系在 EvalEngine 中得到印证evaluate_skill()先无条件执行静态层再依据Depth决定是否加入 judge 层与 Monte Carlo 层。深度等级与层的映射定义在 models.pyquick只有 staticstandard为 static judgedeep与thorough为三层全开——其中thorough会把 Monte Carlo 的模拟次数从 50 提升到 100见 engine.py这是方法论文档未展开、但从源码结构中可以确认的一个更高深度档位。每一档深度还对应一个置信标签Estimated / Assessed / Certified / Certified。Layer 1 — 静态分析六个子检查与反模式惩罚静态分析器layers/static.py直接对解析后的 SKILL.md 做六个子检查子检查度量内容frontmatter_quality名称存在性、描述长度、触发短语质量orchestration_wiring输入/输出文档化程度、代码块数量、编排器反模式progressive_disclosure行数是否落在甜点区200–600 行、references/ 与 assets/ 加分项structural_completeness标题密度、代码块、Examples 章节、Troubleshooting 章节token_efficiencyMUST/NEVER/ALWAYS 密度、重复行比率ecosystem_coherence对其他 skill/agent 的交叉引用、“related”/“see also” 提及这六个子检查通过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对四个维度打分触发准确性Triggering accuracy— 基于 10 条心理测试提示5 条应触发、5 条不应触发推算 F1 分数编排适配度Orchestration fitness— 评估 skill 是否为纯 worker0–1 量规输出质量Output quality— 模拟 3 个真实任务评估指令质量范围校准Scope calibration— 判断深度与广度是否匹配其类别。评审者返回结构化 JSON不允许 markdown 围栏由评估引擎合并进综合分当judges 1时取平均并报告 Cohens 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维度权重维度权重为何重要triggering_accuracy0.25从不触发——或错误触发——的 skill 毫无价值orchestration_fitness0.20skill 必须是纯 worker监督逻辑属于 agentoutput_quality0.15正确、完整的输出是核心交付物scope_calibration0.12既不是空壳也不是臃肿巨兽progressive_disclosure0.10SKILL.md 保持精简细节放在 references/token_efficiency0.06每次调用最小化上下文浪费robustness0.05处理边界情况而不崩溃structural_completeness0.03正确的章节、正确的顺序code_template_quality0.02可复制粘贴、可运行的示例ecosystem_coherence0.02交叉引用不与兄弟 skill 重复这组权重在源码中是模块级常量 DIMENSION_WEIGHTS与文档表格逐项一致权重和为 1.0。各维度的层混合权重每个维度从不同层以不同比例取分。三层全开时--depth deep或certify的混合比例为维度静态评审Monte Carlotriggering_accuracy0.150.250.60orchestration_fitness0.100.700.20output_quality0.000.400.60scope_calibration0.300.550.15progressive_disclosure0.800.200.00token_efficiency0.400.100.50robustness0.000.200.80structural_completeness0.900.100.00code_template_quality0.300.700.00ecosystem_coherence0.850.150.00--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 将其转换为字母等级等级分数区间含义A0.90 – 1.00优秀——无需有意义的改进B0.80 – 0.89良好——只有小缺口C0.70 – 0.79及格——有一两个明确的改进点D0.60 – 0.69勉强——需要针对性工作F 0.60不及格——需要重大整改从源码结构看引擎实际使用的 _score_to_grade() 是更细的 12 档刻度A ≥ 97A ≥ 93A- ≥ 90B ≥ 87B ≥ 83B- ≥ 80C ≥ 77C ≥ 73C- ≥ 70D ≥ 67D ≥ 63D- ≥ 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含义Platinum ★★★★★≥ 90≥ 1600参考质量——可入 gold corpusGold ★★★★≥ 80≥ 1500生产可用Silver ★★★≥ 70≥ 1400功能完整仍有改进空间Bronze ★★≥ 60≥ 1300最低可用——尚不推荐给用户— 60任意未达到最低门槛当 Elo 尚未计算时即 quick 或 standard 深度、未经certifyElo 阈值检查被跳过——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 15severity 0.10。问题过度规定性的指令降低模型灵活性、增加 token 开销并暴露作者在试图 micromanage 每一次输出而不是给出原则性指引。修复审计每一处 MUST/ALWAYS/NEVER尽可能把指令式语言换成解释式表述把硬约束留给真正的安全或正确性需求。目标是每 100 行少于 10 条此类指令。EMPTY_DESCRIPTION触发frontmatter 的description字段去除空白后少于 20 字符。问题没有有意义的描述Claude Code 插件系统无法判断何时调用该 skillskill 对自动调用而言等于隐形。修复写至少 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默认参数期望得分公式标准 EloE(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% CIcompute_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/corpusCLI 实现见 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 quick2 秒内返回 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。完整认证三层 Eloplugin-eval certify ./path/to/skill跑静态 LLM 评审 Monte Carlo50 次模拟 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_count1) → ~76.5JSON 输出结构--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_accuracy0.25低——重写描述高总分 70orchestration_fitness0.20中——重组章节高skill 混有 worker supervisor 逻辑output_quality0.15中——补充示例中judge 分数 0.70scope_calibration0.12低——内容移入 references/中文件 100 或 800 行progressive_disclosure0.10低——建 references/ 目录中不存在 references/ 目录token_efficiency0.06低——减少 MUST/ALWAYS/NEVER低反模式计数 ≥ 3robustness0.05低——加 Troubleshooting 章节低未文档化边界情况处理structural_completeness0.03极低——加标题/代码块低H2 标题少于 4 个code_template_quality0.02极低——加语言标签极低代码块缺语言标签ecosystem_coherence0.02极低——加 Related 章节极低完全没有交叉引用经验法则永远先修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.15assets/固定 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考