What is SkillOpt
SkillOpt is Microsoft's open-source Agent skill document optimization tool. The tool brings deep learning training logic into text space, treating skill.md as trainable parameters, generating edit directions through trajectory analysis, constraining bounded modifications with a text learning rate, filtering through a held-out validation set gate, and iteratively producing best_skill.md. SkillOpt supports cross-model and cross-toolchain transfer, with zero deployment overhead. It achieves the best results across all 52 evaluation units, letting Agent skills continuously evolve in a quantifiable and reproducible way like neural networks.
SkillOpt's main features
- Skill document training: Iteratively optimizes skill.md like training a neural network, including forward propagation, backpropagation, parameter updates, and validation gating.
- Bounded edit control: Limits edit magnitude through a text learning rate, avoiding semantic jumps and overwriting effective rules.
- Rejected edit buffer: Records edit directions rejected by the validation gate, preventing the optimization loop from repeating mistakes.
- Cross-model/cross-tool transfer: Skill documents trained on one model can be directly transferred to smaller models in the same series, different toolchains (Codex ↔ Claude Code), or similar benchmarks.
- Zero deployment overhead: The final output is just a 300–2000 token Markdown file, adding no extra inference calls during deployment.
Follow on WeChat and reply “open source" to join theAI open-source project community group
How to use SkillOpt
- Install: Install SkillOpt and its dependencies via pip.
- Configure API: Copy the environment variable template file and fill in the API keys for platforms such as OpenAI, Azure, or Anthropic.
- Prepare data: Split the raw task data into training, validation, and test sets, or let SkillOpt split it automatically.
- Start training: Run the training script and specify the config file, teacher model, and student model to begin iteratively optimizing the skill document.
- Get the output: After training completes, get the final generated best_skill.md skill document and the snapshots of each iteration round from the output directory.
- Deploy and use: Embedding the contents of best_skill.md directly into the target Agent's system prompt takes effect, with no additional inference overhead.
SkillOpt's core advantages
-
Systematic optimization: Say goodbye to the trial-and-error loop of writing docs → running → tweaking by feel, and get a quantifiable, reproducible path to skill improvement.
-
Leading across all scenarios: Achieves best or tied-best results across all 52 evaluation units spanning 6 benchmarks, 7 target models, and 3 execution toolchains.
-
Significant performance improvement: GPT-5.5 improves by an average of +23.5 percentage points; on ALFWorld, GPT-5.4-mini improves from 70.9% to 85.8%.
-
Train once, deploy everywhere: The same
best_skill.mdcan be reused across model scales, Agent toolchains, and similar tasks.
SkillOpt's project address
- Project website：https://microsoft.github.io/SkillOpt/
- GitHub repository：https://github.com/microsoft/SkillOpt
SkillOpt's comparison with similar competitors
| Dimension | SkillOpt | TextGrad | GEPA | Trace2Skill |
|---|---|---|---|---|
| Optimization target | Single skill.md document | Text prompt | Text prompt | Extract rules from trajectories |
| Training discipline | Deep learning-like (epoch, batch, lr, validation gate) | Gradient-based text optimization | Evolutionary algorithms | Trajectory induction |
| Edit control | Bounded edit budget + rejection buffer | No explicit budget control | Mutation selection | No iterative optimization |
| Validation mechanism | Strict held-out validation gate | No explicit validation gate | None | None |
| Cross-model transfer | Native support | Limited | Limited | Limited |
| Deployment overhead | Zero (pure Markdown) | Low | Low | Low |
Application scenarios of SkillOpt
-
Agent skill tuning: Systematically refine skill.md for existing Agents, replacing manual tuning through repeated trial and error based on experience.
-
Multi-model skill reuse: Train skill documents on strong models and deploy them directly to weak models or different toolchains, reducing the cost of multi-model adaptation.
-
Benchmark breakthroughs: Continuously push the performance ceiling on tasks such as SearchQA, SpreadsheetBench, OfficeQA, DocVQA, LiveMath, and ALFWorld.
-
Self-evolution of local coding Agents: Combined with the SkillOpt-Sleep preview, automatically review sessions at night, reproduce high-frequency tasks, and solidify skills that pass validation.