← Back to Home

SkillOpt: Train Agent Skills Like Neural Networks — Without Touching Model Weights

2026-06-16

SkillOpt: Train Agent Skills Like Neural Networks — Without Touching Model Weights

AI agents today either use hand-crafted skills (slow to iterate), one-shot generated prompts (unreliable), or loosely controlled self-revision (no quality guarantees). None of these behave like a real optimizer — and none reliably improve over their starting point under feedback.

Microsoft SkillOpt changes this completely. It treats the skill document itself — a plain Markdown file — as the trainable state of a frozen agent, and optimizes it with the same discipline that makes weight-space deep learning reproducible. Rollouts, backward passes, gradient clipping, validation gates, learning rate schedulers — SkillOpt maps them all onto natural-language skill editing.

With 7,400+ GitHub stars in just over a month, SkillOpt is already integrated by gbrain, gbrain-evals, and darwin-skill. Across 52 evaluated (model, benchmark, harness) cells, it is best or tied-best on all of them — lifting GPT-5.5's average no-skill accuracy by +23.5 points in direct chat, +24.8 inside the Codex agentic loop, and +19.1 inside Claude Code.

It's open-source under MIT, Python 3.10+, and installs via pip. The deployed artifact is a compact best_skill.md (300–2,000 tokens) that adds zero inference-time overhead.

Why It's Trending

Four forces are driving SkillOpt's explosive growth:

  1. The agent skill bottleneck is real. Everyone building AI agents (Claude Code, Codex, Copilot, OpenHands) needs high-quality skill prompts. Hand-crafting them is slow; one-shot generation is inconsistent. SkillOpt's optimization loop is the first systematic solution.

  2. Zero inference-time overhead. Unlike RAG, fine-tuning, or tool-calling pipelines, SkillOpt's optimized skill is a plain text file. At deployment, it costs nothing — no extra model calls, no latency, no infrastructure.

  3. Benchmarks don't lie. 52/52 best-or-tied across 6 benchmarks, 7 target models, and 3 execution harnesses. The paper shows SkillOpt improving performance on every single configuration tested, with gains that transfer across model scales and between Codex and Claude Code.

  4. The SkillOpt-Sleep companion (June 2026 preview) brings the same discipline to your daily coding sessions — a nightly "sleep cycle" that mines your own Claude Code / Codex transcripts, replays recurring tasks, and consolidates validated skills offline.

Architecture

SkillOpt Architecture

The training loop mirrors deep learning at every stage:

  • Skill Document (the trainable state): A Markdown file (300–2,000 tokens) that acts as the agent's system prompt. This is the only thing that changes during training — the underlying LLM weights stay frozen.

  • Frozen Target Model: The LLM that executes tasks using the current skill. SkillOpt supports OpenAI, Azure OpenAI, Claude, Qwen (local vLLM), and MiniMax — all as drop-in backends.

  • Optimizer Model: A separate, typically more capable model (GPT-5.5 by default) that analyzes failed trajectories and produces bounded add/delete/replace edits on the skill document. It never executes tasks — it only improves the skill.

The Training Loop

Phase Deep Learning Analogy What Happens
1. Rollout Forward pass Target model executes tasks using current skill → trajectories + scores
2. Reflect Backward pass Optimizer analyzes failures → generates edit patches
3. Aggregate Gradient accumulation Semantically similar patches merged to avoid redundant edits
4. Select Gradient clipping Top-K edits selected by learning_rate parameter; scheduler decays over epochs (cosine, linear, or constant)
5. Update Parameter update Bounded add/delete/replace edits applied to the skill document
6. Gate Validation check Updated skill tested on held-out selection split; accepted only if score improves

Epoch Boundary mechanisms prevent catastrophic forgetting:

  • Slow Update (Momentum): At epoch end, both the previous and current skills are rolled out on the same samples. Items are categorized as improved/regressed/persistent failure/stable success, and high-level guidance is injected into the skill document.

  • Meta Skill (Optimizer Memory): Cross-epoch strategy notes accumulated across the entire training run, provided as context during future reflection steps.

Prerequisites

  • Python 3.10 or later
  • An API key for at least one supported backend (Azure OpenAI, OpenAI, Anthropic Claude, or local Qwen via vLLM)
  • At least 4GB RAM (16GB recommended for ALFWorld benchmarks)

Installation

Clone the repo and install:

git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt
pip install -e .

Optional extras:

# For Claude support
pip install -e ".[claude]"

# For local Qwen inference
pip install -e ".[qwen]"

# For the monitoring WebUI dashboard
pip install -e ".[webui]"

# ALFWorld benchmark
pip install -e ".[alfworld]"

Set up your API credentials:

cp .env.example .env
# Edit .env with your API keys

Configuration

SkillOpt uses YAML configs that inherit from a shared base. Here's the key configuration for a SearchQA experiment (configs/searchqa/default.yaml):

model:
  backend: azure_openai
  optimizer: gpt-5.5
  target: gpt-5.5

train:
  num_epochs: 4
  batch_size: 40

optimizer:
  learning_rate: 4          # max edits per step
  lr_scheduler: cosine      # learning rate decay schedule
  use_slow_update: true     # epoch boundary momentum
  use_meta_skill: true      # cross-epoch optimizer memory

evaluation:
  use_gate: true            # accept only if score improves

Running Your First Experiment

SkillOpt ships with 6 built-in benchmarks. Let's run the fastest one — SearchQA:

python scripts/train.py --config configs/searchqa/default.yaml

You'll see output like this:

[Step 1/8] Rollout: 20 items, 4 workers...
[Step 1/8] Score: 0.65 → Reflect...
[Step 1/8] 6 edit patches generated
[Step 1/8] Selected 4 edits (lr=8, cosine → 7.7)
[Step 1/8] Gate: val score 0.68 > 0.65 ✓ ACCEPT
[Step 2/8] ...

Training outputs are saved to outputs/<benchmark>/<run_id>/:

outputs/searchqa/2026-06-01_10-30-00/
├── steps/
│   ├── step_0001/
│   ├── step_0002/
│   └── ...
├── slow_update/
│   └── epoch_02/
├── meta_skill/
│   └── epoch_02/
├── skills/
│   └── step_0001.md
├── best_skill.md
└── history.json

After training completes, evaluate the best skill on the test split:

python scripts/eval_only.py \
--config configs/searchqa/default.yaml \
--skill outputs/searchqa/<run_id>/skills/best_skill.md

WebUI Dashboard

Prefer a visual interface? Launch the monitoring dashboard:

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

Then open http://localhost:7860 in your browser.

Adding a New Benchmark

Extending SkillOpt to your own task is straightforward (~200 lines):

  1. Data Loader — implement a SplitDataLoader subclass that loads train/val/test items
  2. Rollout Helper — runs the target model on items under the current skill and scores predictions
  3. EnvAdapter — wires the loader + rollout into SkillOpt's lifecycle
  4. YAML Config — references your env name and training parameters

The skillopt/envs/_template/ directory provides a complete starting point.

Adding a New Model Backend

SkillOpt's pluggable backend system lets you add any LLM provider:

  1. Create skillopt/model/your_backend.py extending ModelBackend
  2. Implement _init_client() and async generate()
  3. Register in skillopt/model/common.py + backend_config.py

See skillopt/model/qwen.py or skillopt/model/minimax.py for clean templates.

SkillOpt-Sleep: Nightly Self-Evolution

The June 2026 preview of SkillOpt-Sleep brings the same optimization discipline to your daily workflow:

  • Mines transcripts from Claude Code, Codex, or Copilot sessions
  • Identifies recurring tasks and replays them offline
  • Consolidates validated skill improvements behind a held-out validation gate
  • Staged proposals for your review each morning

Install for your agent:

Platform Install
Claude Code /plugin marketplace add ./plugins/claude-code → /skillopt-sleep
Codex bash plugins/codex/install.sh → skillopt-sleep skill
Copilot Register plugins/copilot/mcp_server.py as an MCP server

Results on the SearchQA benchmark show +3.1 to +4.5 percentage point lifts from experience replay alone, with gains rising monotonically with how much relevant past is recalled.

Verification Checklist

  • python -c "import skillopt; print('Ready!')" succeeds
  • Training logs show score improvements across steps and epochs
  • best_skill.md is created in the output directory
  • The optimized skill improves held-out test scores vs. the initial seed
  • Evaluate across at least 2 different target models to verify transfer

Resources

← Retour à l'Accueil

SkillOpt : Entraînez des Compétences d'Agent Comme des Réseaux de Neurones — Sans Toucher aux Poids du Modèle

2026-06-16

SkillOpt : Entraînez des Compétences d'Agent Comme des Réseaux de Neurones — Sans Toucher aux Poids du Modèle

Les agents IA actuels utilisent soit des compétences artisanales (lentes à itérer), des prompts générés en un seul passage (peu fiables), ou de l'auto-révision faiblement contrôlée (aucune garantie de qualité). Aucune de ces approches ne se comporte comme un véritable optimiseur — et aucune n'améliore de façon fiable son point de départ avec du feedback.

Microsoft SkillOpt change tout cela. Il traite le document de compétence lui-même — un simple fichier Markdown — comme l'état entraînable d'un agent gelé, et l'optimise avec la même discipline qui rend l'apprentissage profond reproductible. Passages avant, rétropropagation, clipping de gradient, portes de validation, planificateurs de taux d'apprentissage — SkillOpt les applique tous à l'édition de compétences en langage naturel.

Avec plus de 7 400 étoiles GitHub en un peu plus d'un mois, SkillOpt est déjà intégré par gbrain, gbrain-evals et darwin-skill. Sur 52 cellules (modèle, benchmark, moteur d'exécution) évaluées, il est meilleur ou ex-aequo sur toutes — augmentant la précision moyenne de GPT-5.5 sans compétence de +23,5 points en chat direct, +24,8 dans la boucle agentique Codex, et +19,1 dans Claude Code.

C'est open-source sous licence MIT, Python 3.10+, et s'installe via pip. L'artefact déployé est un best_skill.md compact (300–2 000 tokens) qui n'ajoute aucun surcoût à l'inférence.

Pourquoi cet outil est tendance

Quatre forces propulsent la croissance explosive de SkillOpt :

  1. Le goulot d'étranglement des compétences d'agent est réel. Tous ceux qui construisent des agents IA (Claude Code, Codex, Copilot, OpenHands) ont besoin de prompts de compétence de haute qualité. La création artisanale est lente ; la génération en un seul passage est incohérente. La boucle d'optimisation de SkillOpt est la première solution systématique.

  2. Aucun surcoût à l'inférence. Contrairement au RAG, au fine-tuning ou aux pipelines d'appels d'outils, la compétence optimisée de SkillOpt est un fichier texte brut. Au déploiement, elle ne coûte rien — pas d'appels de modèle supplémentaires, pas de latence, pas d'infrastructure.

  3. Les benchmarks ne mentent pas. 52/52 meilleur ou ex-aequo sur 6 benchmarks, 7 modèles cibles et 3 moteurs d'exécution. L'article montre que SkillOpt améliore les performances sur chaque configuration testée, avec des gains qui se transfèrent entre les échelles de modèles et entre Codex et Claude Code.

  4. Le compagnon SkillOpt-Sleep (aperçu juin 2026) apporte la même discipline à vos sessions de codage quotidiennes — un « cycle de sommeil » nocturne qui exploite vos propres transcriptions Claude Code / Codex, rejoue les tâches récurrentes et consolide les compétences validées hors ligne.

Architecture

Architecture SkillOpt

La boucle d'entraînement reflète l'apprentissage profond à chaque étape :

  • Document de Compétence (l'état entraînable) : Un fichier Markdown (300–2 000 tokens) qui sert de prompt système à l'agent. C'est la seule chose qui change pendant l'entraînement — les poids du LLM sous-jacent restent gelés.

  • Modèle Cible Gelé : Le LLM qui exécute les tâches en utilisant la compétence actuelle. SkillOpt supporte OpenAI, Azure OpenAI, Claude, Qwen (vLLM local) et MiniMax — tous comme backends interchangeables.

  • Modèle Optimiseur : Un modèle séparé, généralement plus capable (GPT-5.5 par défaut), qui analyse les trajectoires échouées et produit des modifications bornées (ajout/suppression/remplacement) sur le document de compétence. Il n'exécute jamais de tâches — il ne fait qu'améliorer la compétence.

La Boucle d'Entraînement

Phase Analogie Deep Learning Ce qui se passe
1. Passage avant Forward pass Le modèle cible exécute des tâches avec la compétence actuelle → trajectoires + scores
2. Réflexion Backward pass L'optimiseur analyse les échecs → génère des correctifs
3. Agrégation Accumulation de gradient Les correctifs sémantiquement similaires sont fusionnés
4. Sélection Clipping de gradient Top-K correctifs sélectionnés par le paramètre learning_rate ; planificateur cosine/linéaire
5. Mise à jour Mise à jour des paramètres Modifications ajout/suppression/remplacement appliquées au document
6. Validation Validation Compétence mise à jour testée sur un sous-ensemble de sélection ; acceptée seulement si le score s'améliore

Mécanismes de frontière d'époque pour éviter l'oubli catastrophique :

  • Mise à jour lente (Momentum) : En fin d'époque, les compétences précédente et actuelle sont déployées sur les mêmes échantillons. Les éléments sont catégorisés (amélioré/régressé/échec persistant/succès stable) et des conseils de haut niveau sont injectés dans le document.

  • Méta-compétence (Mémoire d'optimiseur) : Notes stratégiques inter-époques accumulées pendant tout l'entraînement, fournies comme contexte lors des futures étapes de réflexion.

Prérequis

  • Python 3.10 ou ultérieur
  • Une clé API pour au moins un backend supporté (Azure OpenAI, OpenAI, Anthropic Claude, ou Qwen local via vLLM)
  • Au moins 4 Go de RAM (16 Go recommandé pour les benchmarks ALFWorld)

Installation

Clonez le dépôt et installez :

git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt
pip install -e .

Extensions optionnelles :

# Support Claude
pip install -e ".[claude]"

# Inférence Qwen locale
pip install -e ".[qwen]"

# Tableau de bord WebUI
pip install -e ".[webui]"

# Benchmark ALFWorld
pip install -e ".[alfworld]"

Configurez vos identifiants API :

cp .env.example .env
# Modifiez .env avec vos clés API

Configuration

SkillOpt utilise des configurations YAML qui héritent d'une base commune. Voici la configuration clé pour une expérience SearchQA (configs/searchqa/default.yaml) :

model:
  backend: azure_openai
  optimizer: gpt-5.5
  target: gpt-5.5

train:
  num_epochs: 4
  batch_size: 40

optimizer:
  learning_rate: 4          # max de modifications par étape
  lr_scheduler: cosine      # planificateur de taux d'apprentissage
  use_slow_update: true     # momentum de frontière d'époque
  use_meta_skill: true      # mémoire d'optimiseur inter-époques

evaluation:
  use_gate: true            # accepter seulement si le score s'améliore

Exécution de votre première expérience

SkillOpt est livré avec 6 benchmarks intégrés. Exécutons le plus rapide — SearchQA :

python scripts/train.py --config configs/searchqa/default.yaml

Vous verrez une sortie comme celle-ci :

[Step 1/8] Rollout: 20 items, 4 workers...
[Step 1/8] Score: 0.65 → Reflect...
[Step 1/8] 6 edit patches generated
[Step 1/8] Selected 4 edits (lr=8, cosine → 7.7)
[Step 1/8] Gate: val score 0.68 > 0.65 ✓ ACCEPT
[Step 2/8] ...

Les sorties d'entraînement sont sauvegardées dans outputs/<benchmark>/<run_id>/ :

outputs/searchqa/2026-06-01_10-30-00/
├── steps/
│   ├── step_0001/
│   ├── step_0002/
│   └── ...
├── slow_update/
│   └── epoch_02/
├── meta_skill/
│   └── epoch_02/
├── skills/
│   └── step_0001.md
├── best_skill.md
└── history.json

Après l'entraînement, évaluez la meilleure compétence sur le sous-ensemble de test :

python scripts/eval_only.py \
--config configs/searchqa/default.yaml \
--skill outputs/searchqa/<run_id>/skills/best_skill.md

Tableau de bord WebUI

Vous préférez une interface visuelle ? Lancez le tableau de bord :

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

Puis ouvrez http://localhost:7860 dans votre navigateur.

Ajout d'un nouveau benchmark

Étendre SkillOpt à votre propre tâche est simple (~200 lignes) :

  1. Chargeur de données — implémentez une sous-classe SplitDataLoader qui charge les éléments train/val/test
  2. Assistant de passage avant — exécute le modèle cible sur les éléments et score les prédictions
  3. EnvAdapter — connecte le chargeur + passage avant dans le cycle de vie de SkillOpt
  4. Configuration YAML — référence votre nom d'environnement et paramètres d'entraînement

Le répertoire skillopt/envs/_template/ fournit un point de départ complet.

Ajout d'un nouveau backend de modèle

Le système de backends enfichables de SkillOpt vous permet d'ajouter n'importe quel fournisseur de LLM :

  1. Créez skillopt/model/votre_backend.py étendant ModelBackend
  2. Implémentez _init_client() et async generate()
  3. Enregistrez dans skillopt/model/common.py + backend_config.py

Consultez skillopt/model/qwen.py ou skillopt/model/minimax.py comme modèles.

SkillOpt-Sleep : Auto-évolution Nocturne

L'aperçu de juin 2026 de SkillOpt-Sleep apporte la même discipline d'optimisation à votre flux de travail quotidien :

  • Exploite les transcriptions des sessions Claude Code, Codex ou Copilot
  • Identifie les tâches récurrentes et les rejoue hors ligne
  • Consolide les améliorations de compétence validées derrière une porte de validation
  • Propositions préparées pour votre révision chaque matin

Installation pour votre agent :

Plateforme Installation
Claude Code /plugin marketplace add ./plugins/claude-code → /skillopt-sleep
Codex bash plugins/codex/install.sh → compétence skillopt-sleep
Copilot Enregistrez plugins/copilot/mcp_server.py comme serveur MCP

Les résultats sur le benchmark SearchQA montrent des gains de +3,1 à +4,5 points de pourcentage du simple rejeu d'expérience, avec des améliorations croissantes à mesure que plus de passé pertinent est rappelé.

Liste de vérification

  • python -c "import skillopt; print('Prêt!')" réussit
  • Les journaux d'entraînement montrent des améliorations de score à travers les étapes et époques
  • best_skill.md est créé dans le répertoire de sortie
  • La compétence optimisée améliore les scores de test vs. la compétence initiale
  • Évaluez sur au moins 2 modèles cibles différents pour vérifier le transfert

Ressources