skill-upper

use-skill-up-cli

Help the user evaluate and evolve Agent Skills through the skill-up CLI.

Manual: <https://alibaba.github.io/skill-up/>

Language Policy

Default to English when responding to the user. If the user writes in Chinese (or any other language), switch to that language and stay consistent with the user's input throughout the session.

Detection rules (highest priority first):

1. The user explicitly specifies a language in the current message (e.g. "answer in English" or "reply in Chinese") → follow the user's instruction.
2. The natural language used in the user's current message → match it.
3. None of the above → use English (default).

Regardless of the response language, technical identifiers in this SKILL — CLI commands, eval.yaml / case.yaml field names, report field names, etc. — MUST stay in their original English form. Do not translate them.

Language Rules for Generated Artifacts

When creating or editing eval.yaml, case.yaml, grading scripts, README snippets, final replies, or any other user-visible artifact, treat the language of the user's current message as the output language for this turn:

• If the user asks in Chinese, write the final response and all generated natural-language content in Chinese, including YAML comments, title, description, input.prompt, expect keywords, and judge.criteria.
• If the user asks in English, write the final response and all generated natural-language content in English, including YAML comments, title, description, input.prompt, expect keywords, and judge.criteria; do not leave Chinese or CJK characters in generated case files.
• If the target Skill itself is written in Chinese but the user asks in English, translate the Skill's functional intent into English test prompts and assertions instead of copying Chinese prose from the target Skill.
• In an English context, deterministic keywords in rule_based cases, including expect.must_contain and judge.success.output_contains, must also be English keywords. Express concepts such as resource leaks, closing resources, and exception handling in English; do not mix source-language terms into English assertions.
• Keep technical identifiers unchanged, such as schema_version, environment.type, engine.name, rule_based, agent_judge, script_path, file paths, and commands.
• Generated YAML comments must use field-leading comments. Keep each comment short: one line for field meaning, plus one line for options only when useful.
• When listing options in comments, keep enum values unchanged, such as none | opensandbox | docker and rule_based | agent_judge | script.
• Treat assets/*.tmpl as structural references only. Replace placeholder prose and comments with case-specific content in the current output language. The bundled templates are in English; translate their prose and comments when the user requests another language.
• skill-up import uses the CLI conversion path and does not preserve template comments; do not promise commented YAML for import-generated files.
• In an English context, after generating all files but BEFORE submitting the final reply, you MUST perform a CJK self-check: open every evals/cases/*.yaml and evals/eval.yaml and scan for CJK characters (Unicode ranges \u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff\u3000-\u303f\uff00-\uffef), including but not limited to title, description, input.prompt, expect keywords, judge.criteria, and YAML comments. If any CJK character is found, replace it with an equivalent English expression before finishing the task. This step is mandatory and must not be skipped.

What is skill-up

skill-up is an evaluation CLI for Agent Skill authors. It installs the Skill into a real Agent Engine (Claude Code, Codex, qodercli, etc.), spins up an execution environment for each case, runs the prompt, then grades the result via declared rules / LLM judges / custom scripts, and finally produces a report.

Typical layout:

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

When to trigger

Use this skill in any of the following situations:

• The user asks to "run / evaluate / verify / test this skill".
• The user asks to "fix / improve / iterate / evolve this skill" from eval failures.
• The user wants to "add evals, test cases, or regression cases to a skill".
• The user asks to record explicitly attributed Skill usage, evidence, or feedback.
• The user wants to review captured Skill observations or turn approved feedback into a regression case.
• The user wants to edit eval.yaml / case.yaml, or asks you to choose an appropriate judge type.
• The user mentions skill-up run/validate/list-cases/report/import/init.
• The user wants to migrate from Anthropic evals.json to skill-up.
• The current working directory contains evals/eval.yaml or evals/evals.json and the user wants to run it.

Main flow (follow this order strictly)

Observation capture mode (optional)

Use this mode when the user asks to record the current Skill interaction or feedback and observation tools are available. It requires either a current Codex release with the codex-skill-up plugin and lifecycle-hook support, or DSH with the skill-up plugin's observer explicitly enabled. Do not retrofit observation capture onto the pinned Codex 0.80.0 evaluation adapter.

If the user asks how to install either host plugin, or the required observation tools are missing and the user asks to enable them, read references/install.md under "Install an observation host plugin (optional)". Do not install or enable a plugin unless the user asks.

Claude Code, qodercli, Qwen Code, and other Agent Engines are not supported for this observation workflow. This restriction does not apply to normal skill-up evaluation runs, which remain multi-engine.

1. Attribute the interaction only when the user explicitly references a Skill

(for example, $my-skill) or the responsible Skill is otherwise known with certainty.

1. In Codex, if explicit attribution is absent but certain, call

mark_skill_invocation once with the Skill name and optional version. DSH derives exact attribution from its durable /skill injection or successful skill tool result; do not add inferred attribution.

1. In Codex, use attach_skill_evidence only for references that help reproduce or

evaluate the behavior. Prefer paths and short summaries over copied file contents.

1. In Codex, use record_skill_feedback during the observed turn. In DSH,

the observer stores the next user turn in the same session as an unclassified follow-up candidate. For explicit feedback, use record_observation_feedback with the completed observation's ID. Never invent sentiment or comments.

Both adapters redact common credential shapes before local persistence, but still avoid sending secrets to marker tools. If the request is capture-only, stop after recording it; do not edit, evaluate, commit, or publish a Skill unless the user also asks for that work.

Observation input mode (optional)

When the request starts from a captured Skill observation, read references/observations.md first. Use the available observation tools to inspect and preview the observation, require explicit approval for the exact candidate, write it only after approval, and then continue at Step 4. If the request does not start from an observation, use the normal flow below.

Step 0: Make sure skill-up is installed

Before doing anything, verify skill-up is available:

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

If a version is printed, continue. If you see command not found, on 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

Platform: skill-up currently supports macOS / Linux only; Windows is not supported.

After installing, run skill-up --version again. If the command is still missing, add ~/.local/bin to PATH.

More details, including optional Codex and DSH observation host plugins: references/install.md.

Step 0.5 (optional): User config and telemetry

For OTLP defaults, runtime_kwargs (e.g. OpenSandbox base_url), etc.:

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

Precedence (low → high): embedded empty defaults < user config < project .skill-up.yaml < --config. SKILL_UP_CONFIG can point at the user config file (env var name is historical). See the upstream README "User config".

Step 1: Locate the target Skill

1. Identify the root directory of the target Skill (the directory containing SKILL.md). Search in this priority: user path → nearest SKILL.md upward from CWD → recently viewed files.
2. Read the target SKILL.md for scope, triggers, and dependencies. If the Skill is Chinese but the user writes in English, translate capabilities into English for prompts and assertions.
3. Check evals/:

• evals/eval.yaml exists → Step 4 (optionally Step 3).
• Only evals/evals.json → references/migrate-anthropic.md (skill-up run --auto or skill-up import).
• Nothing → Step 2.

Step 2: Scaffold the evals (only when none exist)

• Copy assets/eval.yaml.tmpl to <skill-root>/evals/eval.yaml.
• Copy assets/case.yaml.tmpl to <skill-root>/evals/cases/<case-id>.yaml.

Adapt language per "Language Rules for Generated Artifacts". Replace the templates' generic English placeholders with case-specific prose in the requested output language. Preserve short field-leading comments in generated YAML; translate them when the output language differs from English, while keeping field names and enum values in English.

Selection guidelines:

• environment.type: use none for pure-text Skills; use opensandbox when you need a remote sandbox (set OPENSANDBOX_API_KEY, put non-secrets in environment.kwargs).
• engine.name + engine.model: default claude_code; model is optional. For qodercli, often omit model.
• judge.type: rule_based (preferred), script, agent_judge (expensive) — see references/judge-types.md.
• Case ID = filename without .yaml; prompts should exercise real Skill value.
• For interactive cases, preserve fixed input.turns[].content where the user message is known. Use input.turns[].respond only for a reply that must react to the agent, or input.prompt plus case-level user_simulator.scenario when the simulator should choose all later replies and when to stop. Set an independent eval-level user_simulator model and a bounded max_turns; see both YAML references. Do not reuse engine.model or judge.model as an implicit simulator model.

See references/eval-yaml.md and references/case-yaml.md.

Step 3: Fill the gaps (when evals already exist)

• skill-up list-cases <path>
• Review eval.yaml and representative cases; avoid agent_judge abuse.
• Add or edit YAML under cases/ as needed.
• If adding simulated user turns, check that the selected engine supports session resumption, configure the separate simulator connection, and retain deterministic fixed turns and judge assertions wherever possible.

Step 4: Validate the configuration

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

Expect: ✓ eval.yaml is valid (loaded N case(s)).

Step 5: Prepare credentials

For the agent model, priority is --api-key > env (ANTHROPIC_API_KEY, OPENAI_API_KEY, QODER_PERSONAL_ACCESS_TOKEN) > ~/.skill-up/credentials.yaml.

The user simulator resolves credentials by its own user_simulator.provider. For provider: simulation, set SIMULATION_API_KEY and SIMULATION_BASE_URL, or configure the simulation provider in ~/.skill-up/credentials.yaml. For provider: openai, use OPENAI_API_KEY and optionally OPENAI_BASE_URL; its standard endpoint is the fallback. Choose protocol: openai for Chat Completions or protocol: anthropic for Messages; custom base URLs must match that protocol. For provider: anthropic with protocol: anthropic, use ANTHROPIC_API_KEY and optional ANTHROPIC_BASE_URL (official endpoint fallback). --api-key for the agent does not supply the simulator connection. Never put a raw key in eval YAML.

for name in ANTHROPIC_API_KEY OPENAI_API_KEY QODER_PERSONAL_ACCESS_TOKEN SIMULATION_API_KEY SIMULATION_BASE_URL; do
  if printenv "$name" | grep -q .; then printf '%s=set\n' "$name"; fi
done

If the selected provider lacks credentials in both the environment and the credential file, ask the user to configure it; do not print secret values or write them into YAML.

For opensandbox, also ensure OPENSANDBOX_API_KEY (and related env) as needed.

Step 6: Run the evaluation

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

Exit 0 = all passed; 1 = failure or error — suitable for CI. When an explicit positive --iteration N runs more than one sample, inspect the terminal's simple current-command summary for lines like case_a: 3 trials, 2 PASS, 1 FAIL -> flaky.

Step 7: Interpret the report

Artifacts under <skill-root>/<skill-name>-workspace/iteration-N/:

• result.json, benchmark.json, optional report.html
• <case-id>/with_skill/grading.json, outputs/

Summarize: pass rate and timing; for failures, case id, assertion text, and evidence; benchmark deltas if enabled; offer HTML path or skill-up report result.json --format html. For simulated cases, inspect each turn's source and any stop_reason alongside the transcript. Hitting max_turns is an execution error; a simulator stop does not itself mean PASS, because the configured judge still grades the result.

Step 8: Evolve the Skill when requested

Only enter this loop when the user asks to fix, improve, iterate, or evolve the target Skill. If the user only asks to evaluate or report results, stop after Step 7 without modifying it.

1. Diagnose failures from result.json, grading.json, and output evidence.
2. Fix SKILL.md or supporting files when the Skill behavior is incorrect.
3. Add or refine eval cases when coverage is missing.
4. Do not weaken valid assertions merely to make a failure pass.
5. Rerun failed cases first, then run the full eval suite.
6. Continue until the evals pass or clearly report what remains blocked.

Command quick reference

Full flags: references/cli.md.

Common pitfalls

• Model IDs vs proxy aliases — preserve what works for the user's base_url.
• opensandbox without OPENSANDBOX_API_KEY — auth failures.
• Chinese expect.must_contain vs English model output — align language in prompts/assertions.
• Abusing agent_judge.
• Anthropic evals.json expectations → default agent_judge; use import + hand edits for deterministic checks.
• Paths relative to Skill root (SKILL.md directory).
• A simulator reply is literal user text, including {{placeholders}}; captured-variable substitution belongs only in configured fixed turns and respond instructions.
• --iteration 0 appends one run after the latest existing iteration without

summarizing history; positive --iteration N runs N samples of the selected cases and, when N > 1, prints a simple stability/flakiness summary covering only samples from the current command.

References

• 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