★ FEATURED ARTICLE 1. 写 SKILL.md 容易验证它不退化才是真麻烦Agent Skills 这个概念现在铺得很快用 Markdown 写一段能力描述coding agent 读到之后就知道该怎么干活。Claude Code、Codex、Qoder CLI、Qwen Code 都支持这套玩法。写一个 SKILL.md 的门槛确实低半小时能憋出一个能跑的版本。但问题往往出在后面——你怎么知道它真的按你预期在工作改了一版之后怎么确认没有把之前修好的行为又改坏我见过太多团队的做法是手动跑几个 prompt看着输出差不多就提交了。这种「肉眼评测」在 Skill 只有一两个的时候还能撑住一旦 Skill 数量上去、行为变复杂就完全失控。更麻烦的是回归——你为了修 A 行为改了 SKILL.md结果 B 行为悄悄退化了而你没测到。skill-up 就是冲着这个痛点来的。它是阿里巴巴开源的 Agent Skills 评测与进化工具Go 语言写的Apache-2.0 协议核心做两件事Evaluation评测和 Evolution进化。评测侧提供声明式 YAML 配置让你把「Skill 应该有什么行为」写成可复现的测试用例进化侧提供一个叫 skill-upper 的 Agent Skill读取评测失败报告自动修复 SKILL.md 或补充测试用例再跑一遍形成闭环。这篇文章面向用 Go 构建 Agent 工具的开发者也适合任何在维护 SKILL.md 的人。我会把 skill-up 的配置结构、评测任务定义、运行步骤、修复验证流程完整走一遍给出可直接复制的 YAML 和命令。读完你应该能搭起一条从「写完 Skill」到「CI 里持续评测」的路径。先说清楚它适合谁如果你只有一个玩具 Skill手动测测就行但如果你在维护多个 Skill、或者 Skill 会被多人协作修改、或者你想把 Skill 质量纳入 CI 门禁那 skill-up 值得花时间接进来。它不替代你的编辑器也不替代 agent 本身它补的是「质量验证」这一环。2. TaoToken 前置给评测引擎准备一个稳定的模型入口skill-up 跑评测的时候背后是要调用真实 agent 引擎的——claude_code、codex、qodercli、qwen_code 这些。也就是说评测过程本身会消耗模型调用。如果你在本地反复跑评测、或者在 CI 里每次 PR 都跑模型入口的稳定性和成本就变成实际问题。我自己的做法是把模型调用统一走 TaoToken 的 API 入口这样评测引擎的 base URL 和 key 集中管理换模型、调额度都在一个地方。TaoToken 提供兼容主流协议的统一入口skill-up 的 eval.yaml 里 engine 配置支持自定义 base URL正好能接上。你需要先拿到 API Key。访问 https://taotoken.net/api-keys 创建然后到 https://taotoken.net/doc 看接入文档确认协议细节。如果你只是想先验证模型能不能通可以用 https://taotoken.net/chat 直接对话测试。长期跑编码类评测、Agent 类任务的话https://taotoken.net/coding-plan 会更划算一些。这里要强调一点TaoToken 是合规的 API 聚合入口不是所谓的中转配置的时候按官方文档填 base URL 和 key 就行。skill-up 的 engine 配置里base-url 字段填 TaoToken 的 API 地址api-key 填你创建的 key。具体到配置skill-up 的 eval.yaml 里 engine 段大概长这样engine: type: claude_code model: claude-sonnet-5 base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY}把 key 放在环境变量里不要硬编码进 YAML。CI 里就用 secrets 注入。这样本地和 CI 用同一套配置只是 key 来源不同。如果你用的是 Codex 引擎配置结构类似把 type 换成 codexmodel 换成对应的模型 ID。skill-up 支持四种内置引擎每种引擎的 model 字段取值不同具体看 https://taotoken.net/doc 里的模型列表。还有一个细节skill-up 的配置有优先级embed user project explicit。也就是说你可以在 ~/.config/skill-up/config.yaml 里放全局的 base_url 和 api_key项目里的 .skill-up.yaml 只覆盖跟项目相关的部分。这样多个项目共享一套模型入口配置不用每个项目都写一遍。3. 可复制配置eval.yaml 与 cases 的完整结构skill-up 的评测配置分两层eval.yaml 定义评测环境和全局设置cases/*.yaml 定义单个测试用例。目录结构是这样的my-skill/ SKILL.md # 被评测的 Skill evals/ eval.yaml # 评测环境、引擎、全局设置 cases/ case-001.yaml # 单个测试用例 case-002.yaml先看 eval.yaml 的完整结构schema_version: v1alpha1 kind: EvalConfig environment: type: local # 本地沙箱环境 # type: opensandbox # 阿里云沙箱 engine: type: claude_code # 使用 Claude Code 引擎 model: claude-sonnet-5 base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} skill: path: ../SKILL.md # 被评测的 Skill 路径 cases: - cases/ # 引用 cases/ 目录下所有 yamlenvironment 有两种local 是本地沙箱opensandbox 是阿里云沙箱。本地开发用 local 就行CI 里如果 runner 环境干净也可以用 local。engine 段是重点。type 支持 claude_code、codex、qodercli、qwen_code还有 engine.custom 用于接入自定义 agent。base_url 和 api_key 就是上面说的 TaoToken 入口。model 字段填具体模型 ID。skill.path 指向被评测的 SKILL.md相对 eval.yaml 的路径。cases 段可以引用目录也可以逐个列文件。引用目录的话目录下所有 .yaml 都会被加载。再看单个测试用例 case-001.yamlschema_version: v1alpha1 kind: EvalCase id: case-001 description: 基本功能验证 input: role: user content: 帮我完成这个任务... judge: type: rule_based rules: - type: contains value: 预期输出关键词 - type: not_contains value: 不应出现的内容input 段定义发给 agent 的用户消息。judge 段定义怎么判断输出是否合格。三种评判策略的配置我分别给出来。rule_based 最简单适合有明确输出格式预期的用例judge: type: rule_based rules: - type: contains value: function - type: regex pattern: def\\s\\w\\( - type: not_contains value: errorscript 适合需要自定义逻辑的复杂判断judge: type: script script: | #!/bin/bash # $OUTPUT 包含 agent 的输出 echo $OUTPUT | grep -q expected_pattern exit $?agent_judge 用 LLM 作为评判者适合主观性强、难以用规则描述的判断judge: type: agent_judge criteria: | 评判标准 1. 输出是否正确完成了任务 2. 是否有安全问题 3. 代码质量是否合格 pass_threshold: 0.8pass_threshold 是 0-1 的评分阈值agent_judge 会给出一个分数超过阈值算通过。三种策略的取舍rule_based 零成本、最快适合有明确格式预期的用例script 低成本适合需要自定义逻辑的agent_judge 高准确性但消耗模型调用适合主观判断。不要一刀切全用 agent_judge按用例复杂度选。配置写完之后先跑 validate 验证skill-up validate ./evals/eval.yaml这个命令会检查 YAML 结构、schema 版本、cases 引用是否正确。配置有错会直接报出来比跑到一半失败强。4. 运行评测与验证修复效果配置验证通过之后跑评测skill-up run ./evals/eval.yaml运行完会在工作区生成报告。默认输出结构my-skill-workspace/ iteration-1/ result.json # 完整原始结果 grading.json # Anthropic 兼容格式 benchmark.md # 可读报告result.json 是完整原始结果包含每个用例的输入、输出、评判结果。grading.json 是 Anthropic 兼容格式方便跟 Anthropic 的 eval 工具链集成。benchmark.md 是人类可读的摘要报告先看这个。benchmark.md 里会列出每个用例的通过/失败状态失败的会给出失败原因。比如某个用例期望输出包含 function 但实际没有报告里会标出来。如果你想从已有的 result.json 重新生成报告不重跑评测用skill-up report result.json这个命令会重新生成 benchmark.md、report.html 等格式。report.html 可以在浏览器里打开看详情。接下来是进化环节。skill-upper 是一个 Agent Skill需要在 Claude Code 或 Codex 里安装# Codex全局安装 npx skills add https://github.com/alibaba/skill-up/tree/main/skills/skill-upper -g -a codex -y # Claude Code全局安装 npx skills add https://github.com/alibaba/skill-up/tree/main/skills/skill-upper -g -a claude-code -y安装之后在包含 SKILL.md 的项目里对 agent 说Use skill-upper to evaluate this Skill. Read SKILL.md, identify its most important behaviors, create realistic eval cases with appropriate judges, validate the configuration, and run skill-up. Summarize the results and the highest-impact failures.skill-upper 会读取 SKILL.md分析关键行为生成 evals/eval.yaml 和 cases/*.yaml调用 skill-up validate 验证配置调用 skill-up run 运行评测然后汇报结果和高优先级失败项。拿到失败报告后继续在同一对话里说Review the latest skill-up results. For each failure, determine whether the Skill or the eval is wrong. Fix SKILL.md and supporting files, or repair the eval case and judge as appropriate. Add regression cases for the bugs you found, rerun skill-up, and continue until the important behaviors pass.skill-upper 会对每个失败判断是 Skill 本身有问题还是测试用例写错了前者修 SKILL.md后者修 cases/*.yaml然后补充回归用例再次运行。这就是 eval-to-evolution 闭环报告 → 修复 → 回归用例 → 再次运行。每次迭代让 Skill 和测试套件都变得更强。验证修复效果就是看再次运行后的 benchmark.md确认之前失败的用例现在通过了同时没有引入新的失败。5. 常见报错排查401、local proxy failed、reading choices跑 skill-up 的过程中报错主要集中在模型调用和配置两块。我按实际遇到的频率列几个。401 Unauthorized最常见。原因通常是 api_key 没设置或设置错了。检查 eval.yaml 里的 api_key 字段如果是 ${TAOTOKEN_API_KEY} 这种环境变量引用确认环境变量真的导出了echo $TAOTOKEN_API_KEY如果为空说明没导出。在 shell 里 export 一下或者写进 ~/.config/skill-up/config.yaml。CI 里检查 secrets 是否正确注入。还有一种情况是 base_url 填错了。TaoToken 的 API 地址是 https://taotoken.net/api不要漏掉 /api 路径。填成 https://taotoken.net 会 404 或 401。local proxy failed这个报错通常出现在 environment.type 是 local 的时候skill-up 尝试启动本地沙箱但失败了。检查几点本地是否有足够的权限启动沙箱进程端口是否被占用如果是 CI 环境runner 是否支持沙箱所需的系统调用。如果本地环境搞不定可以试试把 environment.type 换成 opensandbox用阿里云沙箱。不过 opensandbox 需要额外的云上配置本地开发还是优先修 local。reading choices: unexpected end of JSON input这个报错来自模型返回的响应格式不对。通常是 base_url 指向的端点返回了非预期格式。检查 base_url 是否指向了正确的 API 路径以及 model 字段填的模型 ID 是否在 TaoToken 支持的列表里。模型 ID 填错的话有些端点会返回错误格式的响应。还有一种可能是网络问题导致响应被截断。重试一次看看是否复现。OAuth 相关报错如果你用的是 claude_code 引擎它默认可能走 OAuth 流程。在 CI 或非交互环境里 OAuth 会失败。解决办法是在 engine 配置里显式提供 api_key 和 base_url绕过 OAuth。skill-up 的 engine 配置支持直接指定 api_key这样就不走 OAuth 了。配置优先级搞混skill-up 的配置优先级是 embed user project explicit。如果你在 ~/.config/skill-up/config.yaml 里配了 base_url项目里的 .skill-up.yaml 又配了一个项目里的会覆盖全局的。排查的时候用skill-up init --print打印当前生效的配置模板确认实际用的是哪套。CC Switch / Cline MCP / Codex auth.json 相关如果你在用 CC Switch 管理多个 Claude Code 配置或者在 Cline 里通过 MCP 接入注意 skill-up 的 engine 配置是独立的不会自动读取这些工具的配置。你需要显式在 eval.yaml 里写 Base URL、Key、Model ID 三件套。Codex 的 auth.json 同理skill-up 不读它你得在 engine 段自己填。三件套就是engine: type: codex model: Model ID base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY}Base URL、Key、Model ID 三个都对上才能通。6. 把评测接进 CI让 Skill 质量有门禁本地跑通之后下一步是接进 CI。skill-up 在仓库根目录提供了 GitHub Action可以在每个 PR 触发时自动评测 Skill并且支持跨引擎对比。# .github/workflows/skill-eval.yml name: Skill Eval on: pull_request: paths: [skills/**, evals/**, **/SKILL.md] jobs: eval: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: alibaba/skill-upmain with: engine: claude_code api-key: ${{ secrets.TAOTOKEN_API_KEY }} base-url: https://taotoken.net/api skill-target: evals/eval.yamlAction 的 runner 镜像预装了 skill-up CLI 和三个引擎 CLI运行即开即用不需要额外的镜像拉取配置。api-key 从 secrets 注入base-url 填 TaoToken 的 API 地址。paths 过滤确保只有 Skill 或评测配置变更时才触发避免无关 PR 浪费模型调用。如果你不在 GitHub 上用其他 CI 系统也行。核心就是把 skill-up CLI 装到 runner 上然后跑skill-up run ./evals/eval.yaml根据退出码判断是否通过。skill-up run 在有失败用例时会返回非零退出码CI 直接据此判断门禁。CLI 命令参考我列一下常用的命令说明skill-up run [path]运行评测用例生成全套报告skill-up validate [path]验证 eval.yaml 和 cases/*.yaml 配置skill-up list-cases [path]列出配置引用的所有用例skill-up report result.json从已有结果重新生成报告skill-up import evals.json导入 Anthropic evals.json 转为 YAML 格式skill-up init写入用户配置模板skill-up debug judge input.json调试 judge 模块skill-up debug report input.json调试 report 模块如果你已经有 Anthropic 格式的 evals.json可以一键导入skill-up import ./evals/evals.json --output ./evalsskill-up 也会把结果输出为 grading.jsonAnthropic 兼容方便跟 Anthropic 的 eval 工具链集成。这个兼容性是显式设计目标说明项目考虑了跟现有工具链的互操作性而不是强迫你全部迁移。配置初始化skill-up init # 写入 ~/.config/skill-up/config.yaml skill-up init --local # 写入 $PWD/.skill-up.yaml skill-up init --print # 打印配置模板到 stdout我自己的习惯是全局配置放 base_url 和 api_key项目配置放 skill.path 和 cases 引用。这样多个项目共享一套模型入口项目之间互不干扰。最后说一个实际经验评测用例不要一次写太多。先从 3-5 个覆盖核心行为的用例开始跑通闭环再逐步补充。一上来写几十个用例失败报告会淹没你反而不知道从哪修起。skill-upper 的自动修复也是按优先级来的用例少的时候它更容易聚焦在关键失败上。如果你在开发 Agent Skillsskill-up 提供了一条从单次手动测试到 CI 持续评测的完整路径skill-upper 的自动修复循环让这个过程可以全自动化。模型入口用 TaoToken 统一管理本地和 CI 一套配置省去反复切换的麻烦。
阅读完成 · 觉得有帮助？
