SkVM Skill Optimization Trigger

SkVM JIT Optimize Trigger

When you finish a task that was driven by a skill, and the skill's own instructions appear to have caused problems, collect a short structured record of what happened and invoke skvm jit-optimize. The optimizer reads that evidence, proposes improvements to the skill's files, and stores them as a proposal you can inspect with skvm proposals show <id>.

This skill is not a human review workflow. Its job is to turn task evidence into a concrete optimization run.

This works for any skill the host harness can load — it does not need to have been produced by SkVM's compiler. jit-optimize only needs the skill folder on disk; it does not require SkVM-specific artifacts.

When to trigger

Run this skill only when both of the following hold:

1. The task you just completed was driven by a skill that the harness loaded from disk (not an ad-hoc user instruction).
2. At least one of the following is true:
   • the task failed or ended partial, and a clearer skill would plausibly have avoided it
   • you observed a concrete problem in the skill's instructions: ambiguity, a missing step, an incorrect claim, a confusing ordering, or an unnecessary detour the skill forced you into

Do not run this skill when:

• the task succeeded and the skill read cleanly — silent passes are fine, the optimizer does not need "nothing to report" submissions
• the failure was purely user-side (typo in the prompt, missing credentials, network failure) and no change to the skill would have helped
• the task did not use a skill at all, or used only a trivial one-shot instruction
• you are running inside skvm bench or any other SkVM-orchestrated flow — bench owns its own optimization loop, do not double-submit

Step 1: Locate the skill directory

The skill directory contains a SKILL.md file. You need the absolute path to pass as --skill=<dir> in Step 3.

Each agent harness installs skills in well-known locations. Read adapter-skill-paths.md (sibling file in this skill's directory) and look up the section matching the harness you are currently running inside — it lists the search order for Claude Code, opencode, openclaw, hermes, jiuwenclaw, and bare-agent. Probe the listed paths in order and pick the first one that contains a SKILL.md for the skill name you are looking for.

If none of the listed paths contains the skill, or the reference file marks your harness as "confirm with user", ask the user for the path — do not guess.

Step 2: Prepare optimizer input

Pick one of the two formats below. Save it anywhere (e.g. a temp file); you'll pass its path as --logs=<path> in Step 3.

Format A — Simple optimization report (preferred for one-off observations)

Save as report.json:

{
  "task": "<what the user asked, one or two sentences>",
  "outcome": "pass" | "fail" | "partial",
  "issues": [
    "short description of each problem you hit",
    "another problem"
  ],
  "skill_feedback": "concrete suggestion for how the SKILL.md could be clearer or more correct"
}

Keep issues focused on things the skill's instructions could prevent or clarify. Do not include issues that were purely user-side (typos in the prompt, missing credentials, network failures).

The JSON key is still named skill_feedback because that is the current report schema consumed by jit-optimize; treat it as an optimization hint for the engine, not as human-directed feedback.

When outcome is fail or partial, the optimizer treats the issues and skill_feedback as failure reasons attached to a synthetic "agent-reported" criterion. When outcome is pass, the report still enters the optimizer but with no failures, letting it notice what worked well.

Format B — Conversation log (preferred when the full turn-by-turn trace is informative)

Save as conv-log.jsonl, one JSON object per line:

{"type":"request","ts":"<iso8601>","text":"<user prompt>"}
{"type":"response","ts":"<iso8601>","text":"<your reply or summary of the step>"}
{"type":"tool","ts":"<iso8601>","text":"<tool call summary>","toolCalls":[...]}

Only include entries that matter for diagnosing the skill's quality. Redact secrets.

Step 3: Run jit-optimize

skvm jit-optimize --detach \
  --skill=<skill-directory> \
  --task-source=log \
  --logs=<path-to-report.json-or-conv-log.jsonl> \
  --target-model=<id-the-task-ran-on> \
  --optimizer-model=openrouter/z-ai/glm-5.1

--detach is what lets this skill stay snappy. Without it the optimizer runs in-process and blocks the agent for the full optimization pass (often a minute or more); with it the CLI returns in well under a second after spawning a background worker. Always pass it from this skill.

Required parameters:

• --skill — path to the skill directory (the one containing SKILL.md)
• --task-source=log — tells jit-optimize to analyze a conversation log without rerunning anything. This is the only task source valid from this post-task optimization flow — real and synthetic sources rerun tasks against a live model, which a post-hoc report cannot do.
• --logs — path to the report file you wrote in Step 2
• --target-model=<id> — required for every skvm jit-optimize invocation, including --task-source=log. In log mode the target model is not used for execution — it is the storage key that decides which folder under proposals/<harness>/<target-model>/<skill>/ the proposal lands in, so proposals stay grouped by the model the skill is tuned for. Use the prefixed model id of the model that just ran the task — that is you, the agent reading this skill. Every id must carry a <provider>/ prefix that matches a route in the user's providers.routes; read your own model id out of your system prompt / harness environment and prepend the right provider (Claude Code exposes it as the "exact model ID", e.g. map claude-opus-4-6 → anthropic/claude-opus-4.6 when Anthropic-routed, or openrouter/anthropic/claude-opus-4.6 when OR-routed; opencode/openclaw/hermes similarly). If you genuinely cannot determine your own model id or provider, ask the user once and stop — do not substitute a placeholder.
• --optimizer-model=<id> — the LLM that drives the optimizer agent. Every id must carry a <provider>/ prefix; openrouter/z-ai/glm-5.1 is a good cheap default (needs OPENROUTER_API_KEY).

Optional:

• --target-adapter=<name> — purely informational in log mode (default: bare-agent). Set it if the log came from a non-default adapter (e.g., openClaw, Hermes, jiuwenclaw) so the proposal is filed under the right harness folder.
• --failures=<path,...> — structured failure-reasons JSON, one path per corresponding entry in --logs. Pass only when you already have a cleaner per-criterion breakdown than the report file itself; the count must match --logs. Skip it for single-report cases.

What NOT to pass in log mode (the CLI will error if you do):

• --tasks, --test-tasks — these belong to --task-source=real
• --synthetic-count, --synthetic-test-count — these belong to --task-source=synthetic
• --runs-per-task, --convergence, --baseline — the log mode does not rerun the task, so there is no loop to configure

With --detach, the CLI returns in well under a second. Stdout ends with a block like:

Proposal: <harness>/<safeTargetModel>/<skill>/<timestamp>
Proposal dir: <absolute-path>
Detached; watch with 'skvm proposals show <id>'

The optimization continues in a background worker process; its progress is recorded in <proposal-dir>/run-status.json (phase: queued | running | done | failed) and detailed log output goes to <proposal-dir>/run.log. Both are surfaced when the user runs skvm proposals show <id>.

Capture the id from the line starting with Proposal: only — everything after Proposal: up to the newline is the id. Do not parse Proposal dir: or the Detached; watch with line. Note the middle segment is safeTargetModel (derived from --target-model), not the optimizer model.

If skvm jit-optimize exits non-zero with no Proposal: line, the worker failed before it could allocate a proposal id. Read the stderr message and stop — do not retry blindly. The most common cause is another optimization is in progress for <skill>, which means a prior detach for the same skill+model is still running.