Before we install anything, you need one mental model. Every later lesson — running training, harvesting your Claude Code sessions, wiring in pi or Kiro — hangs off it.
Every coding agent you use today has a frozen brain. You can't fine-tune GPT-5.5 or
Claude on your workflows. What you can change is the text you feed it: system
prompts, AGENTS.md files, skill documents. Normally these are hand-written
and never systematically improved.
SkillOpt's move is to treat a single
skill document as the trainable state of the agent — and train it with
the same discipline as neural network weights: epochs, batches, a learning rate, and a
validation gate. Except every "weight update" is a bounded text edit
(add / delete / replace) made by a separate optimizer model. The output is a
compact best_skill.md (300–2,000 tokens) that you drop into your agent —
with zero extra model calls at inference time.
| Deep learning | SkillOpt equivalent |
|---|---|
| Weights | The skill document (plain markdown) |
| Forward pass | Rollout: agent attempts tasks using the current skill |
| Loss / gradient | Scored trajectories + optimizer-model reflection |
| Gradient step | Bounded add/delete/replace edits to the document |
| Learning rate | Textual edit budget (how much text may change per step) |
| Validation set | Held-out tasks — an edit ships only if it strictly improves the score |
Most "self-improving prompt" schemes drift: the LLM rewrites its instructions and quietly gets worse. SkillOpt only accepts an edit when it strictly improves a score on tasks it did not train on. This is why it reliably beats its starting point where loosely-controlled self-revision doesn't (paper).
The danger is measured, not hypothetical: a companion MSR study of ungated model-generated skills (SkillLens, 5 domains × 6 targets × 5 extractors) found negative transfer in 25% of cases — the extracted skill made the agent worse — rising to 47% on the most fragile domain. The gate is what turns a coin-flip risk into a ratchet.
The highlighted box is where your mission lives. The harness (SkillOpt calls it a backend) is the thing that actually executes a task with the current skill document and returns a trajectory to score. SkillOpt ships three kinds:
| Harness | Backend examples | What a rollout is |
|---|---|---|
| Direct chat | openai_chat, claude_chat, qwen_chat | One API call: skill + task in, answer out |
| Agentic CLI | codex_exec, claude_code_exec | A full agent session: tools, files, multi-turn |
| Yours (later) | pi, Kiro… | Same contract — you implement it in Lesson 6 |
Because the trained artifact is just markdown, skills transfer across harnesses: a skill optimized inside Codex works in Claude Code, and across model scales — one of the paper's headline results. But transfer is not free: SkillLens showed the same skill text can gain anywhere from +1.8 to +9.5 points depending on which model consumes it — consumption ability is a per-model property. Rule of thumb: skills transfer; validation doesn't. Re-run the gate when you change the target.
The repo actually contains two systems that share one philosophy:
skillopt/) — benchmark-driven:
you give it an env (a dataset + a rollout script + a seed skill) and it
trains. Lessons 4–5.
skillopt_sleep/) — usage-driven: a
nightly cycle that harvests your real Claude Code/Codex transcripts, mines
recurring tasks, replays them offline, and stages validated skill edits for your
review. Zero dependency on the research code. Lessons 2–3 — our fastest path to a
real-task win.
In this course, harness/backend = the execution target that runs rollouts; env/benchmark = the task set + scorer; skill = the markdown document being trained. Keep these three separate in your head — most confusion about SkillOpt is mixing them up.
SkillOpt README — Overview section — Microsoft Research. The authors' own 4-paragraph statement of the idea, ~5 minutes. If you want depth, follow it with §1–2 of the paper.