How to Use SkillOpt to Teach LLM Agents New Skills

Teaching an AI agent a new skill typically means retraining or fine-tuning the model, which demands training data, GPU time, and significant cost. Microsoft Research’s SkillOpt takes a completely different route. Instead of touching the model weights, SkillOpt trains a plain text skill document that tells the agent how to approach a task. The result is a single portable file, best_skill.md, that any compatible model can pick up and use immediately.

This guide covers what SkillOpt is, how it works, and how to install and run it on Windows.

What Is SkillOpt

SkillOpt is an open-source project from Microsoft Research. It treats a natural-language skill document as the trainable state of a frozen language agent. During each training round, a separate optimizer model analyzes the agent’s successes and failures, proposes structured edits (add, delete, or replace) to the skill document, and accepts a change only when it improves a held-out validation score.

The frozen target model never changes. Only the skill document evolves.

At the end of training, SkillOpt exports a compact best_skill.md file, typically 300 to 2,000 tokens. You can reuse that file with the same model, transfer it to a different model size, or even move it between execution environments such as Codex CLI and Claude Code without running another training job.

In published benchmarks across six tasks, seven target models, and three execution harnesses, SkillOpt ranked best or tied-best in all 52 evaluated settings. On GPT-5.5, it lifted average accuracy by +23.5 points in direct chat, +24.8 inside the Codex agentic loop, and +19.1 inside Claude Code compared to running the same model with no skill document.

SkillOpt System Requirements

Before installing SkillOpt, confirm your setup meets these requirements.

Windows 11 or Windows 10
Python 3.10 or later
pip package manager
An API key from a supported provider: OpenAI, Azure OpenAI, Anthropic Claude, Qwen, or MiniMax
Active internet connection

Step 1: Install Python

If Python is not already installed on your machine, follow these steps.

Open your browser and go to python.org.
Download the latest Python 3 release for Windows.
Run the installer.
On the first screen, check Add Python to PATH before clicking Install.
Complete the installation.

To confirm the install worked, open Command Prompt and run:

python --version

The terminal should print the installed Python version number.

Step 2: Install Git and Clone the SkillOpt Repository

SkillOpt requires Git to download the repository. Microsoft recommends installing directly from the cloned source rather than relying on the PyPI package alone.

Go to git-scm.com and download Git for Windows.
Run the installer and complete the setup.
Verify the install by running:

git --version

Clone the SkillOpt repository with this command:

git clone https://github.com/microsoft/SkillOpt.git

Move into the project folder:

cd SkillOpt

Install SkillOpt in editable mode so all dependencies are included:

pip install -e .

If you want support for the optional ALFWorld benchmark, run this instead:

pip install -e ".[alfworld]"

To launch the optional WebUI monitoring dashboard, install the extra and start the server:

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

The dashboard starts on port 7860 by default.

Step 3: Configure Your API Key

SkillOpt needs access to a language model to run both the target agent and the optimizer. Set this up by editing the environment file inside the project folder.

Inside the SkillOpt folder, find the file named .env.example.
Make a copy of it and rename the copy to .env.
Open .env in any text editor.

For an OpenAI-compatible endpoint, add:

AZURE_OPENAI_ENDPOINT=https://api.openai.com/v1
AZURE_OPENAI_API_KEY=your_api_key
AZURE_OPENAI_AUTH_MODE=openai_compatible

For Azure OpenAI, add:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your_api_key

Save the file when done. SkillOpt reads credentials from .env at runtime.

Step 4: Run Your First SkillOpt Training Job

With the API key in place, you can start a training run.

Open Command Prompt and navigate to the SkillOpt folder.
Run the training script:

python scripts/train.py

Depending on the benchmark and model you want to use, you may need to pass additional parameters. The project’s documentation on GitHub lists all available configuration flags.

How SkillOpt Runs Each Training Round

Each training round cycles through five steps.

Rollout: The frozen target model executes tasks using the current skill document and records scored trajectories.
Reflect: The optimizer model analyzes the success and failure batches separately to identify reusable patterns.
Edit: The optimizer proposes add, delete, and replace operations on the skill document, ranked within a textual learning-rate budget that prevents destructive rewrites.
Gate: SkillOpt tests the candidate skill on a held-out validation set. The change becomes permanent only if the score improves over the current best.
Slow update: Periodically, SkillOpt compares a longer history of checkpoints to catch multi-step improvements that a single-round gate would miss.

Rejected edits feed into a buffer that the optimizer uses as negative feedback so it does not repeat the same unhelpful direction.

Training duration depends on the model you use, the dataset size, and the number of optimization rounds you configure.

What Is the best_skill.md File in SkillOpt

When training finishes, SkillOpt writes a best_skill.md file to the output directory. This file contains only the final skill instructions, not any optimizer memory or training history.

You can copy the file to any project and pass it to the same model or a different compatible one. Benchmark tests show the skill transfers across model sizes (a LiveMath skill trained on GPT-5.4 transferred to GPT-5.4-nano with a +15.2 gain) and across harnesses (a SpreadsheetBench skill trained with Codex transferred into Claude Code with a +31.8 gain).

How Skills Work in LLMs

A skill in a large language model is a set of task-specific instructions that help the model perform a particular activity such as coding, summarization, reasoning, or data analysis. Skills can originate from the model’s training data, from fine-tuning, or from external instruction files provided at inference time.

SkillOpt focuses on the third approach. It refines an external instruction file through a disciplined optimization loop rather than altering the model itself. This keeps the underlying model unchanged while steadily improving how it performs a specific task.

Frequently Asked Questions

What models does SkillOpt support?

SkillOpt supports OpenAI models, Azure OpenAI, Anthropic Claude, Qwen, and MiniMax as both target models and optimizer models.

Does SkillOpt modify the AI model?

No. SkillOpt only modifies the text skill document. The target model’s weights stay completely frozen throughout training.

Can I use SkillOpt with a smaller model as the optimizer?

Yes. Even when the target and optimizer are the same smaller model, the constrained and validated update loop can still discover useful edits. Using a stronger optimizer model typically produces larger gains.

How long does training take?

Training duration varies based on the benchmark, the model, and the number of rounds. Larger models and bigger datasets take longer. You can monitor progress through the optional WebUI dashboard.

How to Use SkillOpt to Enable LLM Agents to Learn New Skills Without Fine-Tuning