快速上手：评估一个 Skill

你只需要一个包含 SKILL.md 的本地目录，就可以用 comet eval 评估一个 Skill。即使你还没有预先编写评估用例，Eval 也会根据 Skill 的内容自动生成 2–4 个评估用例并运行。本文按实际使用顺序介绍：先跑通一次，再选择 Agent 和评估后端，然后配置任务、生成报告和定位失败原因。

你要准备什么

必需内容

已安装 @rpamis/comet。npm 包自带 eval harness，不需要 clone Comet 仓库。
一个本地 Skill 目录，里面包含 SKILL.md。
运行真实评估时，需要 uv、Python 3.11+、Docker、选定的 Agent CLI 和对应模型凭证。

--collect 只做静态发现和配置检查，不启动 Agent、Docker、插件、凭据或网络请求。因此可以先用它检查 Skill，不必一开始就准备完整的模型环境。如果要选择 Claude Code 以外的 Agent，先阅读 Eval Agent 启动配置，确认对应的 CLI、认证方式和模型协议。

用户级 `.env` 配置

普通用户不需要 clone Comet 源码，也不需要进入源码目录下的 eval/。第一次运行任意 comet eval 命令时，CLI 会自动创建完整的用户级配置文件：

Windows：%USERPROFILE%\\.comet\\eval\\.env
macOS/Linux：~/.comet/eval/.env

CLI 只会创建缺失文件，不会覆盖已有文件。首次运行会在输出中显示实际路径；打开这个文件，按需填写参数后再次运行即可。当前 shell 中已经设置的环境变量优先于 .env。自动生成的模板包含全部用户可配置参数，按以下几组组织：

参数组	主要变量
主任务（Bench）	`BENCH_EVAL_AGENT`、`BENCH_API_KEY`、`BENCH_BASE_URL`、`BENCH_MODEL`
独立 Judge	`BENCH_LLM_JUDGE`、`BENCH_JUDGE_AGENT`、`BENCH_JUDGE_API_KEY`、`BENCH_JUDGE_AUTH_TOKEN`、`BENCH_JUDGE_BASE_URL`、`BENCH_JUDGE_MODEL`
Claude Code	`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_*`、`CLAUDE_CODE_SUBAGENT_MODEL`、`BENCH_CC_MODEL`、`BENCH_CC_VERSION`
Codex	`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`、`CODEX_API_KEY`、`CODEX_BASE_URL`、`CODEX_MODEL`、`BENCH_CODEX_*`
Qoder	`QODER_PERSONAL_ACCESS_TOKEN`、`QODER_BASE_URL`、`QODER_MODEL`、`BENCH_QODER_*`
CodeBuddy	`CODEBUDDY_API_KEY`、`CODEBUDDY_AUTH_TOKEN`、`CODEBUDDY_BASE_URL`、`CODEBUDDY_MODEL`、`CODEBUDDY__MODEL`、`CODEBUDDY_CUSTOM_HEADERS`、`CODEBUDDY_INTERNET_ENVIRONMENT`、`BENCH_CODEBUDDY_`
自定义 Agent	`COMET_EVAL_ADAPTERS_DIR`；以及适配器 `adapter.yaml` 声明的凭据、模型和地址变量
其他评估与追踪	`BENCH_SIMULATOR_PROMPT_FILE`、`LANGSMITH_`、`TRACE_TO_LANGSMITH`、`LANGFUSE_`

模板中的参数默认都是注释，不填写的项目不会改变默认行为。真实 API key 只应放在用户级 .env 或当前 shell，不能写入 Skill、manifest、报告或公开仓库。

支持哪些评估 Agent

comet eval 默认使用 claude-code。主 Agent、用户模拟器和可选的 Judge 都可以使用以下 Agent：

Agent	适合场景	常见凭证
`claude-code`	默认选择，使用 Claude Code 执行 Skill	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`
`codex`	使用 Codex CLI 或 OpenAI 兼容模型	`OPENAI_API_KEY` 或 `CODEX_API_KEY`
`qoder`	使用 Qoder CLI	`QODER_PERSONAL_ACCESS_TOKEN`
`codebuddy`	使用 CodeBuddy CLI 或其 API	`CODEBUDDY_API_KEY` 或 `CODEBUDDY_AUTH_TOKEN`

自定义 Agent 适配器是用户级进阶能力，不需要 clone Comet 源码。只有需要修改内置 Eval harness、任务或 Docker 环境时，才需要参考进阶配置。

非预定义 Agent 的注册、凭据和 CLI 约定见Eval Agent 启动配置。仅仅把可执行文件放到 PATH 上不会自动启用它。如果看到评估瞬间结束且没有真实运行，通常是 Docker、Agent CLI 或模型凭证没有准备好；harness 在这些情况下通常会跳过，而不是伪造一次成功运行。

第一次运行

先做不调用模型的预检查，再运行一次低成本冒烟，最后根据需要运行完整任务集：

# 1. 检查 Skill、manifest 和任务发现
comet eval ./my-skill --collect

# 2. 运行固定的低成本冒烟任务
comet eval ./my-skill --quick --html

# 3. 使用已配置或自动生成的任务运行评估
comet eval ./my-skill --html

没有 comet/eval.yaml，或者 manifest 中没有 evaluation.tasks 和 recommendedTasks 时，普通运行会根据 Skill 内容自动生成 2–4 个评估用例，冻结并缓存后再执行。你不需要先手写任务就能开始评估。--quick 不会使用这些自动生成的用例，而是固定运行 generic-skill-smoke，验证 Skill 能被注入、调用并产出 result.md。

target 怎么传

目录、直接的 SKILL.md 和 manifest 都可以作为 target：

# Skill 目录：自动发现其中的 comet/eval.yaml（如果存在）
comet eval ./my-skill --collect

# 直接传 SKILL.md
comet eval ./my-skill/SKILL.md --html

# 直接传 manifest
comet eval ./my-skill/comet/eval.yaml --html

没有 manifest 时，Comet 会在内存中合成基础配置，不会改写 Skill 源文件。Skill 在仓库外时，用 --project 指定保存运行状态和报告的项目目录：

comet eval ./my-skill --project ./my-project --html

配置评估 Agent 和 Judge

最简单的方式是在命令行选择主 Agent：

comet eval ./my-skill --agent codex --model subject-model --html

也可以在被评估 Skill 的根目录下创建 comet/eval.yaml，在这个文件中配置默认 Agent。例如目录结构如下：

my-skill/
├── SKILL.md
└── comet/
    └── eval.yaml

当你运行 comet eval ./my-skill 时，Comet 会自动发现 ./my-skill/comet/eval.yaml。你也可以直接把这个文件作为 target 传入：

comet eval ./my-skill/comet/eval.yaml --collect

在 eval.yaml 中配置默认 Agent。CLI 选项优先于 manifest：

execution:
  agent: codex
  model: subject-model
  baseUrl: https://subject.example/v1

judge:
  agent: claude-code
  model: judge-model
  baseUrl: https://judge.example/v1

主 Agent 和 LLM-as-Judge 可以使用不同的 Agent、模型、API 地址和凭据。Judge 不会默默继承主 Agent 的模型或凭据；启用 Judge 时，需要单独提供 Judge 配置。

选择评估后端

--suite 选择评估后端。三种后端使用同一套 target、任务和 Agent 配置，区别在于结果是否同步到外部评估服务：

后端	命令	结果位置和用途
`local`	`comet eval ./my-skill --html`	默认后端，只生成本地报告，适合日常开发
`langsmith`	`comet eval ./my-skill --suite langsmith --html`	生成本地报告，并同步运行轨迹、评分和实验数据到 LangSmith
`langfuse`	`comet eval ./my-skill --suite langfuse --html`	生成本地报告，并同步 task trace、rubric score、pass 指标和实验摘要到 Langfuse

Langfuse 示例：

LANGFUSE_PUBLIC_KEY=pk-lf-... LANGFUSE_SECRET_KEY=sk-lf-... \
  comet eval ./my-skill --suite langfuse --html

如果只是检查任务和配置，任何后端都可以和 --collect 一起使用：

comet eval ./my-skill --suite langfuse --collect

--collect --suite langfuse 不初始化 SDK、不联网，也不会下载插件。

报告有哪些类型

评估状态和报告默认写入 target 所属项目的：

.comet/eval/runs/<experiment-id>/
├── summary.md       # Markdown 总结报告，总是生成
├── summary.html     # HTML 总结报告，使用 --html 时生成
├── metadata.json    # 本次 experiment 的元数据
├── events/          # Agent 运行事件
├── raw/             # 原始输出
├── reports/         # 每次运行的 report.json
└── artifacts/       # 任务产物和校验证据

不带 --html 时，评估仍然会生成 summary.md。需要 HTML 时运行：

comet eval ./my-skill --html

也可以用 --report-config <path> 或 COMET_EVAL_REPORT_CONFIG 自定义报告输出。CLI 会打印 Experiment 和 Report path，查找报告时以本次输出为准。看报告时先关注三件事：

评估是否通过。
失败归因是 harness、workflow、task 还是 model。
是否缺少预期 artifact，以及 token、cost、duration 是否异常。

失败归因的含义是：harness 通常表示环境或依赖问题，workflow 表示 Skill 流程没有达到预期，task 表示任务定义或校验条件有问题，model 表示模型行为或调用不稳定。

怎么自定义任务

任务按以下优先级选择：

CLI 指定的 --task。
--quick 使用的 generic-skill-smoke。
manifest 中的 evaluation.tasks。
manifest 中的 recommendedTasks 或任务包 source。
没有可用任务时，根据 Skill 内容自动生成并缓存 2–4 个评估用例。

如果自动生成的任务不够贴合你的 Skill，请在被评估 Skill 的根目录下创建或编辑 comet/eval.yaml，并在其中的 evaluation.tasks 下声明 inline task。例如：

evaluation:
  tasks:
    - name: writes-summary
      prompt: Create summary.md with the requested result.
      expect:
        files:
          - summary.md
        contains:
          summary.md:
            - '# Summary'

引用 Skill 包内的任务包

如果任务需要独立的 task.toml、instruction.md、Docker 环境或验证脚本，可以把任务包放在 Skill 目录内，再通过 source 引用。推荐的目录结构如下：

my-skill/
├── SKILL.md
├── comet/
│   └── eval.yaml
└── eval-tasks/
    └── writes-summary/
        ├── task.toml
        ├── instruction.md
        ├── environment/
        │   └── Dockerfile
        └── validation/
            └── test_summary.py

在 Skill 根目录的 comet/eval.yaml 中，用 evaluation.tasks[].source 指向任务包。这里的 source 相对于 Skill 包根目录（包含 SKILL.md 的目录），不是相对于 comet/ 目录：

# my-skill/comet/eval.yaml
skill:
  name: my-skill
  source: ..

evaluation:
  tasks:
    - name: writes-summary
      source: eval-tasks/writes-summary

下面是这个任务包中几个文件的最小示例内容。完整的 task.toml 字段、验证脚本、profile 和 Docker 配置说明，见配置评估与自定义 Task。 task.toml 声明任务元数据、Docker 环境、需要检查的产物和验证脚本：

[metadata]
name = "writes-summary"
description = "Create summary.md"

[environment]
dockerfile = "environment/Dockerfile"

[validation]
test_scripts = ["test_summary.py"]
target_artifacts = ["summary.md"]

instruction.md 是发给 Agent 的任务指令：

Create `summary.md` in the current workspace.

Requirements:

- Include the heading `# Summary`
- Summarize the result in at least three bullet points

environment/Dockerfile 提供任务运行和校验所需的基础环境：

FROM python:3.11-slim

WORKDIR /workspace

validation/test_summary.py 在任务容器内检查 Agent 是否产出了符合要求的文件：

from pathlib import Path

from scaffold.python.validation.core import write_test_results


passed = []
failed = []
summary = Path("summary.md")

if not summary.exists():
    failed.append("summary.md is missing")
else:
    text = summary.read_text(encoding="utf-8")
    if "# Summary" in text:
        passed.append("summary heading is present")
    else:
        failed.append("summary heading is missing")

write_test_results({"passed": passed, "failed": failed})

eval-tasks/writes-summary/task.toml 描述任务的环境和校验方式，instruction.md 是发给 Agent 的任务指令；如果需要 Docker 或确定性校验脚本，就分别放在同一个任务包的 environment/ 和 validation/ 下。source 任务不能同时写 inline task 的 prompt 或 expect 字段，且 Comet 会检查任务包中确实存在 task.toml 和 instruction.md。配置后可以直接传 Skill 目录，Comet 会自动发现 comet/eval.yaml；也可以直接传 manifest：

# 自动发现 my-skill/comet/eval.yaml
comet eval ./my-skill --collect
comet eval ./my-skill --task writes-summary --html

# 直接传 manifest
comet eval ./my-skill/comet/eval.yaml --collect
comet eval ./my-skill/comet/eval.yaml --task writes-summary --html

任务可以检查文件、文本、JSON 或命令结果；任务工作区和期望产物必须留在允许的 Skill 包或评估工作区内。只有需要自定义 Docker 环境、验证脚本、profile 或 treatment 时，才需要继续阅读配置评估与自定义 Task。

一次推荐的评估流程

准备一个包含 SKILL.md 的目录
comet eval ./my-skill --collect
修复路径、manifest 或任务发现问题
comet eval ./my-skill --quick --html
根据需要配置 Agent、Judge、suite 或自定义 task
comet eval ./my-skill --html
阅读 .comet/eval/runs/<experiment-id>/summary.md 或 summary.html

进一步阅读

内容	适合场景
评估系统概览	了解任务、profile、评分和运行机制
评分指标与双 Agent 评测	了解 rubric、pass@k/pass^k 和多轮 Agent 交互
Eval harness	排查 harness、环境变量和套件内部机制
读取评估报告	深入分析报告和失败归因
comet eval 命令	查看完整 CLI 选项和故障排查

快速上手（基础）

方法论：为什么评估决定 Skill 演进

真实评估实验

深入掌握（进阶）

相关命令

快速上手：评估一个 Skill

你要准备什么

必需内容

用户级 `.env` 配置

支持哪些评估 Agent

第一次运行

target 怎么传

配置评估 Agent 和 Judge

选择评估后端

报告有哪些类型

怎么自定义任务

引用 Skill 包内的任务包

一次推荐的评估流程

进一步阅读

​你要准备什么

​必需内容

​用户级 .env 配置

​支持哪些评估 Agent

​第一次运行

​target 怎么传

​配置评估 Agent 和 Judge

​选择评估后端

​报告有哪些类型

​怎么自定义任务

​引用 Skill 包内的任务包

​一次推荐的评估流程

​进一步阅读

你要准备什么

必需内容

用户级 `.env` 配置

支持哪些评估 Agent

第一次运行

target 怎么传

配置评估 Agent 和 Judge

选择评估后端

报告有哪些类型

怎么自定义任务

引用 Skill 包内的任务包

一次推荐的评估流程

进一步阅读