In short: Microsoft Research’s SkillOpt turns AI agent skills into trainable artifacts. Instead of hand-writing CLAUDE.md, AGENTS.md, or best_skill.md and hoping the rules work, SkillOpt runs the agent, studies its failures, applies bounded text edits, validates the candidate skill, and keeps only changes that improve performance.

Every serious AI agent user eventually starts writing instruction files: CLAUDE.md, AGENTS.md, best_skill.md, project rules, tool-use notes, formatting constraints, debugging routines.

The pattern is familiar. You watch the agent fail a few times, write a better rule, rerun the task, then add another note. After a while, the instruction file becomes a small operating manual.

If you work with Claude Code, Codex, Cursor, or any agent that lives inside a real project, this file quickly becomes part of the product. It tells the agent how to inspect files, when to run tests, how to format answers, which tool calls are safe, what to avoid in production code, and how to recover from common mistakes.

The problem is that most of these files are written by feel. You notice a failure, write a rule, and hope the next run behaves better. Sometimes it does. Sometimes the new rule helps one task and harms another. Sometimes the instruction sounds precise to you but remains too vague for the model that has to act on it.

That is the opening SkillOpt pushes on. Microsoft Research’s new project, SkillOpt, asks why these manuals are still mostly hand-written.

The paper, SkillOpt: Executive Strategy for Self-Evolving Agent Skills, treats the skill document itself as the trainable object. Model weights, backend, and harness stay fixed while a compact natural-language skill file improves over time.

Cover - Stop Hand-Writing Agent Skills

The Core Idea

SkillOpt turns skill writing into a training loop.

A target model runs tasks with the current skill. An optimizer model studies the traces. It proposes small edits to the skill. The candidate skill is tested on a held-out validation split. If the score improves, the edit is accepted. If not, it is rejected and remembered as a bad direction.

In other words, the skill file becomes the agent’s mutable external state. SkillOpt keeps the model, harness, and evaluator constant, then trains the procedure that sits in front of them.

That loop is simple:

  1. Roll out tasks with the current skill.
  2. Reflect on successes and failures.
  3. Edit the skill with bounded add, delete, or replace operations.
  4. Validate the candidate skill.
  5. Export the best best_skill.md.

SkillOpt pipeline

The analogy to neural network training is practical. A rollout batch works like a forward pass. Reflection works like a text-space backward pass. The edit budget acts like a learning rate. The validation gate plays the role of model selection.

The result is a skill document that improves through evidence instead of guesswork.

What Counts as a Skill

A skill is a short procedural artifact. It may be injected as a prompt prefix, but in an agent stack it can encode domain heuristics, tool policies, output formats, recovery routines, and failure cases.

For a spreadsheet agent, a useful skill might say: inspect workbook structure before writing code; normalize keys before joining tables; reopen the saved workbook to verify boundary rows; write evaluated static values when the grader reads cells directly.

For a document QA agent, a useful skill might say: bind the question to the exact table row, header, legend, or form field before copying an answer span. For an embodied agent, it might say: maintain a visited/frontier ledger and stop revisiting exhausted locations.

These are operating rules, the kind a careful practitioner writes after seeing the same failure three times.

Writing a rule is easy. Choosing the rule that belongs in the file is harder. A skill can be too short, too broad, too brittle, too verbose, or simply wrong for the model that consumes it.

SkillOpt’s design keeps the question concrete: does the target agent actually perform better after the rule is added?

Two Models, Two Jobs

SkillOpt separates execution from optimization.

The target model is the model you want to improve. It may be GPT-5.5, GPT-5.4-mini, Qwen, or a model running inside a tool harness such as Codex or Claude Code. This model performs the actual tasks with the current skill file. Its weights stay frozen.

The optimizer model is the editor. It reads the target model’s trajectories, studies successes and failures, and proposes edits to the skill. This optimizer can be stronger than the target model because it is only used offline during training.

That split has a practical benefit: the expensive optimizer does not run at deployment time. Once training finishes, the target model receives only the exported best_skill.md. No extra optimizer calls are needed.

The paper also tests what happens when the optimizer is not stronger. A target-matched optimizer still recovers a substantial share of the gain, about 56% to 74% of the strong-optimizer improvement in the reported cells. A stronger optimizer helps, but the training loop is doing real work on its own.

Why Small Edits Matter

One tempting approach would be to let a strong model rewrite the whole skill file after every batch. SkillOpt avoids that.

Instead, it limits each update to a small number of edits. The paper calls this a textual learning rate. The default setting allows only a few edits per step, often four.

That restraint matters. Big rewrites can erase useful rules, mix good changes with bad ones, or overfit to a local failure. Small edits preserve continuity. They also make it easier to audit what changed and why.

SkillOpt also keeps a rejected-edit buffer. When a proposed change fails validation, the system records it. The optimizer sees that failure later and can avoid repeating the same mistake.

There is also a slower update path across epochs. This slow/meta update captures longer-term patterns, while step-level edits handle immediate failures.

The ablations make this less theoretical. Removing the rejected-edit buffer hurts all three reported ablation benchmarks. Removing both meta skill and slow update is especially damaging on SpreadsheetBench, dropping the score from 77.5 to 55.0 in the matched setting.

Ablation results

SkillOpt adds discipline to skill writing: small edits, explicit validation, memory of bad updates, and slower consolidation across epochs.

The Results

The numbers are the reason SkillOpt is getting attention.

Across six benchmarks, seven target models, and three execution settings, SkillOpt is best or tied-best in all 52 evaluated cells.

On GPT-5.5 in direct chat, the average score rises by +23.5 points over no skill. Some task gains are much larger:

  • SearchQA: 77.7 to 87.3
  • SpreadsheetBench: 41.8 to 80.7
  • OfficeQA: 33.1 to 72.1
  • DocVQA: 78.8 to 91.2
  • LiveMath: 37.6 to 66.9
  • ALFWorld: 83.6 to 95.5

Training curves

The biggest gains show up in procedural tasks. Spreadsheet manipulation, office QA, tool use, and embodied environments all benefit from concrete operating rules.

A rule like this can change behavior dramatically:

Inspect workbook structure and formulas, then write evaluated static values across the full requested target range instead of relying on Excel recalculation.

That is the kind of instruction a human might discover after many failures. SkillOpt learns it from rollouts.

The gains also hold outside direct chat. In the paper, GPT-5.5 improves by +24.8 points on average inside the Codex harness and by +19.1 inside the Claude Code harness. That matters because many real agents do not answer in a single chat turn. They inspect files, run commands, call tools, write code, and react to verifier feedback.

Full result matrix

The method also works across model scales. The paper reports consistent positive gains for frontier GPT models, smaller GPT variants, and Qwen models. Smaller models often benefit more in relative terms because a compact skill can supply procedures that the model has not internalized.

For practitioners, this is one of the more useful findings. Skill optimization can squeeze more performance out of the strongest model, but it can also make cheaper or smaller models more reliable in a narrow domain.

Better Than Hand-Written Skills

The paper compares SkillOpt against human-written skills, one-shot LLM-generated skills, Trace2Skill, TextGrad, GEPA, and EvoSkill.

SkillOpt beats them across the board.

Method comparison

Hand-written skills are often useful starting points. The problem is that human authors rarely know which rules are missing, which ones are too vague, or which ones will hurt a specific target model.

That point connects directly to Microsoft’s related project, SkillLens. SkillLens studies model-generated skills across the full lifecycle: experience generation, skill extraction, and skill consumption. Its main finding is sobering: skills help on average, but roughly a quarter of extractor-target pairs suffer negative transfer.

A skill that reads well may still perform badly. The only reliable judge is downstream utility.

SkillOpt builds that lesson into the loop. Every candidate skill must earn its place through validation.

The comparison set is strong enough to be meaningful. Human-written skills are not straw men. One-shot LLM skills are the obvious automation baseline. Trace2Skill distills lessons from trajectories. TextGrad and GEPA represent language-level prompt optimization. EvoSkill is a closer skill-evolution competitor in tool-backed settings.

SkillOpt’s edge comes from combining the pieces: it optimizes a persistent skill artifact, limits each edit, validates every candidate, and keeps negative feedback from rejected updates.

What the Learned Skills Look Like

The final skills are surprisingly small. In the paper’s case studies, they range from a few hundred to under 2,000 tokens. Many runs accept only one to four edits.

The rules are specific:

  • For SearchQA, infer the expected answer type and choose the shortest canonical entity supported by distinctive evidence.
  • For DocVQA, bind the question to the exact row, header, field, or visual region before copying the answer.
  • For ALFWorld, maintain a visited/frontier ledger and avoid looping through exhausted locations.
  • For math multiple choice, rank options by theorem strength, not just truth.

Good skills are procedural. They tell the agent what to do when the task shape changes.

The best rules look ordinary once you see them. They read like crisp operational advice rather than magic prompts:

Infer the expected answer type from clue wording, then choose the shortest canonical entity supported by co-occurring distinctive evidence.

For tables, forms, charts, and legends, first bind the question to the exact visual row/header/field, then copy only the aligned answer span.

Keep a horizon-aware visited/frontier ledger, diversify search after repeated same-type failures, and avoid revisiting the destination until holding the target.

Ornate wording is beside the point. The exact failure mechanism matters. Generic advice such as “think carefully” or “double-check your work” rarely changes an agent’s behavior. A concrete rule about when to inspect, what to bind, or which state to track often does.

How a Skill Evolves

The final skill file hides the path that produced it. SkillOpt’s traces are useful because they show the document becoming more operational over time.

Take ALFWorld. The initial skill is a broad household plan: search for the object, pick it up, transform it if needed, and place it at the destination. That is reasonable, but it does not prevent loops or object confusion.

After rollout evidence, SkillOpt adds rules about exact object-name matching. A mug is not a cup; a pan is not a pot. It adds visited-location memory so the agent stops checking the same exhausted places. It adds progress locks so that once the agent holds the object or completes a transformation, it avoids unnecessary actions that can undo progress.

SpreadsheetBench shows a similar pattern. The starting skill already tells the agent to use spreadsheet libraries and preserve unrelated content. The optimized skill becomes much more forensic: inspect the actual workbook, locate headers and target ranges across sheets, normalize keys and cell types, preserve formatting, compute static values when the grader reads cells, and reopen the saved workbook to verify the result.

The lesson is straightforward: strong skills usually come from work, not from a blank page.

Transfer Across Models and Environments

A trained skill is more useful when it survives beyond one exact setup. SkillOpt tests three kinds of transfer: across model sizes, across execution harnesses, and across nearby benchmarks.

The results are positive across the reported transfer rows. A SpreadsheetBench skill trained on GPT-5.4 improves smaller GPT variants. A Codex-trained SpreadsheetBench skill transfers to Claude Code with a large gain. An OlympiadBench skill gives positive gains on Omni-MATH.

The cross-harness result is especially interesting. Codex and Claude Code expose different execution surfaces, but a spreadsheet skill can still transfer because much of the learned procedure targets workbook behavior: inspect structure, reason about formulas, materialize values, and verify saved output.

That makes the economics more attractive. You can pay the training cost once, audit the exported skill as text, and reuse it in related environments.

What It Costs

Training still costs money. SkillOpt requires rollout computation, optimizer calls, and a validation split with reliable scoring. The paper reports training-token costs that vary sharply by benchmark.

Shorter procedural benchmarks are relatively cheap per point of improvement. More expensive settings, such as rich retrieval or document contexts, consume far more tokens per point. That is expected: the optimizer has to read trajectories, context, tool outputs, and verifier feedback.

The deployment cost is the important part. After training, the exported skill is just text. It adds no optimizer calls and no model-weight changes. If an agent will run the same kind of task many times, that one-time training cost can be easy to justify.

Try It Yourself

The code is available on GitHub under the MIT license. The repository includes training scripts, evaluation scripts, benchmark adapters, optimizer prompts, model backends, and a WebUI for monitoring runs.

Installation is straightforward:

git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt
pip install -e .

You then configure credentials. Azure OpenAI is the recommended path in the README, but the repo also supports OpenAI, Anthropic Claude, and Qwen through local vLLM.

cp .env.example .env
source .env

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_API_KEY="your-key"

A basic training command looks like this:

python scripts/train.py \
  --config configs/searchqa/default.yaml \
  --split_dir /path/to/your/searchqa_split \
  --optimizer_model gpt-5.5 \
  --target_model gpt-5.5 \
  --num_epochs 4 \
  --batch_size 40

The output directory contains the artifact that matters:

outputs/<run_name>/
├── best_skill.md
├── history.json
├── runtime_state.json
├── skills/
├── steps/
├── slow_update/
└── meta_skill/

best_skill.md is the deployable file. The optimizer model is no longer needed at inference time.

You can also run evaluation directly:

python scripts/eval_only.py \
  --config configs/searchqa/default.yaml \
  --skill outputs/my_run/best_skill.md \
  --split valid_unseen \
  --split_dir /path/to/searchqa_split

The optional WebUI gives you a way to monitor the run:

pip install -e ".[webui]"
python -m skillopt_webui.app --port 7860

The repository currently supports SearchQA, SpreadsheetBench, OfficeQA, DocVQA, LiveMathematicianBench, and ALFWorld. The datasets are not bundled, so you need to prepare split directories with train/, val/, and test/ JSON files.

Where SkillLens Fits

SkillOpt is easier to understand next to SkillLens, a related Microsoft Research project.

SkillLens studies the full lifecycle of model-generated skills: experience generation, skill extraction, and skill consumption. Its finding is practical rather than comforting. Model-generated skills help on average, but utility depends on the extractor, the target model, the domain, and the experience pool. Some skills transfer negatively.

That study also finds that surface plausibility is a poor predictor of utility. An LLM judge asked to pick the better skill does not reliably choose the one that improves downstream performance.

SkillOpt can be read as the engineering response to that result. It replaces surface judgment with validation against actual task performance.

The Limitation

SkillOpt works best when the task has a reliable score. Exact match, executable checks, benchmark verifiers, and automatic grading all fit the method well. Open-ended tasks are harder because the validation gate needs trustworthy feedback.

It also optimizes one skill artifact for a domain. If the domain contains many unrelated workflows, a skill library may be a better structure than one file. The paper points to this as a natural extension.

Overfitting to a benchmark or training distribution remains a risk. The held-out gate helps, but evaluation is still needed before deployment in a new setting.

The Takeaway

Skill files should not be treated as one-off prompt documents.

They are closer to operating policies: compact, inspectable, testable, and improvable. SkillOpt shows that they can be trained with the same discipline engineers already use elsewhere: batches, learning rates, validation gates, rejected updates, checkpoints.

Hand-writing a skill is still useful. It gives the agent a starting procedure.

But the better workflow is to let real failures shape the document. Run the agent. Measure it. Patch the skill. Validate the patch. Keep only what works.

That is the shift SkillOpt points toward: agent skills as trained artifacts rather than static instructions. ByteDance reaches a similar place from a different direction in MUSE-Autoskill, where an agent creates, tests, and migrates its own skills as lifecycle assets.