SkillOpt - Microsoft's open-source agent skills documentation optimization tool
SkillOpt is an open-source agent-based skill document optimization tool from Microsoft. The tool introduces deep learning training logic into the text space, treating skill.md as trainable parameters, generating editing directions through trajectory analysis, and constraining them with text learning rates...
What is SkillOpt?
SkillOpt is an open-source agent skills documentation optimization tool from Microsoft. It introduces deep learning training logic into the text space, treating skill.md as trainable parameters. It generates editing directions through trajectory analysis, constrains bounded modifications using text learning rates, and iterates through a validation set to produce the best_skill.md. SkillOpt supports cross-model and cross-toolchain migration with zero deployment overhead. Achieving best performance across all 52 evaluation units allows agent skills to evolve continuously in a quantifiable and reproducible manner, much like a neural network.
The main functions of SkillOpt
- Skills document trainingIteratively optimize skill.md like training a neural network, including forward propagation, back propagation, parameter updates, and validation gating.
- Bounded editing controlThe text learning rate limits the scope of editing, preventing semantic jumps and overwriting of effective rules.
- Refuse to edit bufferRecord the editing direction that is rejected by the verification gate to prevent repeated pitfalls in optimization loops.
- Cross-model/cross-tool migrationSkill documents trained on a single model can be directly transferred to smaller models in the same series, different toolchains (Codex ↔ Claude Code), or similar benchmarks.
- Zero deployment overheadThe final output is only a Markdown file with 300–2000 tokens, and no additional inference calls are added during deployment.
Follow and reply on WeChat “open source",join inAI open source project discussion group
How to use SkillOpt
- InstallInstall SkillOpt and its dependencies via pip.
- Configure APICopy the environment variable template file and fill in the API keys for platforms such as OpenAI, Azure, or Anthropic.
- Prepare data: Divide the original task data into training set, validation set and test set, or let SkillOpt do the division automatically.
- Start trainingRun the training script and specify the configuration file, teacher model, and student model to begin iteratively optimizing the skills document.
- Obtaining productsAfter training is complete, retrieve the final generated best_skill.md skill document and snapshots of each iteration from the output directory.
- Deployment and UseEmbedding the contents of best_skill.md directly into the target agent's system prompt will work without requiring additional inference overhead.
SkillOpt's core advantages
-
System optimizationSay goodbye to the trial-and-error cycle of writing documentation → running → modifying based on intuition, and provide a quantifiable and reproducible path to skill improvement.
-
Leading in all scenariosIt achieved the best or tied best in all 52 evaluation units across 6 benchmarks, 7 target models, and 3 execution toolchains.
-
Significant performance improvementGPT-5.5 improved by an average of +23.5 percentage points; GPT-5.4-mini on ALFWorld improved from 70.9% to 85.8%.
-
One training session, deployed everywhereThe same one
best_skill.mdIt can be reused across model sizes, across agent toolchains, and across similar tasks.
SkillOpt's project address
- Project official websitehttps://microsoft.github.io/SkillOpt/
- GitHub repositoryhttps://github.com/microsoft/SkillOpt
SkillOpt's Competitive Comparison
| Dimension | SkillOpt | TextGrad | GEPA | Trace2Skill |
|---|---|---|---|---|
| Optimization Object | A single skill.md document | Text prompt | Text prompt | Trajectory Extraction Rules |
| Training discipline | Deep learning-like processes (epoch, batch, learner, validation gates) | Gradient-based text optimization | Evolutionary Algorithm | Trajectory Induction |
| Editing control | Bounded editing budget + rejection buffer | No explicit budget control | Mutation selection | No iterative optimization |
| Verification mechanism | Strict held-out verification gate | No explicit verification 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 optimization: Systematically refine skill.md for existing Agents, replacing manual tuning based on repeated trial and error based on experience.
-
Multi-model skill reuseTraining skill documentation on strong models allows for direct deployment to weak models or different toolchains, reducing the cost of adapting to multiple models.
-
Benchmarking BreakthroughContinuously pushing the limits of performance on tasks such as SearchQA, SpreadsheetBench, OfficeQA, DocVQA, LiveMath, and ALFWorld.
-
Local encoding Agent self-evolutionCombined with the SkillOpt-Sleep preview version, it automatically reviews sessions, reproduces high-frequency tasks, and solidifies verified skills at night.