SkillOpt trains an agent's skill file the way you train model weights: an optimizer model turns scored rollouts into small add/delete/replace edits, and a held-out validation gate accepts only edits that raise the score. The model stays frozen. The skill document is the thing that learns.
Agent harnesses such as Claude Code and Codex let you attach a skill: a Markdown document that tells the agent how to work in a domain. The skill holds procedures, tool policies, output formats, and known failure modes. Today these documents come from three sources. A person writes one by hand. A model generates one in a single pass. Or the agent revises its own skill after failures, with little control. The authors state that none of these methods reliably improves a skill over its starting point.
Model weights are trained under strict discipline: batches, learning rates, validation sets, checkpoints. Skill documents get none of that discipline, although they now carry much of an agent's domain adaptation. The paper asks a direct question: if the skill is the adaptation layer, how should we optimize it?
SkillOpt treats the skill document as the trainable state of a frozen agent. The target model never changes. A second model, the optimizer, edits the skill. Each part of a deep-learning training loop has a text counterpart.
The loop works like this. The target model runs a batch of tasks with the current skill. The optimizer reads the trajectories, separates successes from failures, and reflects on them in small groups rather than one at a time. A single trajectory yields a fix for one case; a group exposes a recurring procedural error, such as the agent that always writes answers in the wrong format. Each reflection proposes structured edits: add a rule, delete a rule, or replace a rule.
Three controls keep the loop stable.
An edit budget is the learning rate. The optimizer ranks all proposed edits and applies only the top few per step. An unbounded rewrite can erase useful rules or overfit to one failure. A bounded update keeps each skill version close to the last one, so the edit history stays meaningful.
A held-out gate is the validation set. Each candidate skill runs on a selection split the optimizer never trains on. The candidate is accepted only if its score is strictly higher; ties are rejected. This matters because a diagnosis can read as plausible and still make the real agent worse.
Rejected edits become negative feedback. A buffer records each rejected edit and the score drop it caused. Later optimizer calls see this buffer and do not repeat the failed edit.
At the end of each epoch, a slow update writes durable lessons into a protected region of the skill that step-level edits cannot overwrite. The exported result is one best_skill.md of roughly 400 to 2,000 tokens. Deployment adds zero optimizer calls: the agent just loads the file.
The evaluation covers six benchmarks (search QA, spreadsheets, office documents, document images, competition math, and the ALFWorld household simulator), seven target models from the GPT and Qwen families, and three execution modes: direct chat, the Codex harness, and the Claude Code harness. The authors report that SkillOpt is best or tied-best in all 52 tested combinations of benchmark, model, and harness, against human-written skills, one-shot generated skills, and the optimizers TextGrad, GEPA, Trace2Skill, and EvoSkill.
The gains for GPT-5.5 in direct chat: SpreadsheetBench rises from 41.8 to 80.7, OfficeQA from 33.1 to 72.1, competition math from 37.6 to 66.9. The average gain over no skill is +23.5 points in direct chat, +24.8 inside Codex, and +19.1 inside Claude Code.
There are caveats. The gains are largest on procedural benchmarks, where format and tool discipline dominate; on tasks the model already does well, the gain is smaller. Some baselines are already strong: EvoSkill lifts the spreadsheet score inside Codex from 27.5 to 67.5 on its own, and SkillOpt adds 17.5 more points. All numbers come from the authors' own benchmark and split choices, with the baselines run by the authors. Training is not free: one benchmark took between 21M and 214M optimizer-loop tokens, which is 0.6M to 46M tokens per point of test gain. That cost is paid once, before deployment.
The transfer results support the claim that the skill file is reusable. A skill trained on GPT-5.4 improves the smaller mini and nano variants. A spreadsheet skill trained inside Codex, moved to Claude Code without further training, gains +59.7 points over the Claude Code baseline and slightly beats the skill trained inside Claude Code itself. Cross-benchmark transfer (olympiad math to a different math benchmark) stays positive but small, +1.3 to +3.7.
The ablations show where the value sits. Remove the epoch-level slow update that protects durable lessons, and SpreadsheetBench falls from 77.5 to 55.0. Remove the rejected-edit buffer, and scores drop 1.6 to 4.6 points. And the accepted-edit counts are low: each final skill contains only 1 to 4 accepted edits. The gate rejects most of what the optimizer proposes.
The learned rules are procedural, not instance-specific. The spreadsheet skill learns: inspect the workbook structure and formulas, then write evaluated static values across the full requested range instead of relying on Excel recalculation. The ALFWorld skill learns: keep a ledger of visited locations, diversify the search after repeated same-type failures, and do not revisit the destination until the agent holds the target object. These read like rules an engineer would write after a day with the task, and each one passed a held-out score check before it entered the file.
The code is at aka.ms/SkillOpt. To use the loop you need three things: a task set with an automatic score (a test suite, exact match, or a verifier), split into train, selection, and test; a frozen agent with a skill slot, which Claude Code and Codex both provide; and a token budget for the optimizer model. The best fit is a task where your agent fails on procedure, such as output format, tool order, or missing verification steps, rather than on knowledge.
Two limits apply. Without an automatic scorer there is no gate, and the gate is the core of the method; the authors list preference-based gates as future work. And a skill trained by this loop is still a text file: you can read it, audit it, and hand-edit it after training, which weight updates do not allow.