SkVM General Usage

Drive the skvm CLI on behalf of a user to profile models, AOT-compile skills, run skill-assisted tasks, run benchmarks, and manage compiled proposals. Trigge...

Security Scan

The skill is an instruction-only wrapper for the skvm CLI and mostly matches its stated purpose, but the SKILL.md references environment variables and an install URL that are not declared in the metadata — this mismatch deserves attention before installing or using it.

Purpose & Capability

The skill's name and description match the instructions: it drives the skvm CLI to profile models, AOT-compile skills, run tasks, benchmark, and manage proposals. The operations described (skvm profile, aot-compile, run, bench, proposals, logs) are coherent with the stated purpose.

Instruction Scope

The SKILL.md confines actions to running the skvm CLI and reading/writing skvm-related directories (profiles, proposals, logs). It explicitly requires user confirmation before expensive runs and stops if prerequisites are missing. There is a minor scope ambiguity around 'jit-optimize': the header says not to trigger for jit-optimize but the document includes steps for 'manage jit-optimize proposals' (likely local management only) — this should be clarified.

Install Mechanism

This is instruction-only (no install spec), so it does not install code itself. The document suggests an install command (curl -fsSL https://skillvm.ai/install.sh | sh) to give users guidance if skvm is missing; recommending a curl|sh installer is a usability convenience but carries the usual safety caveats and should be verified by the user.

Credentials

The SKILL.md conditionally requires OPENROUTER_API_KEY for LLM-calling commands and references SKVM_PROFILES_DIR and .skvm log/cache paths, but the skill metadata declared no required env vars or config paths. That mismatch (SKILL.md accessing undeclared env vars/paths) is inconsistent and could surprise users with prompts to provide credentials or grant access to local directories.

Persistence & Privilege

The skill is not marked always:true, has no install actions, and does not request system-wide persistence or modify other skills' configs in the provided instructions. Autonomous invocation is allowed by default but not a special privilege here.

What to consider before installing

This skill appears to be a coherent CLI wrapper for skvm, but it references environment variables and local paths that are not declared in the registry metadata. Before using/installing: (1) verify the authenticity of the skvm binary if you must run the suggested install script (avoid running curl | sh from an unverified source), (2) expect to supply an OPENROUTER_API_KEY if you run commands that call an LLM — the metadata should have declared this but did not, (3) confirm you are OK with the skill reading/writing the .skvm directories (profiles, proposals, logs), (4) ask the publisher to clarify the jit-optimize triggering rule vs. the 'manage proposals' content and to update metadata to list required env vars (OPENROUTER_API_KEY, SKVM_PROFILES_DIR) if applicable. If you are uncomfortable providing an LLM API key or installing third-party binaries, avoid running LLM-invoking commands or the suggested install command.

You are driving skvm, a CLI that AOT-compiles and runs LLM agent skills across heterogeneous models. Use this skill when the user wants to use skvm — profile a model, AOT-compile a skill, run a task with a skill, run a benchmark, or manage optimization proposals. Do not invent flags — every example below uses the real flag set from the installed skvm binary.

Step 1: Prerequisite self-check

Split the check in two — the binary must always be present, but the API key is only required for commands that call an LLM.

Always required — skvm is on PATH:

skvm --help >/dev/null 2>&1 || { echo "skvm not installed — tell the user to run: curl -fsSL https://skillvm.ai/install.sh | sh"; exit 1; }

Required only before LLM-calling commands — profile (without --list), aot-compile, pipeline, run, bench, jit-optimize. Local filesystem commands (profile --list, proposals list|show|reject, logs, clean-jit) do not need the API key — run them even if the key is unset.

# Before running profile/aot-compile/run/bench/jit-optimize:
test -n "${OPENROUTER_API_KEY:-}" || { echo "OPENROUTER_API_KEY is not set — ask the user for their key"; exit 1; }

If a required prerequisite is missing, stop and tell the user what is missing. Do not install anything yourself.

Step 2: Profile a model

A profile (TCP — Target Capability Profile) records what an LLM can do across 26 primitive capabilities. It is the input for AOT compilation and is cached so subsequent compile calls reuse it.

skvm profile --model=<id>                              # profile one model
skvm profile --model=<id1>,<id2> --concurrency=4       # profile several in parallel
skvm profile --model=<id> --adapter=opencode           # non-default adapter
skvm profile --model=<id> --force                      # ignore cache, re-run
skvm profile --list                                    # list cached profiles

Notes:

• Default adapter is bare-agent. Other valid adapters: opencode, openclaw, hermes, jiuwenclaw.
• Cache lives at $SKVM_PROFILES_DIR (default .skvm/profiles/).
• Profiling is expensive — confirm with the user before running on several models, and prefer --concurrency over sequential runs.

Step 3: AOT-compile a skill

AOT compilation rewrites a skill's SKILL.md (and optionally bundle files) so it fits a specific target model's capability profile. The three-pass AOT compiler runs by default.

skvm aot-compile --skill=<path> --model=<id>                       # all three passes
skvm aot-compile --skill=<path> --model=<id> --pass=1,2,3          # explicit
skvm aot-compile --skill=<path> --model=<id> --pass=1              # only pass 1 (SCR + gap analysis)
skvm aot-compile --skill=<path> --model=<id> --dry-run             # no write
skvm pipeline --skill=<path> --model=<id>                          # profile-if-needed → aot-compile

Pass semantics:

• --pass=1 — SCR extraction, gap analysis, capability substitution/compensation
• --pass=2 — dependency manifest + env-binding script generation
• --pass=3 — workflow decomposition + DAG parallelism extraction

Compiled variants land under the proposals tree (proposals/aot-compile/...). Multiple passes can be combined in any subset: --pass=1,3 runs passes 1 and 3, skipping 2.

Step 4: Run a single task with a skill

For ad-hoc debugging of one skill on one task:

skvm run --task=<path/to/task.json> --model=<id>                    # no skill
skvm run --task=<path> --model=<id> --skill=<path/to/SKILL.md>      # with skill
skvm run --task=<path> --model=<id> --adapter=opencode --verbose    # explicit adapter + debug

Use this to reproduce a single failing task or validate a skill edit. Do not use it for benchmarking — use skvm bench instead.

Step 5: Bench a skill

Benchmarking runs a skill across many tasks and condition variants. It can get expensive fast — always confirm with the user before running across many models or tasks, and use --concurrency for parallelism.

skvm bench --model=<id>                                              # all conditions, all tasks
skvm bench --model=<id> --conditions=original,aot-compiled           # baseline + compiled
skvm bench --model=<id> --conditions=jit-optimized                   # use latest jit-optimize best round
skvm bench --model=<id> --conditions=jit-boost --jit-runs=5          # 5 warmup runs for solidification
skvm bench --model=<id1>,<id2> --concurrency=4                       # multi-model in parallel
skvm bench --model=<id> --tasks=task_01,task_02 --runs-per-task=3    # specific tasks, 3 reps each
skvm bench --model=<id> --async-judge                                # defer LLM-judge to post-run batch
skvm bench --resume=latest                                           # resume an interrupted session
skvm bench --list-sessions                                           # list past sessions

Valid --conditions strings:

• no-skill — run the task with no skill injected (baseline floor)
• original — the skill as-written (baseline ceiling)
• aot-compiled — full 3-pass AOT compiled variant
• aot-compiled-p1, -p2, -p3, -p12, -p13, -p23 — single or partial AOT passes
• jit-optimized — the latest best-round variant from skvm jit-optimize proposals
• jit-boost — code-solidification runtime optimization

Bench logs land at .skvm/log/bench/<sessionId>/.

Step 6: Manage jit-optimize proposals

Proposals are the artifact produced by skvm jit-optimize (and by the sibling skvm-jit skill). Each proposal contains the original skill in round-0/, one or more improved rounds in round-N/, and metadata recording which round the engine considered best.

skvm proposals list                                           # all proposals
skvm proposals list --status=pending                          # only pending (not yet accepted/rejected)
skvm proposals list --skill=<name> --target-model=<id>        # filter by skill + target model
skvm proposals show <id>                                      # print metadata and per-round summary
skvm proposals accept <id>                                    # deploy the engine-recommended best round
skvm proposals accept <id> --round=2                          # override: deploy round 2 instead
skvm proposals accept <id> --target=<dir>                     # deploy to a non-default skill dir
skvm proposals reject <id>                                    # mark as rejected (no deploy)
skvm proposals cancel <id>                                    # stop a detached run still in phase=running

Proposal id format: <harness>/<safe-target-model>/<skill-name>/<timestamp>, where <safe-target-model> is the slugified target model id (forward slashes in the CLI id become --). When the user gives you an id like bare-agent/openrouter--anthropic--claude-sonnet-4.6/calendar/20260401T120000Z, pass it verbatim — do not reformat it.

Detached runs (skvm jit-optimize --detach) write an extra run-status.json inside the proposal directory that tracks execution phase (running / done / failed), separate from meta.json.status. skvm proposals show renders this header and tails the last 20 lines of run.log for running / failed detached runs. If the user wants to stop a detached optimization mid-run, use cancel; sync runs (no --detach) do not need cancel, they block until complete.

Critical rule: only run skvm proposals accept when the user has explicitly asked to deploy. If the user just says "check the proposals", run list and show and stop there. Accepting without confirmation overwrites the skill files in place.

Step 7: Environment variables

Variable	Required	Purpose
OPENROUTER_API_KEY	yes	OpenRouter key used by bare-agent, profiler, compiler (when routed through OpenRouter), and jit-optimize optimizer
ANTHROPIC_API_KEY	optional	Enables the Anthropic SDK backend for the compiler and judge
SKVM_DATA_DIR	optional	Override the input dataset root (default: ./skvm-data submodule)
SKVM_CACHE	optional	Override the runtime cache root (default: ~/.skvm)
SKVM_PROPOSALS_DIR	optional	Override the proposals storage root (default: ~/.skvm/proposals/)

OPENROUTER_API_KEY is only required for commands that actually call an LLM. Local-only commands (proposals list/show/reject, profile --list, logs, clean-jit) run without it.

Rules

• Never run bench or profile across many models without explicit user confirmation — they can cost tens of dollars per run. Always quote an expected model count back to the user before starting.
• Never run skvm proposals accept unless the user explicitly asked to deploy.
• Prefer --concurrency=<n> over sequential loops for multi-model work.
• Do not invent flags. If the user asks for something you don't see in this skill, run skvm <command> --help to check before guessing.
• Do not install anything. If skvm is missing, tell the user to run the installer; if OPENROUTER_API_KEY is missing, ask them for it.
• Surface skvm's stderr progress lines (e.g. Installing bundled opencode…, Downloading profile…) as normal output — they are not errors.