Documentation

SkVM is a compilation and runtime system that makes LLM agent skills portable across heterogeneous models and harnesses. It implements the SkVM paper: profile model capabilities, compile skills to match, and optimize execution at runtime.

Installation

Most users should install the standalone skvm CLI and use it directly. Source checkout is still supported for contributors, but the installed binary is the primary workflow described in the current README.

# One-line installer (macOS / Linux)
curl -fsSL https://skillvm.ai/install.sh | sh

# Or install from npm (Node 18+)
npm i -g @skillvm/skvm

# Set your API key and verify the install
export OPENROUTER_API_KEY=sk-or-...
skvm --help

Quick Start

The current CLI quick start has four common workflows: profile the target, AOT-compile the skill, autotune with synthetic tasks, or optimize from an existing conversation log.

For every SkVM command below, model fields use the fully qualified form <provider>/<model-id>. For example, OpenRouter targets are written like openrouter/qwen/qwen3.5-35b-a3b.

1. Profile the target model

Generate a Target Capability Profile (TCP) for the target model and harness pair by running the 26-primitive profiling suite:

skvm profile
  --model=openrouter/qwen/qwen3.5-35b-a3b
  --adapter=bare-agent

The resulting profile is cached under .skvm/profiles/ and reused by later compilation runs for the same model and adapter combination.

2. AOT-compile the skill

Run the AOT compiler on the skill directory for the profiled target. The example below uses Pass 1 only and explicitly selects the compiler model:

skvm aot-compile
  --skill=path/to/skill-dir
  --model=openrouter/qwen/qwen3.5-35b-a3b
  --adapter=bare-agent
  --pass=1
  --compiler-model=openrouter/anthropic/claude-sonnet-4.6

AOT outputs are written into the proposals tree under .skvm/proposals/aot-compile/, where you can inspect the compiled variant before adopting it.

3. Autotune with synthetic tasks

Let SkVM generate synthetic tasks from the skill itself, then iterate optimize → rerun → score against the specified target model and adapter:

skvm jit-optimize --skill=path/to/skill-dir --task-source=synthetic
  --optimizer-model=openrouter/anthropic/claude-sonnet-4.6
  --target-model=openrouter/qwen/qwen3.5-35b-a3b
  --target-adapter=bare-agent

4. Or optimize from an existing conversation log

For post-mortems and feedback loops, feed prior run logs directly into the optimizer without rerunning tasks:

skvm jit-optimize --skill=path/to/skill-dir --task-source=log
  --logs=path/to/session.jsonl
  --optimizer-model=openrouter/anthropic/claude-sonnet-4.6
  --target-model=openrouter/qwen/qwen3.5-35b-a3b

CLI: profile

Profile a model's capabilities against the 26-primitive catalog. The command writes a cached TCP per (model, adapter), so later aot-compile and pipeline runs can reuse it instead of re-running microbenchmarks.

skvm profile --model=<provider>/<model-id> [options]

Detailed parameter guide. profile is the entry point that decides which model-adapter pairs need work, whether cached TCPs may be reused, and how profiling slots are distributed across the resulting job matrix.

Examples

# Default OpenRouter route
skvm profile --model=openrouter/qwen/qwen3.5-35b-a3b

# Profile multiple models in parallel
skvm profile --model=openrouter/qwen/qwen3.5-35b-a3b,openrouter/deepseek/deepseek-chat-v3-0324 --concurrency=4

# Native Anthropic route
skvm profile --model=anthropic/claude-sonnet-4.6

# Profile multiple adapters for one model
skvm profile --model=openrouter/qwen/qwen3.5-35b-a3b --adapter=bare-agent,opencode

# List all cached profiles
skvm profile --list

CLI: aot-compile

AOT-compile one or more skills for one or more target model-adapter pairs. The compiler consumes an existing TCP, runs the selected passes, validates the result with guard checks, and writes compiled variants under ~/.skvm/proposals/aot-compile/.

skvm aot-compile --skill=<path> --model=<provider>/<model-id> [options]

Detailed parameter guide. aot-compile first resolves skill paths, then loads TCPs for every requested model × adapter pair, and finally runs a shared compiler provider across the resulting job matrix.

Compilation Passes

The three-pass compiler is sequential on purpose: each pass narrows uncertainty and emits artifacts that the next pass can trust. Guard validation runs after compilation so unsafe or internally inconsistent rewrites are caught before the variant is accepted.

1. Pass 1 — Capability Gap Analysis: extracts the SCR from SKILL.md, compares the required primitive levels against the TCP, and splits deficits into hard absence vs weak proficiency. Hard gaps trigger substitution onto alternative primitive paths; weak gaps trigger compensation such as extra scaffolding, examples, decomposition, or stronger execution constraints. SCR extraction and rewriting are LLM-backed, while the actual gap analysis is deterministic computation.
2. Pass 2 — Environment Binding: inspects the skill bundle for tools, binaries, packages, and API dependencies, then checks whether the current environment already satisfies them. The output is not just a list of dependencies: SkVM also emits an idempotent environment setup script so the compiled artifact carries enough operational context to bootstrap itself on a clean machine.
3. Pass 3 — Concurrency Extraction: decomposes the workflow into a DAG, identifies independent stages, and records parallelism opportunities as DLP, ILP, and TLP hints. In practice this means the compiler is trying to separate steps that can be run independently from steps that are only ordered because the original prose was linear.

CLI: jit-optimize

Proposal-based skill optimization supports three explicit evidence sources: synthetic, real, and log. Regardless of source, the optimizer writes a proposal tree, records per-round evidence and root-cause analysis, and picks a best round for later review or deployment.

# Synthetic autotune
skvm jit-optimize --skill=path/to/skill-dir --task-source=synthetic
  --optimizer-model=openrouter/anthropic/claude-sonnet-4.6
  --target-model=openrouter/qwen/qwen3.5-35b-a3b --rounds=3

# Real bench tasks
skvm jit-optimize --skill=path/to/skill-dir --task-source=real
  --tasks=task-a,task-b --test-tasks=task-c
  --optimizer-model=openrouter/anthropic/claude-sonnet-4.6 --target-model=openrouter/qwen/qwen3.5-35b-a3b

# Existing execution logs
skvm jit-optimize --skill=path/to/skill-dir --task-source=log
  --logs=path/to/log1.jsonl,path/to/log2.jsonl
  --optimizer-model=openrouter/anthropic/claude-sonnet-4.6 --target-model=openrouter/qwen/qwen3.5-35b-a3b

Detailed parameter guide. jit-optimize always builds a proposal keyed by (harness, target-model, skill-name). What changes across task sources is how evidence is collected and whether tasks are re-executed or only analyzed retrospectively.

Shared Required Flags

Task-Source-Specific Flags

Loop, Delivery, and Batch Flags

CLI: pipeline

Profile the target if no cached TCP exists, then run aot-compile with that TCP. This is the shortest path when you want a compiled variant but do not want to manually split the work into profile and compile steps.

skvm pipeline --skill=<path> --model=<provider>/<model-id> [options]

Operationally, pipeline has three branches: load an explicit profile, reuse a cached profile, or run profile inline. Only after the TCP is resolved does it move on to the compile stage.

CLI: proposals

Inspect, diff, group, serve, accept, or reject the proposal trees created by jit-optimize. This command is the review surface between optimization and deployment.

skvm proposals list | show | diff | report | serve | accept | reject [options]

Use proposals as the human review gate. jit-optimize is allowed to propose edits, but accept is the point where those edits become the live skill bundle.

CLI: run

Execute one task against one model+adapter, with or without a skill. This is execute-only and primarily for testing; use bench when you need scored evaluation.

skvm run --task=<path> --model=<provider>/<model-id> --adapter=<name> [--skill=<path>]

SkVM copies any files under the task's fixtures/ directory into the work directory before execution, then reports workdir, timing, token usage, and non-OK run status at the end.

CLI: bench

Run benchmark conditions over tasks, skills, and models. bench is the widest CLI surface in SkVM because it covers standard benchmarking, deferred judging, session resumption, task import, and condition-to-condition comparison.

skvm bench --model=<provider>/<model-id> [options]

Detailed parameter guide. The standard execution path builds a benchmark plan from model × adapter × task × condition, while submodes like judge, --compare, --import, and --custom bypass parts of that plan builder.

Async Judge and Compare Modes

Import Mode

# Single model benchmark
        skvm bench --model=openrouter/qwen/qwen3.5-35b-a3b --adapter=bare-agent

# Specific conditions and tasks
        skvm bench --model=openrouter/qwen/qwen3.5-35b-a3b --conditions=no-skill,original,aot-compiled,jit-boost

# Defer LLM-judge and process it later
        skvm bench --model=openrouter/qwen/qwen3.5-35b-a3b --async-judge
skvm bench judge --manifest=path/to/manifest-dir --judge-model=openrouter/anthropic/claude-sonnet-4.6

CLI: clean-jit

Clear persisted JIT artifacts for a model+adapter pair when you want to reset solidification or proposal state.

skvm clean-jit --model=<provider>/<model-id> --adapter=<name>

The command intentionally keeps compiled SKILL.md artifacts, candidate metadata, and cached profiles intact. It is for resetting JIT effects, not wiping every derived artifact.

CLI: logs

List recent runs across profiling, compilation, bench, and runtime subsystems from the shared cache tree.

skvm logs

Each entry includes status, type, model or model count, harness, skill, summary text, and the log directory path, so logs acts as a lightweight session index over the shared cache.

Primitive Catalog

SkVM defines 26 primitive capabilities that describe what an LLM agent can do. Each primitive is testable at three difficulty levels (L1–L3). The catalog is organized into four domains:

Each primitive has a dedicated microbenchmark generator that produces randomized test instances. Generators use two evaluation patterns:

• Tool-use primitives — agent runs tools, evaluator checks files in the working directory
• Text-only primitives — profiler writes LLM response to file, evaluator reads it

TCP — Target Capability Profile

A TCP is the output of profiling: a JSON file that maps each of the 26 primitives to a proficiency level.

The profiler uses progressive testing: it tests L3 first. If the model passes, L2 and L1 are skipped (assumed passed). This minimizes API costs while maintaining accuracy.

{
  "gen.code.write": { "level": 2, "scores": { "L3": 0.33, "L2": 0.83 } },
  "tool.file.read": { "level": 3, "scores": { "L3": 1.0 } },
  "reason.plan":    { "level": 1, "scores": { "L3": 0.0, "L2": 0.17, "L1": 0.67 } }
}

SCR — Skill Capability Requirement

An SCR describes what primitives a skill needs and at what proficiency level. It is extracted automatically by the compiler (Pass 1) from the skill's SKILL.md file.

The SCR may include alternative implementation paths — different ways to accomplish the same goal using different primitives. This allows the compiler to find substitutions when a model lacks a required capability.

3-Pass Compilation

The AOT compiler transforms skills in three sequential passes. Each pass emits artifacts that narrow the next stage's search space, so the compiler is not just editing prose: it is moving from capability analysis to environment binding to executable scheduling hints.

Pass 1: Capability Gap Analysis

Pass 1 reads the skill as a requirement document. It extracts the SCR, maps each purpose to the primitives and minimum levels it needs, compares those against the target TCP, and decides whether the skill can run unchanged, needs compensation, or needs structural substitution.

• L0 gaps — capability absent → substitution (replace with alternative primitives)
• Weak gaps — capability present but below required level → compensation (add scaffolding, examples, decomposition)

Because the SCR can contain alternative implementation paths, Pass 1 is not limited to saying “the model is weaker.” It can often redirect the skill onto a different primitive path that the target model is better at executing.

Pass 2: Environment Binding

Pass 2 binds the rewritten skill to the actual machine it will run on. It extracts dependency manifests, checks whether binaries, Python packages, APIs, or shell tools already exist, and emits an idempotent setup script that can recreate the required environment.

This means AOT output is not only “better instructions for the model”; it also becomes a more operational skill bundle with explicit setup knowledge instead of hidden environmental assumptions.

Pass 3: Concurrency Extraction

Pass 3 analyzes the workflow structure itself. It decomposes the skill into a DAG, identifies true data and control dependencies, and looks for places where the original sequential prose can be turned into parallel work without changing semantics.

• DLP — Data-Level Parallelism (process independent data chunks)
• ILP — Instruction-Level Parallelism (pipeline independent steps)
• TLP — Task-Level Parallelism (run independent subtasks concurrently)

The resulting variant can therefore preserve the same end behavior while exposing runtime scheduling opportunities that a plain natural-language skill would usually leave implicit.

JIT Optimization

SkVM provides two independent JIT systems that operate after the original skill already exists. They solve different problems: JIT-boost reduces repeated runtime cost by bypassing predictable LLM calls, while JIT-optimize edits the skill itself based on evidence collected from runs.

JIT-Boost (Code Solidification)

JIT-boost is a runtime specialization layer. It first uses a headless agent to scan the whole skill bundle and emit boost-candidates.json entries containing code signatures, keywords, parameter templates, and execution templates. During execution, runtime hooks watch LLM calls for repeated matches against those signatures.

After enough consecutive matches, a candidate is promoted. From that point on, SkVM extracts parameters directly from the prompt, executes the stored template, and bypasses the LLM entirely for that repeated pattern.

• Zero LLM calls at runtime for promoted patterns
• Automatic demotion on failure (falls back to LLM)
• Model and harness agnostic — stored per skill

So JIT-boost is closer to code caching or solidification than to skill rewriting: it accelerates a stable repeated behavior path without changing the skill source itself.

JIT-Optimize (Skill Rewriting)

JIT-optimize is a proposal-driven editing loop. It normalizes evidence into a shared schema, copies the skill into a temporary workspace, writes the evidence and history into .optimize/, and launches a headless agent that can edit SKILL.md or any bundle files.

The optimizer must submit a structured record containing a required rootCause, reasoning, confidence, and changed files. SkVM then snapshots the workspace as a numbered round, computes the actual diff, reruns evaluation when appropriate, and chooses the best round according to score and monotonicity checks.

Because the result is stored as a proposal tree rather than applied immediately, JIT-optimize is a controlled editing workflow, not an in-place mutation mechanism.

Autotune

Autotune is the fully closed loop built on top of jit-optimize --task-source=synthetic: generate evaluation tasks, execute them, score the result, propose edits, and repeat until rounds are exhausted or convergence is reached. It is the nearest thing SkVM has to self-supervised online skill improvement.

System Overview

SkVM is structured as a modular pipeline:

Profile Tool ──TCP──> AOT Compiler ──Variant──> Runtime + Agent
     │                    │                         │
  26 primitives    3 passes                JIT-boost + JIT-optimize
  L3→L1 progressive   1: capability gaps     - code solidification
                       2: env binding         - skill optimization
                       3: concurrency DAG     - autotune loop

Key design principles:

• Decoupled stages — profiler, compiler, and runtime can run independently
• Pluggable adapters — any agent harness can be integrated via the AgentAdapter interface
• Pluggable providers — any LLM backend via the LLMProvider interface
• Cached artifacts — profiles, logs, and proposal-tree outputs are persisted and reused

Agent Adapters

Adapters wrap agent harnesses and provide a uniform interface. All adapters support RuntimeHooks for JIT monitoring.

LLM Providers

Two LLM provider implementations are included:

• Anthropic — native Anthropic SDK, supports tool_use
• OpenRouter — OpenAI-compatible API, routes to 100+ models

The extractStructured() function provides two-layer structured output: tool_use when available, prompt + parse fallback otherwise.

Evaluation Framework

Four evaluation methods, used by both the profiler and bench subsystems:

Environment Variables

Set these in a .env file at the project root. Bun auto-loads it.

Provider Routing

Start with skvm config init. The interactive wizard writes $SKVM_CACHE/skvm.config.json (default ~/.skvm/skvm.config.json) and lets you configure providers, API keys, and adapter checkouts without editing JSON by hand.

skvm config init
skvm config show
skvm config doctor

Every CLI model field uses <provider>/<model-id>. In the docs, the default route uses openrouter/, so a Qwen target is written as openrouter/qwen/qwen3.5-35b-a3b and Claude through OpenRouter is written as openrouter/anthropic/claude-sonnet-4.6. If you configure Anthropic directly as the provider, the same Claude model becomes anthropic/claude-sonnet-4.6. In other words, anthropic is the provider in the native route, but part of the model id when the provider is openrouter.

{
  "providers": {
    "routes": [
      { "match": "anthropic/*",  "kind": "anthropic",         "apiKeyEnv": "ANTHROPIC_API_KEY" },
      { "match": "openai/*",     "kind": "openai-compatible", "apiKeyEnv": "OPENAI_API_KEY",     "baseUrl": "https://api.openai.com/v1" },
      { "match": "openrouter/*", "kind": "openrouter",        "apiKeyEnv": "OPENROUTER_API_KEY" }
    ]
  }
}

Model IDs

SkVM uses provider-prefixed model identifiers in the form <provider>/<model-id>. The default examples below use OpenRouter, and the final line shows the native Anthropic form for comparison:

openrouter/qwen/qwen3.5-35b-a3b
openrouter/anthropic/claude-sonnet-4.6
openrouter/google/gemini-2.5-flash
openrouter/qwen/qwen3-30b-a3b-instruct-2507
openrouter/deepseek/deepseek-chat-v3-0324
anthropic/claude-sonnet-4.6

Data Directory

Current SkVM uses two roots: skvm-data/ for the input dataset, and .skvm/ for local runtime cache and generated artifacts.

skvm-data/
├── skills/         # input skill definitions
└── tasks/          # benchmark task dataset

.skvm/
├── profiles/       # cached TCP JSON files
├── log/            # profile / compile / bench / runtime logs
└── proposals/      # aot-compile, jit-boost, jit-optimize outputs