1. 从“凭感觉发布”到“有据可依”Agent Skill 质检的真实痛点如果你写过几个像样的 Agent Skill大概率会有这样一种感觉改一行提示词比改一百行业务代码还让人心里没底。代码改了跑一遍单测绿了就是绿了。但 Skill 改了跑一遍 demo没报错——然后呢你真的敢说它“没问题”吗我试过在同一个 Skill 上连续迭代七版每版都手动跑三五个场景结果上线后还是被同事反馈“边界情况退化了”。问题不在于我不认真而在于手工验证根本无法覆盖非确定性输出的全部可能。Skill 的核心是一份 SKILL.md它的行为是“提示词 模型 上下文”三者共同作用的结果。改一个字输出可能就天差地别。官方指南其实给出了正确方向写真实用例、对比有无 Skill 的表现、给输出打分、汇总迭代。但这套流程全靠手工很难坚持超过两轮。这就是 skill-up 要解决的问题。它是一个用 Go 编写的 CLI 工具官方定位是“Agent Skill 的评测与进化工具”。用测试领域的话翻译就是把 JUnit / pytest 那套成熟框架完整地移植到了 Skill 这个新物种上。它让你能够在真实的 Agent Engine如 Claude Code、Codex、Qoder CLI中运行 Skill验证其功能正确性将失败转化为可操作的修复线索并在本地或 CI 中持续回归。本文面向需要批量发布 Agent Skill 的团队聚焦 skill-up 的 CLI 质检流程。我会给出 Go 环境下的安装命令、skill 目录结构示例、LLM-as-a-Judge 评分配置并演示一次从本地校验到发布通过的完整验证动作。如果你正在为“Skill 发布没有质量门禁”发愁这篇可以跟着做。2. 前置准备Go 环境与 TaoToken 接入配置skill-up 本身是 Go 编写的 CLI但它的评测执行层需要调用大模型来完成 agent_judge 判定。为了让评测链路稳定可复现我建议把模型调用统一走 TaoToken 的 API 网关。这样做的原因很实际评测场景下你会频繁切换模型做横向对比如果每个模型都单独配 Key、单独记 Base URL维护成本会迅速失控。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的接口协议。你需要在控制台创建一个 API Key然后把它写进环境变量。skill-up 在执行 agent_judge 时会读取OPENAI_BASE_URL和OPENAI_API_KEY这两个环境变量来构造裁判模型的请求。先确认 Go 环境可用go version # 期望输出类似 go version go1.22.x linux/amd64如果还没装 Go去官网下载对应平台的安装包即可。skill-up 要求 Go 1.21 以上。接着安装 CLIcurl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash安装完成后验证skill-up --version # 期望输出 skill-up version x.y.z然后配置模型接入。这里以 Linux/macOS 为例写入 shell 配置文件export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEYsk-你的TaoToken密钥Windows PowerShell 用户用$env:OPENAI_BASE_URLhttps://taotoken.net/api $env:OPENAI_API_KEYsk-你的TaoToken密钥注意OPENAI_BASE_URL末尾不要加/v1skill-up 内部会自动拼接路径。如果你之前配过其他网关记得先清理掉冲突的环境变量否则会出现local proxy failed之类的连接错误。模型选择上agent_judge 建议用推理能力较强的模型比如 claude-sonnet 系列或 gpt-4 级别。你可以在 TaoToken 的模型对话页面先手动测一下目标模型是否可用确认返回正常后再写进评测配置。这一步花两分钟能省掉后面大量排障时间。3. 可复制配置skill 目录结构与 eval.yaml 完整示例skill-up 采用“约定优于配置”的设计。当eval.yaml位于包含SKILL.md的目录下时运行时会自动安装这个本地 Skill通常不需要手动写 Skill 路径。标准目录结构如下my-skill/ SKILL.md # 被测对象 evals/ eval.yaml # 评测入口配置 cases/ # 测试用例集 basic-success.yaml edge-case-null.yaml regression-001.yaml fixtures/ # 测试数据与脚手架 repos/ # 代码仓库模板 diffs/ # 补丁文件 scripts/ # 自定义校验脚本 mcp/ # MCP 工具配置eval.yaml定义运行环境与引擎schema_version: v1alpha1 environment: type: none engine: name: claude_code model: provider: anthropic name: claude-sonnet-4-8 cases: files: - evals/cases/my-test.yaml单轮用例示例覆盖 rule_based 判定id: find-null-bug title: 应识别空指针 bug input: prompt: Review the current diff and report findings. context: repo_fixture: evals/fixtures/repos/null-check-bug apply_diff: evals/fixtures/diffs/null-check.patch judge: type: rule_based success: - output_contains: all: [null, bug] - exit_code: 0多轮用例示例适合迭代优化和澄清交互场景id: multi-turn-binary-search title: 多轮实现二分查找并补测试 input: turns: - role: user content: 用 Go 实现二分查找 post_condition: must_contain_all: [func, binary] on_fail: fail - role: user content: 添加单元测试 post_condition: must_contain_any: [Test, t.Run] on_fail: failLLM-as-a-Judge 配置示例这是本文重点。agent_judge 会把 Skill 输出和判定标准一起喂给裁判模型id: judge-code-quality title: 生成的代码应具备良好可读性 input: prompt: 生成一个 Go 函数解析 JSON 配置文件并返回结构体。 judge: type: agent_judge model: provider: openai name: claude-sonnet-4-8 criteria: | 请从以下维度评估输出 1. 函数命名是否清晰表达意图 2. 错误处理是否完整 3. 是否有必要的注释 4. 是否存在明显的边界遗漏 输出格式PASS 或 FAIL并附一句话理由。 pass_when: PASS这里有个关键设计细节judge是“是否通过”的质量门槛而expect是“绝对不能突破”的安全底线。两者叠加形成“硬约束 软评估”的双层防护。你可以在同一个用例里同时写expect和judge前者保证基本行为不出错后者给主观质量留出评判空间。如果你用 Claude Code 的 settings 文件管理环境可以在项目根目录建.claude/settings.json{ env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的TaoToken密钥 } }Codex 用户则在~/.codex/auth.json中配置{ openai_api_key: sk-你的TaoToken密钥, base_url: https://taotoken.net/api }三件套记牢Base URL 填https://taotoken.net/apiKey 填控制台生成的密钥Model ID 填你实际要用的模型名。缺一个都会导致 401 或模型不存在。4. 验证请求从本地校验到发布通过的完整动作配置写好后先做一次配置校验避免 YAML 语法错误导致运行中断skill-up validate --config evals/eval.yaml # 期望输出Config valid. 3 cases found.然后跑全量评测skill-up run如果你只想先验证单个用例可以指定文件skill-up run --case evals/cases/judge-code-quality.yaml执行过程中skill-up 会拉起配置的 Agent Engine准备 repo_fixture、应用 diff、注入本地 Skill然后执行对话并采集完整输出。判定层依次执行 expect 和 judge最后汇总每个用例的 PASS / FAIL 状态。跑完后查看报告skill-up report --format html # 生成 report.html浏览器打开即可查看报告产物包括grading.json、JUnit XML、HTML 和 benchmark 对比。grading.json是结构化数据记录了每个用例的通过状态、失败原因、实际输出、期望条件。这个文件是后续 skill-upper 闭环修复的输入。一次典型的成功输出如下Running 3 cases with engine claude_code... [PASS] find-null-bug (rule_based) [PASS] multi-turn-binary-search (rule_based) [PASS] judge-code-quality (agent_judge) Summary: 3 passed, 0 failed, 0 skipped Report written to grading.json如果要做基线对比比如验证“改了一行提示词后是否退化”skill-up run --baseline这个命令会把当前结果和上一次基线做 diff直接告诉你哪些用例从 PASS 变成了 FAIL。这正是“改一行提示词心里没底”的解药——你不需要凭感觉报告会告诉你答案。并行执行可以加速大批量用例skill-up run --parallelism 4指定不同引擎做横向对比skill-up run --engine codex接入 CI 时把skill-up run作为质量门禁步骤JUnit XML 可以直接被 Jenkins、GitLab CI 等平台解析。一旦有用例失败流水线自动阻断发布。5. 常见报错排查401、local proxy failed、reading choices、OAuth评测链路涉及 CLI、Agent Engine、模型网关三层报错定位需要按层排查。下面是我踩过的坑和对应解法。401 Unauthorized最常见的原因是 API Key 没生效或 Base URL 写错。先确认环境变量echo $OPENAI_BASE_URL echo $OPENAI_API_KEY如果输出为空说明当前 shell 没加载配置。检查是否写进了~/.bashrc或~/.zshrc并执行了source。如果 Key 正确但仍 401检查 Base URL 是否误加了/v1后缀。正确写法是https://taotoken.net/api不要带/v1。local proxy failed这个报错通常出现在 Agent Engine 启动阶段。skill-up 会为每个用例准备隔离环境如果本地端口被占用或网络策略拦截就会报 proxy failed。排查步骤先确认没有其他进程占用评测所需端口再检查eval.yaml里的environment.type是否设成了none大多数场景用none即可不需要额外代理层。如果你在容器里跑确认容器网络能访问taotoken.net。reading choices 相关错误这个报错说明模型返回的 JSON 结构不符合预期通常是裁判模型返回了非标准格式。agent_judge 期望模型输出包含choices字段的标准响应。如果你用的模型不支持 OpenAI 兼容格式就会解析失败。解法在 TaoToken 的模型对话页面确认目标模型返回结构正常或者在judge.model里显式指定provider: openai强制走兼容协议。OAuth 相关报错如果你用 Claude Code 作为 Engine它可能尝试走 OAuth 登录流程。在 CI 或无人值守环境下这会失败。解法是在eval.yaml的engine配置里显式指定 API Key 模式而不是依赖 OAuth。同时确认~/.claude/settings.json里的env字段已正确写入 Base URL 和 Key。Codex 用户同理检查~/.codex/auth.json是否完整。用例全部 FAIL 但输出看起来正常这种情况多半是 judge 的criteria写得太模糊裁判模型无法给出稳定判断。建议把判定标准拆成可勾选的条目每条都有明确的 PASS/FAIL 边界。另外pass_when的值要和模型实际输出格式对齐如果模型返回“通过”而你写的是“PASS”就会误判。回归用例没有自动沉淀skill-upper 负责把失败场景写入cases/regression-*.yaml。如果你只跑了skill-up run而没有触发 skill-upper回归用例不会自动生成。确认你的工作流里包含了 skill-upper 的调用步骤或者手动把失败用例复制到cases/目录并标记为回归。6. 把质检关变成发布流水线的默认动作skill-up 真正的价值不在于单次评测而在于它把“评测 → 归因 → 修复 → 回归”串成了闭环。skill-upper 会读取grading.json里的失败项判断是 Skill 缺陷还是用例缺陷然后自动修改 SKILL.md 或调整 YAML 判定条件最后把失败场景沉淀为回归用例。官方把这套流程叫做 Eval-to-Evolution Loop。对团队来说落地路径可以分三步走。第一步挑 10 到 20 条真实场景写成 eval case接入 CI让每次 Skill 改动自动回归。第二步把 agent_judge 的判定标准统一化避免不同人写出风格迥异的 criteria 导致评分不可比。第三步把skill-up run设为发布流水线的必经关卡JUnit XML 作为质量凭证归档。模型调用统一走 TaoToken 的 API 网关Base URL 固定为https://taotoken.net/apiKey 在控制台管理模型 ID 按评测需求切换。这样无论你用 Claude Code、Codex 还是 Qoder CLI 作为 Engine裁判模型的接入方式都是一致的不会因为换引擎就要重配一遍。如果你还在手动跑 demo 然后凭感觉发布 Skill建议从今天开始建第一个 eval case。哪怕只覆盖三条核心场景也比“裸奔”强得多。质检这件事早做一天少踩一个坑。