skill-upper
Capture and review Agent Skill observations, and create, run, diagnose, or iteratively improve Skill evaluations (evals) with the skill-up CLI. Use when the user asks to record explicitly attributed Skill usage or feedback; review observations; turn an approved observation into a regression case; evaluate, test, regress, verify, fix, improve, iterate, or evolve a Skill; add or strengthen eval cases; write eval.yaml/case.yaml; run skill-up run/validate/list-cases/report/import/init; or migrate from Anthropic evals.json. Observation capture and review require either the Codex skill-up plugin or an observer-enabled DSH skill-up plugin; evaluation remains multi-engine.
Savant verdict: Pending analysis
Imported from the source hub; Savant's analysis is still running.
Live evaluation
Not evaluated yet. Workspaces can request a live evaluation.
Safety (NVIDIA SkillSpector)
Scan pending.
Structure
- 2 referenced files aren't in the packageassets/eval.yaml.tmpl, assets/case.yaml.tmpl. They may be binary, too large to catalog, or missing upstream.
- Ships 1 executable scriptevals/fixtures/scripts/assert-english-only-generated-cases.sh. Review what they do before enabling the skill for agents with tool access.
- No license declaredConfirm you may reuse this skill before importing it into your repository.
SKILL.md
---
name: skill-upper
description: "Capture and review Agent Skill observations, and create, run, diagnose, or iteratively improve Skill evaluations (evals) with the skill-up CLI. Use when the user asks to record explicitly attributed Skill usage or feedback; review observations; turn an approved observation into a regression case; evaluate, test, regress, verify, fix, improve, iterate, or evolve a Skill; add or strengthen eval cases; write eval.yaml/case.yaml; run skill-up run/validate/list-cases/report/import/init; or migrate from Anthropic evals.json. Observation capture and review require either the Codex skill-up plugin or an observer-enabled DSH skill-up plugin; evaluation remains multi-engine."
---
# 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.
2. 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.
3. 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.
4. 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:
```bash
command -v skill-up && skill-up --version
```
If a version is printed, continue. If you see `command not found`, on **macOS / Linux**:
```bash
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.:
```bash
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.
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.
### Step 4: Validate the configuration
```bash
skill-up validate <skill-root>/evals/eval.yaml
```
Expect: `✓ eval.yaml is valid (loaded N case(s))`.
### Step 5: Prepare credentials
Priority: `--api-key` > env (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `QODER_PERSONAL_ACCESS_TOKEN`) > `~/.skill-up/credentials.yaml`.
```bash
printenv | grep -E 'ANTHROPIC_API_KEY|OPENAI_API_KEY|QODER_PERSONAL_ACCESS_TOKEN'
```
If missing, **stop and ask**; do not write secrets into YAML without consent.
For `opensandbox`, also ensure `OPENSANDBOX_API_KEY` (and related env) as needed.
### Step 6: Run the evaluation
```bash
skill-up run <skill-root>/evals/eval.yaml
```
| Scenario | Command |
| -------------------------------- | ------------------------------------- |
| Subset | `--include-case-name "basic-*"` |
| Exclude | `--exclude-case-name "*-flaky"` |
| HTML report | `--format html` |
| Engine override | `--engine codex --model openai/gpt-4` |
| Parallelism | `--parallelism 4` (1–256) |
| Anthropic JSON | `--auto` |
| Stability/flakiness sampling | `--iteration 3` |
| Auto-append after last iteration | `--iteration 0` (default behavior) |
| Verbose | `-v`, `-vv` |
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`.
### 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
| Command | Purpose |
| --------------------------------------------- | --------------------------------- |
| `skill-up validate <eval.yaml>` | Validate before `run`. |
| `skill-up list-cases <eval.yaml>` | List cases. |
| `skill-up run [eval.yaml]` | Run evals. |
| `skill-up run --auto` | Run from `evals/evals.json`. |
| `skill-up report <result.json> --format html` | Re-render reports. |
| `skill-up import <evals.json>` | Convert Anthropic format to YAML. |
| `skill-up init` | Write user-config template. |
| `skill-up debug judge <input.json>` | Debug judge. |
| `skill-up debug report <input.json>` | Debug report. |
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).
- `--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`