skill-upper

use-skill-up-cli

通过 skill-up CLI 帮助用户评估和改进 Agent Skills。

手册：https://alibaba.github.io/skill-up/

语言策略

默认使用英语回复用户。如果用户使用中文（或任何其他语言），则切换到该语言，并在整个会话中保持一致。

检测规则（按优先级从高到低）：

1. 用户在当前消息中明确指定了语言（例如“用英语回答”或“用中文回复”）→ 遵循用户的指示。
2. 用户当前消息使用的自然语言 → 与之匹配。
3. 以上都不符合 → 默认使用英语。

无论回复使用何种语言，本 SKILL 中的技术标识符（CLI 命令、eval.yaml / case.yaml 字段名、报告字段名等）都必须保持原有的英语形式。不要翻译它们。

生成产物的语言规则

回复、新编写的说明性文字和 YAML 注释应使用用户当前所用的语言。保留测试输入、预期输出字面值、标识符、命令、路径和现有回归用例的语言与语义。不要仅仅因为对话语言改变，就翻译确定性断言。在测试本地化行为时，即使对话使用英语，也应保留原始业务文本。

将 assets/*.tmpl 视为结构参考：根据要求的语言调整占位说明文字和注释。仅审查为本任务新建或更改的文件；不要为了统一语言偏好而重写无关用例。

为生成的 YAML 添加简短的字段前置注释。在 eval.yaml 中说明实际配置的字段：schema_version、environment.type、engine.name、cases.files 和 report.formats；在 case YAML 中说明 id、title、input.prompt 和 judge.type。对于嵌套字段，应在父级映射内、紧挨子字段之前添加注释，而不是只在父级之前添加注释。 例如，应分别在 prompt 和 type 所在的缩进层级添加注释：

input:
  # User request sent to the agent.
  prompt: Review this code.
# Cheap prerequisites checked before the judge.
expect:
  must_contain: ["suggestion"]
judge:
  # Deterministic grading strategy for this case.
  type: rule_based

如果存在，则为 expect 和顶层 judge 添加注释；不要仅为满足注释检查而添加可选字段。保持字段名和枚举值不变。skill-up import 不会保留模板注释。

什么是 skill-up

skill-up 是面向 Agent Skill 作者的评估 CLI。它会将 Skill 安装到真实的 Agent 引擎（Claude Code、Codex、qodercli 等），为每个用例启动一个执行环境，运行提示词，然后通过声明的规则 / LLM 裁判 / 自定义脚本进行评分，最后生成报告。

典型目录结构：

my-skill/
  SKILL.md
  evals/
    eval.yaml
    cases/
      <case-id>.yaml
    fixtures/

何时触发

在以下任一情况下使用此 Skill：

• 用户要求“运行 / 评估 / 验证 / 测试此 skill”。
• 用户希望根据评估失败“修复 / 改进 / 迭代 / 改进”此 skill。
• 用户希望为某个 skill“添加评估、测试用例或回归用例”。
• 用户要求记录明确归因于 Skill 使用的内容、证据或反馈。
• 用户希望查看已记录的 Skill 观察结果，或将获批的反馈转为回归用例。
• 用户希望编辑 eval.yaml / case.yaml，或要求你选择合适的 judge 类型。
• 用户提到 skill-up run/validate/list-cases/report/import/init。
• 用户希望从 Anthropic evals.json 迁移到 skill-up。
• 当前工作目录包含 evals/eval.yaml 或 evals/evals.json，且用户希望运行它。

选择所需的工作流

• **诊断或规划：**阅读目标 Skill 和提供的证据，找出具体问题，并提出修改建议或测试案例。除非用户提出要求，否则不要安装工具、创建评测文件、修改配置或运行评测。
• **创建或编辑案例：**使用步骤 1–4 创建或更新测试套件，并验证其配置。除非用户也要求运行，否则在配置凭据和执行之前停止。在最终回复中报告实际的配置／案例路径和验证状态。
• **评测：**针对所需的测试套件，按照步骤 0–7 操作；报告失败情况，但不要自动编辑 Skill。
• **改进：**在所需范围内，按照评测工作流和步骤 8 操作。保留有效的现有案例和断言。

评测工作流

观察记录模式（可选）

当用户要求记录当前的 Skill 交互或反馈，且观察工具可用时，使用此模式。此模式要求使用支持生命周期钩子的当前 Codex 版本和 codex-skill-up 插件，或者使用明确启用了 skill-up 插件观察器的 DSH。不要为固定版本的 Codex 0.80.0 评测适配器添加观察记录功能。

如果用户询问如何安装任一宿主插件，或者缺少所需的观察工具且用户要求启用这些工具，请阅读 references/install.md 中的“安装观察宿主插件（可选）”。除非用户提出要求，否则不要安装或启用插件。

Claude Code、qodercli、Qwen Code 和其他 Agent Engine 均不支持此观察工作流。此限制不适用于常规的 skill-up 评测运行，此类运行仍支持多种引擎。

1. 仅当用户明确提及某个 Skill（例如 $my-skill），或能够确定负责的 Skill 时，才将交互归因于该 Skill。
2. 在 Codex 中，如果用户未明确指定归因对象，但能够确定该对象，则调用一次 mark_skill_invocation，并提供 Skill 名称和可选版本。在 DSH 中，通过其持久化的 /skill 注入或成功的 skill 工具结果推导确切归因；不要添加推断出的归因。
3. 在 Codex 中，仅当引用内容有助于复现或评测行为时，才使用 attach_skill_evidence。优先提供路径和简短摘要，而非复制文件内容。
4. 在 Codex 中，于观察到的轮次内使用 record_skill_feedback。在 DSH 中，观察器会将同一会话中的下一轮用户消息保存为未分类的后续候选项。对于明确反馈，请使用已完成观察的 ID 调用 record_observation_feedback。切勿捏造情绪倾向或评论。

两种适配器都会在本地保存前对常见格式的凭据进行脱敏，但仍应避免将机密发送给标记工具。如果用户只要求记录观察，则记录后即停止；除非用户也要求相关操作，否则不要编辑、评测、提交或发布 Skill。

观察输入模式（可选）

如果请求基于已记录的 Skill 观察，请先阅读 references/observations.md。使用可用的观察工具检查并预览观察内容，要求用户明确批准确切的候选项，仅在获得批准后写入，然后继续步骤 4。如果请求并非基于观察，请使用以下常规流程。

步骤 0：确认已安装 skill-up

开始任何操作前，先确认 skill-up 可用：

command -v skill-up && skill-up --version

如果显示了版本号，请继续。如果看到 command not found，请在 macOS / Linux 上执行：

curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

export SKILL_UP_VERSION=v0.1.0
curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

export INSTALL_DIR="$HOME/bin"
curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

平台：skill-up 目前仅支持 macOS / Linux；不支持 Windows。

安装后，再次运行 skill-up --version。如果仍找不到该命令，请将 ~/.local/bin 添加到 PATH。

更多详情，包括可选的 Codex 和 DSH 观察宿主插件，请参阅： references/install.md。

步骤 0.5（可选）：用户配置和遥测

对于 OTLP 默认值、runtime_kwargs（例如 OpenSandbox base_url）等：

skill-up init
skill-up init --local
skill-up init --print
skill-up init --force

优先级（从低到高）：内嵌空默认值 < 用户配置 < 项目 .skill-up.yaml < --config。SKILL_UP_CONFIG 可指向用户配置文件（环境变量名沿用历史命名）。请参阅上游 README 中的“用户配置”。

步骤 1：定位目标 Skill

1. 确定目标 Skill 的根目录（包含 SKILL.md 的目录）。按以下优先级搜索：用户提供的路径 → 从 CWD 向上最近的 SKILL.md → 最近查看的文件。
2. 阅读目标 SKILL.md，了解其范围、触发条件和依赖项。设计测试用例时，保留本地化行为和预期字面值。
3. 检查 evals/：
   • 存在 evals/eval.yaml → 步骤 4（可选执行步骤 3）。
   • 仅有 evals/evals.json → 使用 references/migrate-anthropic.md（skill-up run --auto 或 skill-up import）。
   • 不存在 → 步骤 2。

步骤 2：搭建 evals 框架（仅当不存在时）

• 将 assets/eval.yaml.tmpl 复制到 <skill-root>/evals/eval.yaml。
• 将 assets/case.yaml.tmpl 复制到 <skill-root>/evals/cases/<case-id>.yaml。

从用户要求的最小完整框架开始。除非用户要求更广泛的覆盖范围，否则创建一个有代表性的测试用例；只有针对不同要求时才添加更多用例。对于脚本判定器，用简短脚本实现所需的输出约定，并在符合相同约定的测试用例间复用。搭建框架时，不要构建通用报告解析器，也不要创建大规模脚本测试矩阵。对于仅含 JSON 的约定，使用 json.loads 和明确的字段检查；仅当约定允许时，才支持文本或 Markdown 封装。

按照“生成内容的语言规则”调整语言。将模板中的通用英文占位内容替换为符合要求输出语言、针对具体测试用例的文字。保留生成的 YAML 中简短的字段开头注释；当输出语言不是英语时，将注释翻译成对应语言，同时保留英文字段名和枚举值。

选择指南：

• environment.type：纯文本 Skill 使用 none；需要远程沙箱时使用 opensandbox（设置 OPENSANDBOX_API_KEY，将非机密值放在 environment.kwargs 中）。
• engine.name + engine.model：默认使用 claude_code；model 为可选项。对于 qodercli，通常省略 model。
• judge.type：rule_based（首选）、script、agent_judge（开销较大）——请参阅 references/judge-types.md。
• 测试用例 ID = 不含 .yaml 的文件名；提示词应能体现 Skill 的实际价值。
• 对于交互式测试用例，如果已知用户消息，保留固定的 input.turns[].content。仅当回复必须根据 Agent 的回应作出调整时，才使用 input.turns[].respond；如果应由模拟器选择所有后续回复以及何时停止，则使用 input.prompt 和测试用例级别的 user_simulator.scenario。设置独立的评测级别 user_simulator 模型和有界的 max_turns；请参阅两份 YAML 参考文档。不要将 engine.model 或 judge.model 隐式地用作模拟器模型。

请参阅 references/eval-yaml.md 和 references/case-yaml.md。

步骤 3：补齐缺项（已有 evals 时）

• skill-up list-cases <path>
• 检查 eval.yaml 和有代表性的测试用例；避免滥用 agent_judge。
• 根据需要添加或编辑 cases/ 下的 YAML。
• 如需逐字节保留检查，请在编辑前后比较 sha256sum <file>（或 shasum -a 256 <file>），并遵守用户允许的命令范围。
• 如果添加模拟用户轮次，请检查所选引擎是否支持会话恢复，配置独立的模拟器连接，并尽可能保留确定性的固定轮次和判定器断言。

步骤 4：验证配置

skill-up validate <skill-root>/evals/eval.yaml

预期结果：✓ eval.yaml is valid (loaded N case(s))。

对于编写用例的请求，到此结束，并提供配置和用例路径以及验证状态。不要在搭建脚手架时启动后台评估。回复前，重新打开生成的 YAML，并检查配置中紧挨着嵌套字段 input.prompt、judge.type 和 report.formats 之前的注释。input、judge 或 report 之前的注释不能说明其子字段。 单独检查每个生成的用例：读取实际的 judge: 块，并确保说明性注释位于 judge: 与 type: 之间，且缩进与 type: 相同。如果注释位于 judge: 上方，将其移入映射内部并重新验证。不要根据 YAML 验证成功或原本的编写意图来推断注释是否覆盖相应字段。 对于 expect 块，将说明性注释放在 expect: 正上方；放在 must_contain 上方、块内部的注释不能说明父级门控项。 对于新编写的评分脚本，在可行时，用一个通过和一个失败的样例进行检查，然后报告检查结果并结束。除非用户提出要求，否则不要扩展到无关的脚本功能或大型测试矩阵。

步骤 5：准备凭据

检查所选引擎和提供方的身份验证情况。提供方 API 密钥可从 --api-key、环境变量或 ~/.skill-up/credentials.yaml 获取；特定引擎的令牌和已保存的登录会话遵循该引擎的身份验证规则。绝不要转储环境变量或凭据文件，也不要将机密值输出到工具结果、日志或对话中。只检查相关变量是否具有非空值。例如，对于 OpenAI API 密钥工作流：

if printenv OPENAI_API_KEY | grep -q .; then
  printf '%s\n' 'OPENAI_API_KEY: configured'
else
  printf '%s\n' 'OPENAI_API_KEY: not configured in the environment'
fi

环境变量不存在，并不能排除基于文件的凭据或已有的引擎登录。如果无法使用所选的身份验证方式，停止并询问用户，让其在本地进行配置；不要要求用户在对话中粘贴机密，也不要未经同意将机密写入 YAML。

如果用户要求编写凭据探测脚本，在验证时也要遵守用户允许的命令配置文件。编写脚本并不代表可以在该配置文件禁止执行脚本时，使用 sh、sh -x 或 source 来启动它。应检查已编写的探测脚本，并说明未执行；不要仅为测试而添加不受支持的启动方式。仅在明确允许的隔离测试中，使用模拟凭据检查 shell 跟踪行为。

用户模拟器使用其自身的 user_simulator.provider 来解析凭据。对于 provider: simulation，设置 SIMULATION_API_KEY 和 SIMULATION_BASE_URL，或在 ~/.skill-up/credentials.yaml 中配置 simulation 提供方。对于 provider: openai，使用 OPENAI_API_KEY，并可选设置 OPENAI_BASE_URL；未设置时使用标准端点作为回退。使用 protocol: openai 对接 Chat Completions，或使用 protocol: anthropic 对接 Messages；自定义基础 URL 必须与对应协议匹配。对于 provider: anthropic 且 protocol: anthropic，使用 ANTHROPIC_API_KEY，并可选设置 ANTHROPIC_BASE_URL（未设置时回退到官方端点）。用于 Agent 的 --api-key 不会提供模拟器连接凭据。切勿将原始密钥写入 eval YAML。

对于 opensandbox，还要按需确保已设置 OPENSANDBOX_API_KEY 和相关环境变量。

第 6 步：运行评估

skill-up run <skill-root>/evals/eval.yaml

场景	命令
子集	--include-case-name "basic-*"
排除	--exclude-case-name "*-flaky"
HTML 报告	--format html
覆盖引擎	--engine codex --model openai/gpt-4
并行度	--parallelism 4（1–256）
Anthropic JSON	--auto
稳定性／不稳定性采样	--iteration 3
在最后一次迭代后自动追加	--iteration 0（默认行为）
详细输出	-v、-vv

退出码 0 = 全部通过；1 = 失败或出错，适用于 CI。当使用明确的正数 --iteration N 运行多个样本时，请查看终端中当前命令的简要摘要，寻找类似以下的行： case_a: 3 trials, 2 PASS, 1 FAIL -> flaky。

第 7 步：解读报告

产物位于 <skill-root>/<skill-name>-workspace/iteration-N/：

• result.json、benchmark.json，以及可选的 report.html
• <case-id>/with_skill/grading.json、outputs/

总结：通过率和耗时；对于失败项，列出案例 ID、断言 text 和 evidence；启用基准测试时，列出基准差异；提供 HTML 路径或 skill-up report result.json --format html。 对于模拟案例，请检查每一轮的 source，以及与对话记录对应的任何 stop_reason。达到 max_turns 属于执行错误；模拟器停止本身并不意味着 PASS，因为配置的评审器仍会对结果进行评分。

第 8 步：按需改进 Skill

仅当用户要求修复、改进、迭代或演进目标 Skill 时，才进入此循环。如果用户只要求评估或报告结果，请在第 7 步后停止，不要修改它。

1. 根据 result.json、grading.json 和输出证据诊断失败原因。
2. 如果 Skill 行为不正确，请修复 SKILL.md 或支持文件。
3. 如果覆盖范围不足，请添加或完善评估案例。
4. 不要仅为让失败项通过而弱化有效断言。
5. 先重新运行失败案例，再运行完整评估套件。
6. 持续执行，直到评估通过，或明确报告仍受阻的部分。

命令速查

命令	用途
skill-up validate <eval.yaml>	运行前进行验证。
skill-up list-cases <eval.yaml>	列出案例。
skill-up run [eval.yaml]	运行评估。
skill-up run --auto	从 evals/evals.json 运行。
skill-up report <result.json> --format html	重新生成报告。
skill-up import <evals.json>	将 Anthropic 格式转换为 YAML。
skill-up init	写入用户配置模板。
skill-up debug judge <input.json>	调试评审器。
skill-up debug report <input.json>	调试报告。

完整标志列表：references/cli.md。

常见问题

• 模型 ID 与代理别名——保留适用于用户 base_url 的设置。
• 使用 opensandbox 却未设置 OPENSANDBOX_API_KEY——会导致身份验证失败。
• 确定性断言的语言应与被测行为的语言一致，而不只是与对话语言一致。
• 滥用 agent_judge。
• Anthropic evals.json 预期 → 默认使用 agent_judge；如需进行确定性检查，请使用 import 并手动编辑。
• 路径相对于 Skill 根目录（SKILL.md 所在目录）。
• 模拟器回复是字面意义上的用户文本，包括 {{placeholders}}；变量捕获后的替换仅适用于已配置的固定轮次和 respond 指令。
• --iteration 0 会在最新的现有迭代之后追加一次运行，不会汇总历史记录；正数 --iteration N 会对所选用例运行 N 个样本；当 N > 1 时，会输出简单的稳定性／波动性摘要，仅涵盖当前命令运行的样本。

参考资料

• references/install.md
• references/eval-yaml.md
• references/case-yaml.md
• references/judge-types.md
• references/cli.md
• references/migrate-anthropic.md
• references/observations.md
• assets/eval.yaml.tmpl、assets/case.yaml.tmpl