Microsoft SkillOpt Trains Your Agent's Markdown File Like a Model Weight

A spreadsheet skill trained inside Codex, dropped into Claude Code untouched, beat the skill trained inside Claude Code. Here's what that result actually tells you about where agent capability lives.

The number that should stop you is not the headline. Microsoft's SkillOpt reports a jump from 58.8 to 82.3 on a six-benchmark average with GPT-5.5, which is a big number and easy to file under "yet another optimizer paper."

The transfer result is stranger. A spreadsheet skill trained inside the Codex CLI, copied into Claude Code with zero further optimization, took that harness from a no-skill baseline of 22.1 to 81.8. Training the skill natively inside Claude Code produced 80.4. The transplant scored slightly higher than the local build, across two harnesses that expose completely different tool surfaces.

If that holds up outside Microsoft's benchmark selection, then the thing carrying the capability isn't the harness, isn't the model, and isn't the tooling. It's a markdown file of roughly 900 tokens.

What SkillOpt actually does

Agent skills today come from three places. A human writes one by hand. A frontier model generates one in a single shot. Or the agent revises its own after a bad run. The Microsoft Research team's complaint about all three is precise: none of them behaves like an optimizer. No step size, no held-out validation, no memory of revisions that failed. So skills grow longer with every rewrite, and a revision that reads perfectly sensibly can make real task performance worse without anyone noticing.

SkillOpt runs the loop you'd run if the skill file were a parameter.

Forward pass: the frozen target model executes a batch of training tasks using the current skill. Backward pass: a separate optimizer model reads the resulting trajectories in reflection minibatches and distills what to keep from the wins and what to correct from the failures. Update: the optimizer proposes small add, delete, and replace edits, which get merged, deduplicated, ranked, and then clipped by a textual learning rate, which is just a per-step edit budget.

Then the part that does the real work. Every candidate skill has to clear a strict validation gate. It's adopted only if it scores strictly higher than the current skill on a held-out split. Fail, and the edit doesn't vanish. It lands in a rejected-edit buffer that feeds back as negative signal to later optimizer calls in the same epoch. On a slower cadence, an epoch-wise meta update consolidates lessons no single batch could reveal.

Bounded edits stop drift. The validation gate stops confident nonsense. The rejected buffer stops the optimizer proposing the same bad idea four times. That's the whole design, and it maps cleanly onto habits any ML engineer already has.

The results, and how to read them

Six benchmarks (SearchQA, SpreadsheetBench, OfficeQA, DocVQA, LiveMathematicianBench, ALFWorld), seven target models from GPT-5.5 down to the 4-billion-parameter open-weight Qwen3.5-4B, three execution modes (direct chat, Codex, Claude Code). Count each combination as a cell and you get 52. Microsoft reports best or tied-best on all 52, measured against human-written skills, one-shot LLM skills, Trace2Skill, TextGrad, GEPA, and EvoSkill.

The gains concentrate on procedural work, which makes sense. SpreadsheetBench goes 41.8 to 80.7. OfficeQA goes 33.1 to 72.1. LiveMathematicianBench goes 37.6 to 66.9. Inside agentic loops, GPT-5.5 picks up 24.8 points in Codex and 19.1 in Claude Code over running with no skill at all.

There's a second result worth more than the first to anyone paying an inference bill. After optimization, GPT-5.4-mini's six-benchmark average of 64.3 clears the no-skill baseline of the larger GPT-5.4 at 59.7. GPT-5.4-nano at 57.4 clears GPT-5.2's 51.3. Qwen3.5-4B, running on hardware you can own, also clears GPT-5.2's baseline. No weights changed. No extra model calls at inference. One file.

And the file is small. Across six case studies the median final skill runs about 920 tokens, and because the gate rejects most proposals, only one to four edits ever make it into the deployed artifact. OfficeQA's 39-point gain came from a single accepted edit. The published skills read like advice from someone who has done the task a hundred times, which is roughly what they are: distilled procedure, not benchmark-specific trickery.

Put this into practice

Don't start with the benchmarks. Start with the one task in your workflow where you already have a way to score an answer automatically.

That's the gating question, and it's worth answering honestly before you install anything. Do you have a test suite, a regex, a diff against a known-good output, a schema validator, a human-labeled set of 40 examples? If yes, SkillOpt has something to optimize against. If the only judge is your own taste after reading the output, you are outside the method's scope and no amount of configuration fixes that.

Assuming you have a scorer, the path is short:

1. pip install skillopt. Python 3.10+, MIT license. Backends cover OpenAI, Azure, Claude, Qwen, and MiniMax, plus an openai_compatible shim that handles most providers implementing the Chat Completions protocol.
2. Point it at your task. A benchmark in SkillOpt terms is a directory with an adapter, a data loader, a scored rollout helper, a YAML config, and optionally a seed skill you already hand-wrote. The searchqa environment in the repo is the simplest reference to copy.
3. Split your examples. The validation gate only means something if the held-out set is genuinely held out. This is where people will cheat themselves and get a skill that memorized the training tasks.
4. Take the resulting best_skill.md, read it, and put it under version control. It's 300 to 2,000 tokens of plain English. You can audit it in two minutes, which is the entire point of optimizing in text space instead of weight space.
5. Try the transfer. Take the skill you trained in one harness and drop it into another. If the Microsoft result generalizes to your task, you just got a second deployment for free. If it doesn't, you learned something specific about how harness-shaped your task is.

The v0.2.0 release from July 2 adds SkillOpt-Sleep, a nightly CLI that harvests past sessions, replays recurring tasks, and consolidates what validates, behind the same gate. It ships integration shells for Claude Code, Codex, Copilot, and Devin. Treat it as a separate decision from the core loop, for reasons in the next section.

Where this breaks

The verifier requirement is not a footnote, it's the boundary of the whole method. SkillOpt is an adaptation layer for work where automatic evaluation exists. Creative work, judgment calls, anything where the answer is "it depends on the client," gets nothing here. Microsoft says as much in the blog post, and I'd rather that be loud than buried.

Every number above is Microsoft's, on Microsoft's benchmark selection, against baselines Microsoft chose. That's normal for a research release and it's still worth saying plainly. The 52-of-52 claim is impressive precisely because it's a sweep, and sweeps are the kind of result that gets softer when someone else picks the cells. I have not seen an independent reproduction.

Training costs real money. Every rollout batch burns target-model calls, and every reflection minibatch burns optimizer-model calls. The deployed artifact adds zero inference cost, which is the good part, but the training run is not free and the repo doesn't publish a dollar figure for a typical convergence.

The nightly engine deserves its own risk budget. A process that rewrites your agent's operating instructions while you're asleep is a bot with commit access to the file your agent trusts most. The validation gate constrains it toward higher scores, which is not the same thing as constraining it toward safe behavior. The release notes themselves flag multi-objective, replay, and dream-rollout controls as experimental, and note the main CLI deliberately keeps conservative defaults rather than exposing every experiment-harness knob.

One small thing I noticed reading the repo that nobody has flagged: the optional WebUI dashboard binds to 0.0.0.0 by default, meaning it listens on every network interface. The README says to pass --host 127.0.0.1 for local-only access. Do that.

And the 13,000 stars are momentum, not a verdict. The project has 272 commits and two releases. It's two months old.

What to take from it

The counter-intuitive read on SkillOpt isn't "Microsoft built a good optimizer." It's what the transfer result implies about the skills economy everyone is currently building.

Five companies this month decided the reusable markdown skill is the artifact worth owning. AWS ships a curated catalog behind a toggle. Alibaba opened its glasses platform to third-party skills. Marketplaces have install counts and one-command updates. All of that assumes the valuable skill is one you acquire from someone else.

Microsoft's own result cuts against that. If a skill trained against your tasks, with your verifier, in your harness, transfers to a different harness and lifts it by 59 points, then the artifact worth having is one you generated and can read, not one you downloaded and trusted. Same file format. Completely different provenance story.

Find the one task you can already grade. Train a skill against it this week. Read the 900 tokens it produces. If they're wrong, you'll know, because it's English.

Sources: Microsoft Research: SkillOpt: Agent skills as trainable parameters, microsoft/SkillOpt on GitHub, SkillOpt v0.2.0 release notes, arXiv:2605.23904.