PluginEval 质量方法论——维度、评分标准、统计方法和评分公式。当需要理解插件质量如何衡量、解读某个维度的低分、决定如何提高技能的触发准确性或编排适配性、为市场校准评分阈值，或向 Neon 等外部合作伙伴解释质量徽章时，使用此技能。
评估方法论
本文档是 PluginEval 如何衡量插件和技能质量的权威参考。它涵盖了三个评估层、所有十个评分维度、复合公式、徽章阈值、反模式标志、Elo 排名以及可操作的改进建议。
相关：完整评分标准锚点
三个评估层
PluginEval 堆叠了三个互补的层。每一层为每个适用维度生成 0.0 到 1.0 之间的分数，后续层会根据每个维度的混合权重覆盖或与早期层混合。
第 1 层——静态分析
速度： < 2 秒。无需 LLM 调用。确定性。
静态分析器（layers/static.py）对解析后的 SKILL.md 直接运行六项子检查：
| 子检查 | 衡量内容 |
|---|---|
frontmatter_quality |
名称存在性、描述长度、触发短语质量 |
orchestration_wiring |
输出/输入文档、代码块数量、编排器反模式 |
progressive_disclosure |
行数与最佳区间（200–600 行）、references/ 和 assets/ 奖励 |
structural_completeness |
标题密度、代码块、示例部分、故障排除部分 |
token_efficiency |
MUST/NEVER/ALWAYS 密度、重复行重复率 |
ecosystem_coherence |
对其他技能/代理的交叉引用、“相关”/“另见”提及 |
这六项子检查直接映射到十个最终维度中的六个（通过 STATIC_TO_DIMENSION 映射）。其余四个维度——output_quality、scope_calibration、robustness 和部分 triggering_accuracy——没有静态贡献，完全依赖第 2 层和/或第 3 层。
反模式惩罚以乘法方式应用于第 1 层分数：
penalty = max(0.5, 1.0 − 0.05 × anti_pattern_count)
每检测到一个额外的反模式，分数降低 5%，最低降至 50%。
第 2 层——LLM 评判器
速度： 30–90 秒。一次或多次 LLM 调用（默认 Sonnet）。非确定性。
eval-judge 代理读取 SKILL.md 和任何 references/ 文件，然后使用锚定评分标准（参见 references/rubrics.md）对四个维度进行评分：
- 触发准确性——基于 10 个心理测试提示的 F1 分数
- 编排适配性——工作器纯度评估（0–1 评分标准）
- 输出质量——模拟 3 个实际任务；评估指令质量
- 范围校准——判断相对于技能类别的深度和广度
评判器返回一个结构化的 JSON 对象（无 markdown 围栏），评估引擎将其合并到复合分数中。当 judges > 1 时，分数取平均值，并报告 Cohen's kappa 作为评判者间一致性指标。
第 3 层——蒙特卡洛模拟
速度： 5–20 分钟。N=50 次模拟 Agent SDK 调用（默认）。统计性。
蒙特卡洛运行 N 个真实提示通过技能，并记录：
- 激活率——触发技能的提示比例
- 输出一致性——质量分数的变异系数 (CV)
- 失败率——错误/崩溃比例，附带 Clopper-Pearson 精确置信区间
- Token 效率——中位数 token 数、四分位距、异常值数量
第 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)。
复合评分公式
最终分数是每个维度在所有三个层上的加权混合，然后求和：
composite = Σ(dimension_weight × blended_dimension_score) × 100 × anti_pattern_penalty
维度权重
| 维度 | 权重 | 重要性 |
|---|---|---|
triggering_accuracy |
0.25 | 从不触发或错误触发的技能毫无价值 |
orchestration_fitness |
0.20 | 技能必须是纯粹的工作器；监督逻辑属于代理 |
output_quality |
0.15 | 正确、完整的输出是主要交付物 |
scope_calibration |
0.12 | 既不是存根也不是臃肿的怪物 |
progressive_disclosure |
0.10 | SKILL.md 精简；细节在 references/ 中 |
token_efficiency |
0.06 | 每次调用最小化上下文浪费 |
robustness |
0.05 | 处理边缘情况而不崩溃 |
structural_completeness |
0.03 | 正确的部分按正确顺序排列 |
code_template_quality |
0.02 | 可工作、可复制粘贴的示例 |
ecosystem_coherence |
0.02 | 交叉引用；不与同级重复 |
层混合权重
每个维度以不同比例从不同层获取数据。当所有三个层都激活时（--depth deep 或 certify）：
| 维度 | 静态 | 评判器 | 蒙特卡洛 |
|---|---|---|---|
triggering_accuracy |
0.15 | 0.25 | 0.60 |
orchestration_fitness |
0.10 | 0.70 | 0.20 |
output_quality |
0.00 | 0.40 | 0.60 |
scope_calibration |
0.30 | 0.55 | 0.15 |
progressive_disclosure |
0.80 | 0.20 | 0.00 |
token_efficiency |
0.40 | 0.10 | 0.50 |
robustness |
0.00 | 0.20 | 0.80 |
structural_completeness |
0.90 | 0.10 | 0.00 |
code_template_quality |
0.30 | 0.70 | 0.00 |
ecosystem_coherence |
0.85 | 0.15 | 0.00 |
在 --depth standard（仅静态 + 评判器）下，混合权重重新归一化以去除蒙特卡洛列。在 --depth quick（仅静态）下，所有权重落在第 1 层。
混合分数计算
对于给定深度，维度 d 的混合分数为：
blended[d] = Σ( layer_weight[d][layer] × layer_score[d][layer] )
─────────────────────────────────────────────────────
Σ( layer_weight[d][layer] for available layers )
这种归一化确保在标准深度下跳过蒙特卡洛不会人为地降低分数。
解读维度分数
每个维度分数是 [0.0, 1.0] 范围内的浮点数。CLI 将其转换为字母等级：
| 等级 | 分数范围 | 含义 |
|---|---|---|
| A | 0.90 – 1.00 | 优秀——无需有意义的改进 |
| B | 0.80 – 0.89 | 良好——仅有微小差距 |
| C | 0.70 – 0.79 | 合格——有一两个明确的改进领域 |
| D | 0.60 – 0.69 | 边缘——需要针对性工作 |
| F | < 0.60 | 不及格——需要重大修正 |
阅读报告时，首先关注权重最高的最低等级维度。triggering_accuracy（权重 0.25）的 D 等级比 ecosystem_coherence（权重 0.02）的 D 等级代价大得多。
置信区间在第 2 层或第 3 层运行时出现在报告中。窄置信区间（± < 5 分）表示分数稳定。宽置信区间表明不一致——通常由模糊的描述或仅适用于某些提示风格而非其他风格的指令引起。
质量徽章
徽章需要同时满足复合分数阈值和 Elo 阈值（当 Elo 可用时）。Badge.from_scores() 逻辑首先检查复合分数，然后检查 Elo（如果提供）：
| 徽章 | 复合分数 | Elo | 含义 |
|---|---|---|---|
| 铂金 ★★★★★ | ≥ 90 | ≥ 1600 | 参考质量——适合黄金语料库 |
| 金 ★★★★ | ≥ 80 | ≥ 1500 | 生产就绪 |
| 银 ★★★ | ≥ 70 | ≥ 1400 | 功能可用，有改进机会 |
| 铜 ★★ | ≥ 60 | ≥ 1300 | 最低可行——暂不建议用户使用 |
| — | < 60 | 任意 | 未达到最低标准 |
当 Elo 尚未计算时（即在 quick 或 standard 深度下未使用 certify），跳过 Elo 阈值。在这种情况下，技能可以仅凭复合分数获得徽章。
反模式标志
静态分析器检测五种反模式。每种都有严重性乘数，影响惩罚公式。
OVER_CONSTRAINED
触发条件： SKILL.md 中 MUST、ALWAYS 或 NEVER 出现超过 15 次。
问题： 过度规定的指令降低了模型灵活性，增加了 token 开销，并表明作者试图微观管理每个输出，而不是提供原则性指导。
修复： 审计每个 MUST/ALWAYS/NEVER。尽可能用解释性框架替换指令性语言。将硬约束保留给真正的安全或正确性要求。目标每 100 行少于 10 个此类指令。
EMPTY_DESCRIPTION
触发条件： 前置元数据 description 字段在去除空白后少于 20 个字符。
问题： 没有有意义的描述，Claude Code 插件系统无法确定何时调用该技能。该技能对自主调用变得不可见。
修复： 编写至少 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.”
BLOATED_SKILL
触发条件： SKILL.md 超过 800 行且技能没有 references/ 目录。
问题： 单一的 SKILL.md 迫使整个文档在每次调用时进入上下文，浪费 token 在仅在边缘情况下需要的内容上。
修复： 创建 references/ 目录并将支持材料移到那里：
- 详细评分标准 →
references/rubrics.md - 扩展示例 →
references/examples.md - 配置参考 →
references/config.md
SKILL.md 应使用 [text](references/filename.md) 链接到这些文件，以便模型按需获取。
ORPHAN_REFERENCE
触发条件： SKILL.md 包含 markdown 链接 [text](references/filename)，其中 filename 在 references/ 目录中不存在。
问题： 死链接浪费 token 在永远不会解析的上下文上，并混淆模型。
修复： 创建缺失的引用文件或删除死链接。
DEAD_CROSS_REF
触发条件： SKILL.md 通过相对路径引用另一个技能或代理，且该路径无法从 skills/ 目录解析。
问题： 断裂的生态系统链接削弱了插件的连贯性分数，并可能导致模型尝试导航到不存在的文件。
修复： 验证引用的技能存在。更新路径或删除引用。
Elo 排名
PluginEval 使用 Elo/Bradley-Terry 评分系统将技能与黄金语料库进行排名。
起始评分： 1500（按惯例为语料库中位数）。
K 因子： 32（中等风险评分的标准值）。
期望分数公式（标准 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 次自助法计算，报告为 95% CI。
语料库百分位数反映对黄金语料库的成对胜率。
位置偏差检查： 成对评估按两种顺序进行；不一致之处会被标记。
plugin-eval init 命令从插件目录构建语料库索引：
plugin-eval init ./plugins --corpus-dir ~/.plugineval/corpus
CLI 参考
对技能评分（仅快速静态分析）
plugin-eval score ./path/to/skill --depth quick
在 < 2 秒内返回第 1 层结果。适用于编写期间的快速反馈。
使用 LLM 评判器评分（默认）
plugin-eval score ./path/to/skill
运行静态 + LLM 评判器（标准深度）。耗时 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
完整认证（所有三个层 + Elo）
plugin-eval certify ./path/to/skill
运行静态 + LLM 评判器 + 蒙特卡洛（50 次模拟）+ Elo 排名。耗时 15–20 分钟。分配质量徽章。在将技能发布到市场之前使用。
头对头比较
plugin-eval compare ./skill-a ./skill-b
以 quick 深度评估两个技能，并打印逐维度比较表。用于在两个实现之间做决定，或衡量重写前后的改进。
初始化 Elo 语料库
plugin-eval init ./plugins
在 ~/.plugineval/corpus 构建本地语料库索引。在 Elo 排名工作之前需要。
脚本化复合公式
离线重现复合分数（pre-commit 钩子、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)
# 示例：一个触发分数较弱的技能
scores = {
"triggering_accuracy": 0.65, # D — 需要描述工作
"orchestration_fitness": 0.85,
"output_quality": 0.80,
# … 填写其余 7 个维度 …
}
# 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
提高技能分数的技巧
按权重顺序处理维度。最大的收益来自首先修复权重最高的维度。
首先改进哪个维度
当分数报告显示多个 D/F 等级且需要优先安排工作时，使用此表。
| 维度 | 权重 | 典型修复工作量 | 每小时分数影响 | 如果…则先修复 |
|---|---|---|---|---|
triggering_accuracy |
0.25 | 低——重写描述 | 高 | 总分 < 70 |
orchestration_fitness |
0.20 | 中——重组章节 | 高 | 技能混合工作器 + 监督逻辑 |
output_quality |
0.15 | 中——添加示例 | 中 | 评判器分数 < 0.70 |
scope_calibration |
0.12 | 低——将内容移到 references/ | 中 | 文件 < 100 或 > 800 行 |
progressive_disclosure |
0.10 | 低——创建 references/ 目录 | 中 | 不存在 references/ 目录 |
token_efficiency |
0.06 | 低——减少 MUST/ALWAYS/NEVER | 低 | 反模式计数 ≥ 3 |
robustness |
0.05 | 低——添加故障排除部分 | 低 | 未记录边缘情况处理 |
structural_completeness |
0.03 | 非常低——添加标题/代码块 | 低 | 少于 4 个 H2 标题 |
code_template_quality |
0.02 | 非常低——添加语言标签 | 非常低 | 代码块缺少语言标签 |
ecosystem_coherence |
0.02 | 非常低——添加相关部分 | 非常低 | 完全没有交叉引用 |
经验法则： 首先修复 triggering_accuracy——权重 0.25 时，它每小时带来的复合分数增益超过所有低权重维度的总和。
触发准确性（权重 0.25）
- 包含“Use this skill when...”后跟 3–4 个逗号分隔的具体上下文。
- 如果技能应在没有明确用户请求的情况下自动激活，添加“proactively”。
- 心理测试：写 5 个应触发它的提示和 5 个不应触发的提示——你的描述能区分吗？如果不能，添加或收紧上下文短语。
编排适配性（权重 0.20）
- 记录技能接收什么和返回什么——而不是它编排什么。
- 避免在 SKILL.md 中使用“orchestrate”、“coordinate”、“dispatch”、“manage workflow”。
- 包含一个“Output format”部分和 2 个以上展示具体工作器行为的代码块。
输出质量（权重 0.15）
- 给出具体、可操作的指令——而不仅仅是目标。
- 至少明确覆盖一个边缘情况（空输入、格式错误的数据等）。
- 包含一个示例部分，展示代表性输入和预期输出。
- 指令越具体，评判器对该维度的评分越高。
范围校准（权重 0.12）
- 目标 200–600 行。低于 100 是存根；高于 800 且没有
references/是臃肿。 - 将背景阅读、扩展示例和参考表移到
references/。 - 非常狭窄的技能应与同级合并；非常广泛的技能应拆分。
渐进式披露（权重 0.10）
- 添加
references/目录（获得 0.15–0.25 奖励）并保持 SKILL.md 专注于执行路径。assets/目录增加额外奖励。
Token 效率（权重 0.06）
- 审计 MUST/ALWAYS/NEVER 数量。目标每 10 行少于 1 个。
- 合并近乎重复的要点和重复结构的表格。
鲁棒性（权重 0.05）
- 添加“Troubleshooting”或“Edge Cases”部分，覆盖至少 3 种失败模式。
- 说明技能在无法完成任务时返回什么。
结构完整性（权重 0.03）
- 确保至少 4 个 H2/H3 标题、3 个代码块、一个示例部分和一个故障排除部分。
代码模板质量（权重 0.02）
- 所有代码块必须语法有效且可复制粘贴，并带有语言标签。
生态系统连贯性（权重 0.02）
- 添加一个“## Related”部分，列出带有相对路径的同级技能或代理。
- 避免重复其他技能中已存在的内容——改为链接到它。
故障排除
“添加内容后分数远低于预期”
反模式惩罚会累积。使用 --output json 运行并检查 layers[0].anti_patterns。如果你有 5 个以上反模式，乘数可以将分数降低到原始值的 75%，无论内容有多好。先修复标志。
“尽管描述详细，但 triggering_accuracy 很低”
_description_pushiness 评分器查找特定的句法模式，而不仅仅是长度。验证你的描述包含短语“Use this skill when”或“Use when”（确切措辞很重要——它是正则表达式匹配）。还要检查是否有多个用例用逗号或“or”分隔，以获得特异性奖励。
“LLM 评判器分数在不同运行之间差异很大”
这对于模糊的技能是预期的。评判器非确定性地生成 10 个心理测试提示。通过收紧描述和添加具体示例来提高分数稳定性。当 judges > 1 时，平均分数会更稳定。使用 --depth deep 和 certify，它会运行蒙特卡洛以获得统计上有界的分数。
“尽管文件长度合适，但 progressive_disclosure 分数很低”
检查文件是否在 200–600 行的最佳区间内。短于 100 行的文件在此子检查中仅得 0.20 分。还要确认 references/ 文件不为空——评分器检查非空引用文件，而不仅仅是目录。
“compare 显示我的重写分数低于原版”
Quick 深度（--depth quick）仅运行静态分析。如果重写将内容移到 references/ 并显著缩短了 SKILL.md，结构完整性的静态分数可能会下降，即使整体质量提高了。运行 --depth standard 以获得更公平的比较，包括 LLM 评判器对内容质量的评估。
参考
相关代理
- eval-judge (
../../agents/eval-judge.md)——对第 2 层维度（triggering_accuracy、orchestration_fitness、output_quality、scope_calibration）进行评分的 LLM 评判器。当需要仅重新运行评判器层或检查其推理时直接调用。 - eval-orchestrator (
../../agents/eval-orchestrator.md)——顶层编排器，负责排序所有三个层、合并结果、分配徽章并写入最终报告。当运行完整认证或头对头比较两个技能时调用。
