SkillOpt README

The project's README from github.com/microsoft/SkillOpt. As one markdown file: README.md.

SkillOpt: Executive Strategy for Self-Evolving Agent Skills

Train agent skills like you train neural networks — with epochs, (mini-)batchsize, learning rates, and validation gates — but without touching model weights.

Project Page Paper Project Video PyPI Python 3.10+ License: MIT

microsoft%2FSkillOpt | Trendshift microsoft%2FSkillOpt | Trendshift

📖 For installation, data preparation, training/eval commands, configuration, and framework internals, start with the versioned SkillOpt documentation. A concise rendered overview is available in the Documentation & Reproduction Guide, and longer-form engineering analysis appears on the Technical Blog. We also maintain a Changelog for released and unreleased changes.

News 🔥🔥🔥

Overview

Modern agent skills are usually hand-crafted, generated one-shot by a strong LLM, or evolved through loosely controlled self-revision — none of which behaves like a deep-learning optimizer for the skill itself, and none of which reliably improves over its starting point under feedback.

SkillOpt treats the skill document as the trainable state of a frozen agent, and trains it with the discipline that makes weight-space optimization reproducible. A separate optimizer model turns scored rollouts into bounded add / delete / replace edits on a single skill document; in the default paper-style path, a candidate edit is accepted only when it strictly improves a held-out validation score. A textual learning-rate budget, a rejected-edit buffer, and an epoch-wise slow / meta update make skill training stable while adding zero inference-time model calls at deployment.

The deployed artifact is a compact best_skill.md (typically 300–2,000 tokens) that runs against the unchanged target model. Across six benchmarks, seven target models, and three execution harnesses (direct chat, Codex CLI, Claude Code CLI), SkillOpt is best or tied-best on all 52 evaluated (model, benchmark, harness) cells and on GPT-5.5 lifts the average no-skill accuracy by +23.5 points in direct chat, +24.8 inside the Codex agentic loop, and +19.1 inside Claude Code. Optimized skill artifacts transfer across model scales, between Codex and Claude Code harnesses, and to nearby benchmarks without further optimization.

For the full method, ablations, and per-cell results see the paper; for a visual walkthrough of the loop see the project page; for deeper API / backend / benchmark docs see docs/.

🎬 Demo Video

https://github.com/user-attachments/assets/eb12d3bc-371c-467f-904d-91b61f339ed7

▶ Watch the full demo on YouTube

Extensibility & WebUI

Adding a new backend

A backend = a chat / exec target (e.g. openai_chat, claude_chat, qwen_chat, minimax_chat, copilot_chat, openai_compatible, codex_exec, claude_code_exec, cursor_exec, copilot_exec). If a provider implements the OpenAI Chat Completions protocol, try the built-in openai_compatible backend before adding code. See docs/guide/new-backend.md for the full contract. Chat backends add a skillopt/model/<name>_backend.py module; target-only exec backends use the shared harness in codex_harness.py. Both register through common.py, backend_config.py, and skillopt/model/__init__.py.

Adding a new benchmark

A benchmark = a skillopt/envs/<name>/ package with an adapter, a data loader, a scored rollout helper, a YAML config, and optionally an initial seed skill. See docs/guide/new-benchmark.md for the full contract; the simplest reference is skillopt/envs/searchqa/.

WebUI

Launch the monitoring dashboard (optional):

pip install -e ".[webui]"
python -m skillopt_webui.app
Flag Default Description
--port 7860 Server port
--host 0.0.0.0 Bind address
--share off Create a public Gradio share link

The default host listens on every network interface. Use --host 127.0.0.1 for local-only access.

Citation

@article{yang2026skillopt,
  title={Skillopt: Executive strategy for self-evolving agent skills},
  author={Yang, Yifan and Gong, Ziyang and Huang, Weiquan and Yang, Qihao and Zhou, Ziwei and Huang, Zisu and Li, Yan and Gao, Xuemei and Dai, Qi and Liu, Bei and others},
  journal={arXiv preprint arXiv:2605.23904},
  year={2026}
}

SkillOpt (microsoft/SkillOpt)

Searching Database…

18.5K ·GitHub
SkillOpt
What is this?A text-space optimizer that trains reusable natural-language skills for frozen LLM agents without touching model weights. The trained skill ships as a compact markdown file (typically 300–2,000 tokens) that adds zero inference-time model calls at deployment.
Is this a library I import, or a command-line tool I run?Both: it is a Python package on PyPI with a skillopt CLI (plus a skillopt-sleep companion CLI) and an optional Gradio WebUI dashboard. You extend it by writing Python modules for new backends or benchmarks.
How do I get it running?Install it with pip install skillopt, configure a backend, and run the training loop (rollout → reflect → aggregate → select → update → evaluate). Optionally launch the WebUI dashboard on port 7860 to monitor runs.
Which LLM providers can it optimize against?Built-in chat backends cover OpenAI, Azure, Claude, Qwen and MiniMax, and any provider speaking the OpenAI Chat Completions protocol works via the openaicompatible backend. There are also exec backends for Codex CLI, Claude Code, Cursor and Copilot.
Does pip install give me everything from the release notes?No. The main CLI keeps conservative defaults and does not expose every experiment-harness control as a flag, and the coding-agent integration shells (Claude Code, Codex, Copilot, Devin, OpenClaw) live in the repository rather than the PyPI wheel.
Will it run on my Windows machine, or is it Linux-only?It is a cross-platform Python package with explicit Windows support — the v0.2.0 release specifically adds Windows robustness alongside Linux and macOS.
How does the training loop actually work?Each round the agent rolls out tasks and a separate optimizer model turns the scored trajectories into bounded add, delete or replace edits on the skill document. In the default path an edit is accepted only when it strictly improves a held-out validation score, and a textual learning-rate budget plus a rejected-edit buffer keep training stable.
What is SkillOpt-Sleep?A nightly offline self-evolution engine shipped as the skillopt-sleep CLI. It reviews past sessions of local coding agents like Claude Code, Codex and Copilot, replays recurring tasks and consolidates validated skills behind a held-out validation gate.
How much does it actually improve agents?Across six benchmarks, seven target models and three harnesses it was best or tied-best on all 52 evaluated cells. On GPT-5.5 it lifts average no-skill accuracy by +23.5 points in direct chat, +24.8 in the Codex agentic loop and +19.1 in Claude Code, and trained skills transfer across model scales and harnesses.
Can I plug in my own backend or benchmark?Yes. A backend is a chat or exec target registered through a few Python modules (see docs/guide/new-backend.md), and if a provider speaks the OpenAI Chat Completions protocol the built-in openaicompatible backend may already work. A benchmark is a skillopt/envs package with an adapter, a data loader and a YAML config — searchqa is the simplest reference.
What are similar projects?jev-align, hermes-agent-self-evolution, OmniParser, darwin-skill, wikiskill, benjamin-plus-skill, CUAWright, arc-code
Which topics is it in?optimizer, self-evolving-agents, minimax, gradio, optimization, microsoft, qwen, evaluation, prompt-engineering, anthropic, dashboard, benchmark
Creator
microsoft
Size
24.2 MB
Stars
18.5K
Updated
CommitOct 06Releasev0.2.0Jul 02
Age
5mo
Commits · 90 Days