Microsoft SkillOpt: A Portable best_skill.md That Transfers Across Codex and Claude Code

Overview

Microsoft, Shanghai Jiao Tong University, Tongji University, and Fudan University jointly released SkillOpt (arXiv 2605.23904, GitHub microsoft/SkillOpt, PyPI skillopt). The work targets a hard problem in agent tooling: whether a skill optimized in one environment can be moved to another without losing its gains.

The reported answer is aggressive: yes, and in some cases a transferred skill scores higher than one trained in place at the destination.

What SkillOpt Does

SkillOpt is a text-space optimizer. It trains a natural-language skill document (a single Markdown file, 379–1,995 tokens) while the target model remains frozen. An optimizer model reads scored rollouts and proposes bounded add / delete / replace edits. A held-out selection split accepts an edit only when the score strictly improves. The final deliverable is a single file: best_skill.md.

Each edit leaves a trace in edit_apply_report.json with per-edit accept/skip status, so domain experts can read the full artifact in minutes and understand why the skill works.

This differs from related work such as TextGrad, GEPA, EvoSkill, and Trace2Skill, which export parameterized skills or prompt-embedded instructions. SkillOpt exports an auditable Git-diff-shaped asset rather than fine-tuned weights or opaque prompt templates.

Key results

The paper defines three columns for each transfer experiment:

• baseline — destination score with no skill
• direct — destination score after in-domain training
• transferred — destination score when a skill trained elsewhere is dropped in, with zero extra optimization

Cross-model-size transfer (within the GPT-5.4 family)

• SpreadsheetBench on GPT-5.4-mini: baseline 36.1, direct 47.5, transferred 45.5 → 82% of in-domain gain retained (+9.4 vs +11.4).
• SpreadsheetBench on GPT-5.4-nano: baseline 36.1, direct 55.1, transferred 39.1 → only 16% retained (+3.0 vs +19.0).
• LiveMath on GPT-5.4-nano: transferred 28.8 higher than direct 27.2, attributed to learned procedures that are partly independent of the target model.

All four rows stay inside one model family. Cross-family transfer (for example GPT to Qwen 3.5) was not tested.

Cross-harness transfer (the headline finding)

On SpreadsheetBench with GPT-5.5, a skill optimized inside Codex and moved into Claude Code:

• baseline 22.1
• direct (Claude Code trains its own skill) 80.4
• transferred (Codex-trained skill used in Claude Code) 81.8

Transferred beats direct by 1.4 points, meaning SkillOpt produced a Codex-side artifact that out-scored Claude Code's own in-domain training.

LiveMath complicates the story:

• Codex → Claude Code: transferred 42.4 vs direct 56.5 → 10% retention.
• Claude Code → Codex: transferred 48.0 vs direct 78.4 → 30% retention.

The asymmetry is the data point: portable artifacts carry procedural skills (how to inspect, verify, format), while reasoning-dense skills stay bound to the harness where they were trained.

The paper explains SpreadsheetBench portability through workbook-level procedures — inspect the workbook structure and formulas first, write evaluated static values rather than relying on Excel recompute. LiveMath-style skills, by contrast, depend on tool-response formats and filesystem conventions specific to each harness, so they break on transfer.

Cross-benchmark transfer (same model)

Skills trained on OlympiadBench and dropped into Omni-MATH (GPT-5.4 family) yield positive gains across all three model sizes:

• GPT-5.4: transferred 60.3 vs baseline 56.6 (+3.7)
• GPT-5.4-mini: 36.6 vs 34.8 (+1.8)
• GPT-5.4-nano: 40.1 vs 38.8 (+1.3)

No direct column is reported here — Omni-MATH was not used for in-domain training — so the comparison is against baseline only. All three rows show reusable mathematical procedures surviving across instances and answer formats.

Why the artifact is portable

Three execution modes (direct chat, Codex, Claude Code) all consume the same best_skill.md format. Codex renders the current skill into a per-task SKILL.md placed alongside the task file and reads back a compact execution trace. Claude Code mirrors the same workspace contract through its claude CLI. Neither side gets a custom skill format; the shared contract is what makes cross-harness experiments possible.

Training cost

Reported cost: 0.6M–46.4M training tokens per absolute test point (SpreadsheetBench 0.6M/point, DocVQA 46.4M/point). The optimizer only runs during training; deployment has zero optimizer inference cost. When a skill trained on one harness can move to another, that one-time cost amortizes across environments. The Codex → Claude Code SpreadsheetBench result (81.8) is the existence proof — and it implies "optimize where tools are cheapest, deploy where the product ships."

Position in the 2026 H2 agent tooling landscape

• Anthropic Skills / Agent Plugins 1.0.0 — protocol-layer portability via standardized plugin.json schemas (covered here on 08-08).
• Microsoft SkillOpt — experience-layer portability via text-space optimization and cross-model, cross-harness transfer.
• Prime Agent / Continual Harness — adaptive-layer portability via harnesses that CRUD themselves.

Together they form a fuller picture: protocols let a skill be installed, experience makes a skill worth installing, adaptation lets a skill evolve.

Audit and compliance angle

The deployed artifact is a text file a domain expert can read in minutes, and every edit is traceable through edit_apply_report.json. That contrasts sharply with fine-tuned weights as an unauditable black box. Portability plus auditability is a different operational posture, especially for enterprise users — possibly the largest unstated selling point of SkillOpt.

Open questions

• Cross-family transfer (GPT to Qwen, Claude to Llama) was not tested. Whether Agent Plugins 1.0.0's unified protocol can actually carry cross-vendor skills remains unanswered on the SkillOpt side.
• The Codex → Claude Code 81.8 figure is self-reported. End-to-end reproduction on SpreadsheetBench at 0.6M tokens per point with multiple rollbacks has no public reproduction guide.
• The root cause of LiveMath's 10% retention (tool-call format vs internal harness prompt structure) was not decomposed in the paper and is left to future work.
• The optimal composition — train with SkillOpt, distribute through Agent Plugins — has no official integration path yet.
• Anthropic Claude Skills does not appear as a comparison baseline; any collaboration or competitive relationship between the two efforts on cross-harness skills has no public signal.

Sources

• Paper: https://arxiv.org/abs/2605.23904
• GitHub: https://github.com/microsoft/SkillOpt
• Project page: https://microsoft.github.io/SkillOpt/
• Docs: https://github.com/microsoft/SkillOpt/blob/main/docs/index.md
• PyPI: https://pypi.org/project/skillopt/
• Demo video: https://youtu.be/JUBMDTCiM0M
• MarkTechPost coverage: https://www.marktechpost.com/2026/08/05/microsoft-skillopt-agent-skill-transfer-portability
• Comparison baselines: GEPA (https://arxiv.org/abs/2507.19457), TextGrad (https://arxiv.org/abs/2406.07496), EvoSkill (https://arxiv.org/abs/2603.02766), Trace2Skill (https://arxiv.org/abs/2603.25158)
• Cited benchmarks: SpreadsheetBench (https://arxiv.org/abs/2406.14991), LiveMathematicianBench (https://arxiv.org/abs/2604.01754), DocVQA (https://arxiv.org/abs/2007.00398)

One-line takeaway

SkillOpt delivers the first hard evidence for AI coding tooling: a single best_skill.md moves between Codex and Claude Code and scores higher than the destination's own in-domain skill. Competition in the agent toolchain is no longer only "whose harness is better" — it now includes "whose skill can be moved, and still work after the move."