前言¶

Agent 上线后，「改了一版 prompt / 换了个模型，到底变好了还是变差了」往往只能靠体感或零散试跑。传统软件有单元测试和 CI，但 Agent 决策路径不固定、同题多次运行结果可能不同，也常常没有唯一标准答案。下面介绍的 evaluation Skill，来自开源合集 Agent Skills for Context Engineering，专门指导如何构建面向 Agent 的评估体系：确定性检查、回归套件、多维评分量表、质量门控，以及生产侧的持续观测与基线对比。

这是什么¶

evaluation 是一份符合 Agent Skills 规范的 SKILL.md 指导文档（Skill 元数据中版本为 1.2.0，维护方为 Agent Skills for Context Engineering Contributors）。它不负责替你写评测代码，而是在你设计或落地评估时，提供可核对的方法论与操作顺序。

与「先堆 LLM 当裁判」的常见做法不同，该 Skill 强调：先对可机器校验的结构做确定性验证，再在多维度量表稳定之后，才大规模使用模型评判；裁判提示设计、成对比较、校准与偏见缓解等，应交给同仓库的 advanced-evaluation。

核心功能¶

以下能力均来自官方 SKILL.md 与合集 README 中的表述。

何时启用¶

适合在以下场景激活该 Skill：

• 系统化测试 Agent 表现
• 验证上下文工程（context engineering）改动是否达到预期
• 度量随时间的改进、上线前抓回归
• 为 Agent 流水线建质量门控
• 对比不同 Agent 配置
• 对生产系统做持续评估

明确不要用本 Skill 覆盖的工作：advanced-evaluation（裁判本身的设计）、harness-engineering（自主控制面与回滚边界）、context-degradation（先定位具体上下文失效再度量）。

评估原则¶

1. 看结果，不绑路径：Agent 可能用不同工具链达到同一目标，评估应基于正确性、完整性、质量等结果标准，执行路径仅作参考。
2. 多维量表，避免单一总分：事实准确性、完整性、引用准确性、来源质量、工具效率等分维打分，再按业务加权；单一数字容易掩盖某一维的严重失败。
3. 确定性优先于 LLM 评判：在产物具备可校验结构时，先做 schema 有效性、重复键、量表计算、清单同步、检索状态、必需证据路径等检查，失败则快速拒绝，避免浪费 token 或用主观分「洗白」无效输出。
4. 评估预算要贴近生产：资料引用浏览 Agent 研究结论——token 用量、工具调用次数、模型选择会显著影响测得的表现方差；应在接近生产的 token 上限下评估，多 Agent 架构需与单 Agent 基线对比。

方法论要点¶

• 测试集：早期可用 20–30 条用例；系统成熟后建议 50+ 条以获得更稳定信号。按复杂度分层（simple / medium / complex / very_complex），并分别汇报各层分数。
• 评分：各维映射到 0.0–1.0，加权汇总；一般场景通过线常取 0.7，高风险场景常取 0.9；须同时保留各维分数。
• LLM-as-Judge：用于规模化时，提示中应包含任务说明、待测输出、可用时的 ground truth、带层级描述的评分尺度，以及结构化判断与理由；评判模型宜与被测 Agent 不同模型族，以降低自我偏好。
• 人工抽检：边界样本、异常查询、生产流量随机样本交人工，用于发现自动化漏检的问题，并反哺评测标准。
• 有状态 Agent：对会改写文件、数据库或配置的 Agent，用终态断言程序化校验，而非规定中间步骤。
• 持续评估：变更触发自动跑评测、版本对比、关键指标回退则阻断发布；生产侧抽样评测，资料给出示例告警阈值——通过率低于 0.85 为 warning、低于 0.70 为 critical，并配合趋势看板。

与其他 Skill 的分工¶

本 Skill 负责结果度量与质量门；advanced-evaluation、harness-engineering、context-degradation、context-optimization、multi-agent-patterns、tool-design、memory-systems 等分别覆盖裁判设计、控制环、退化检测、优化效果、协作与工具等专项评估场景。Skill 内还指向同目录下的 references/metrics.md（设计具体指标与加权计算时可读）。

安装与启用¶

Agent Skills 要求目录结构，不能把单独的 SKILL.md 平铺成单文件，否则会破坏 references/ 等相对路径。

Claude Code（插件市场）¶

在 Claude Code 中注册插件源：

/plugin marketplace add muratcankoylan/Agent-Skills-for-Context-Engineering

安装合集插件（包含 evaluation 等全部已发布 Skill）：

/plugin install context-engineering@context-engineering-marketplace

Skill 会根据任务上下文自动激活。

Cursor¶

1. 从 Cursor Plugin Directory 的 context-engineering 条目 安装，或克隆仓库后将 Cursor 指向插件根目录。
2. Cursor 通过 Open Plugins 清单 .plugin/plugin.json 发现仓库根目录下的 skills/。
3. 若只在当前项目手动安装 evaluation，将 skills/evaluation 整目录复制到项目内：

mkdir -p .cursor/skills
cp -R skills/evaluation .cursor/skills/

（需先在本机取得仓库中的 skills/evaluation 目录；用户规则禁止在本文写作流程中使用 git clone，请自行下载或复制该目录。）

Codex 与通用 Agent Skills 目录¶

• Codex 项目级：复制到 .codex/skills/
• 通用布局：复制到 .agents/skills/
• Claude Code 项目级：复制到 .claude/skills/

合集 README 说明：仓库以 Open Plugins 形式分发，清单位于 .plugin/plugin.json。

典型用法¶

官方在 SKILL.md 中给出了可复现的伪代码与配置片段，用于说明评估流水线形状，而非绑定某一框架。

多维加权与通过判断（简化示例）：

def evaluate_agent_response(response, expected):
    rubric = load_rubric()
    scores = {}
    for dimension, config in rubric.items():
        scores[dimension] = assess_dimension(response, expected, dimension)
    overall = weighted_average(scores, config["weights"])
    return {"passed": overall >= 0.7, "scores": scores}

按复杂度组织测试集（节选）：

test_set = [
    {
        "name": "simple_lookup",
        "input": "What is the capital of France?",
        "expected": {"type": "fact", "answer": "Paris"},
        "complexity": "simple",
        "description": "Single tool call, factual lookup"
    },
    {
        "name": "medium_query",
        "input": "Compare the revenue of Apple and Microsoft last quarter",
        "complexity": "medium",
        "description": "Multiple tool calls, comparison logic"
    },
    # ... complex / very_complex 用例
]

先跑确定性门控，再跑质量评分：

def evaluate_pr_candidate(candidate):
    structure = run_validate_repo(candidate)
    if not structure.ok:
        return {"passed": False, "reason": "deterministic validation failed", "details": structure.errors}

    quality = run_rubric_eval(candidate)
    return {"passed": quality.overall >= 0.8, "scores": quality.dimensions}

质量门维度示例（YAML）：

gate:
  deterministic:
    - schema_valid
    - required_files_present
    - no_duplicate_ids
  quality:
    factual_accuracy: min 0.85
    completeness: min 0.80
    source_traceability: min 0.90

建议的搭建顺序（官方 Practical Guidance 摘要）：先定义业务相关质量维 → 写清量表层级 → 从真实用法与边界用例建分层测试集 → 实现变更触发的自动流水线 → 改前建立基线 → 持续追踪趋势并辅以人工复核 → 将确定性失败与质量判断分开处理。

适用场景与注意¶

适合谁：正在把 Agent 从 demo 推向生产的团队——需要回归套件、上线门控，或要证明某次上下文/工具/多 Agent 改动确实提升了结果而非偶然。

常见坑（来自官方 Gotchas，择要）：

• 评测过拟合到固定代码路径或表面模式，应对结果与语义写标准，并定期轮换输入。
• 评判模型与被测模型同族导致分数偏高。
• 评测集与训练或 prompt 数据污染。
• 只优化聚合分导致「分数好、体验差」，需定期与人工判断交叉验证。
• 评测集过小（官方建议至少约 50 条）或未按难度分层，容易被简单题拉高总分。
• 把评估当成一次性上线检查；模型、工具与用法变化后应持续跑评测。

本 Skill 是平台无关的原则文档；合集 README 称示例多为 Python 伪代码，便于跨环境理解，不强制安装特定依赖。

结尾¶

Agent 能否「越改越好」，取决于你是否能量化结果、抓住回归，并在生产里看见漂移。evaluation Skill 把这类工作拆成可执行的维度、门控与流水线步骤，并与同仓库的其他 Skill 划清边界。完整内容与 references/ 见官方目录：

https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/evaluation