# microsoft/skillopt architecture

> Architecture diagram of the GitHub repository microsoft/skillopt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/skillopt
- Repository: https://github.com/microsoft/skillopt

## Overview

1. **Repository shape:** This is a Python package centered on **SkillOpt**, a system for optimizing a text “skill document” instead of model weights. The codebase is split into a reusable core library (`skillopt/`), a nightly offline companion for coding agents (`skillopt_sleep/`), integration plugins (`plugins/`), benchmark assets (`data/`, `configs/`, `ckpt/`), and a small WebUI package (`skillopt_webui/`).

2. **Primary training pipeline:** The main architecture is a closed loop: **dataset → environment rollout → scoring/evaluation → reflection/aggregation → skill update → held-out validation gate → checkpoint export**. That loop is implemented across `skillopt/engine`, `skillopt/envs`, `skillopt/evaluation`, `skillopt/gradient`, `skillopt/optimizer`, and `skillopt/scheduler`.

3. **Benchmark/environment boundary:** Each benchmark lives in `skillopt/envs/<benchmark>/` and acts like an adapter layer around a specific task family. These packages contain the benchmark-specific `dataloader`, `rollout`, `adapter`, `evaluator`, prompt templates, and an `initial.md` seed skill. The built-in benchmarks include **alfworld, docvqa, livemathematicianbench, officeqa, searchqa, and spreadsheetbench**.

4. **Model/backend abstraction:** `skillopt/model/` isolates all LLM or execution backends behind a common interface. The repo supports multiple external targets, including **OpenAI/Azure OpenAI, Claude, Qwen, MiniMax, and Codex-style execution harnesses**. This is an important architectural boundary: the optimizer does not depend on one model provider, only on the backend contract.

5. **Skill state and updates:** The “trainable parameter” is a markdown skill file, not neural weights. The optimizer subsystem (`skillopt/optimizer/`) produces bounded textual edits such as add/delete/replace, applies update policies, and supports variants like **skill-aware updates, slow updates, meta-skill, clipping, scheduling, and autonomous learning-rate logic**. The resulting artifact is typically a `best_skill.md` checkpoint.

6. **Validation and safety gates:** `skillopt/evaluation/gate.py` and related scoring utilities enforce the key control point in the system: an edited skill is only accepted if it improves validation performance. This separates **candidate generation** from **promotion to the canonical skill checkpoint**, which is what makes the process reproducible and stable.

7. **Configuration and experiment control:** `configs/` defines benchmark-specific and feature-specific YAML configuration, with a shared base in `configs/_base_/`. `scripts/train.py` and `scripts/eval_only.py` are the top-level entry points for running training and evaluation, while `scripts/run_*.sh` provide benchmark-specific launch wrappers. The `data/` directory holds predefined train/val/test splits via `items.json` manifests, and `ckpt/` stores benchmark-specific skill checkpoints and notes.

8. **Prompted reasoning and reflection:** The repo is heavily prompt-driven. Shared prompt templates live in `skillopt/prompts/`, while each environment has its own rollout, analyst, and success/error prompts. This makes prompt selection part of the architecture: rollout generation, failure analysis, and skill rewriting are all explicit stages rather than ad hoc strings in application code.

9. **SkillOpt-Sleep subsystem:** `skillopt_sleep/` is a separate offline self-evolution pipeline for local coding agents. It adds its own cycle around **state tracking, memory, harvesting session traces, replaying tasks, judging outcomes, mining reusable skills, consolidating them, and applying a gate before promotion**. It is conceptually similar to SkillOpt, but optimized for agent-session artifacts rather than benchmark rollouts.

10. **Agent-tool integrations:** The `plugins/` directory contains external integration packages for **Claude Code, Codex, Copilot, and OpenClaw**. These are not the core optimizer, but they are important deployment boundaries: they connect SkillOpt-Sleep to real agent runtimes, session hooks, cron-based sleep jobs, and plugin-specific skill packaging.

11. **WebUI and observability:** `skillopt_webui/` provides an optional dashboard for monitoring experiments. It is separate from the training engine, so the core optimization loop can run headless while the UI only observes or summarizes progress.

12. **Extensibility model:** The repository is designed around two extension points: add a **new benchmark** by creating a new `skillopt/envs/<name>/` package, or add a **new backend** by implementing a new `skillopt/model/*_backend.py` and registering it in the model router/config. That separation is central to how the architecture scales across tasks and model providers.

13. **Tests and contract checks:** The `tests/` folder validates core utilities, scoring, backend behavior, type contracts, and parts of the sleep engine. Architecturally, this reinforces that the stable interfaces are the JSON/text utilities, backend adapters, skill-aware reflection, and the sleep-cycle logic.

Main entry points: [`skillopt/engine/trainer.py`](https://github.com/microsoft/skillopt/blob/main/skillopt/engine/trainer.py) (Trainer), [`skillopt/envs/base.py`](https://github.com/microsoft/skillopt/blob/main/skillopt/envs/base.py) (Env Base), [`skillopt_sleep/cycle.py`](https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/cycle.py) (Sleep Cycle), [`skillopt/model/router.py`](https://github.com/microsoft/skillopt/blob/main/skillopt/model/router.py) (Model Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["SkillOpt Core"]
  node_core_engine["Trainer<br/>orchestrator<br/>[trainer.py]"]
  node_core_envs["Env Base<br/>adapter base<br/>[base.py]"]
  node_core_model["Model Router<br/>backend router<br/>[router.py]"]
  node_core_gateway(("Validation Gate<br/>promotion gate<br/>[gate.py]"))
  node_core_gradient["Reflection<br/>analysis<br/>[aggregate.py]"]
  node_core_optimizer["Skill Update<br/>text optimizer<br/>[rewrite.py]"]
  node_core_scheduler["Update Policy<br/>scheduler<br/>[__init__.py]"]
end

subgraph group_benchmarks["Benchmarks"]
  node_bench_alfworld["Alfworld<br/>benchmark env"]
  node_bench_docvqa["DocVQA<br/>benchmark env"]
  node_bench_math["Live Math<br/>benchmark env"]
  node_bench_officeqa["OfficeQA<br/>benchmark env"]
  node_bench_searchqa["SearchQA<br/>benchmark env"]
  node_bench_sheet["Spreadsheet<br/>benchmark env"]
end

subgraph group_sleep["SkillOpt Sleep"]
  node_sleep_cycle["Sleep Cycle<br/>offline pipeline<br/>[cycle.py]"]
  node_sleep_memory[("Memory<br/>state store<br/>[memory.py]")]
  node_sleep_harvest["Harvest<br/>trace ingestion<br/>[harvest.py]"]
  node_sleep_mine["Mine Skills<br/>skill mining<br/>[mine.py]"]
  node_sleep_gate(("Sleep Gate<br/>promotion gate<br/>[gate.py]"))
end

subgraph group_deploy["Integrations"]
  node_plugin_claude["Claude Code<br/>plugin"]
  node_plugin_codex["Codex<br/>plugin"]
  node_plugin_copilot["Copilot<br/>plugin"]
  node_plugin_openclaw["OpenClaw<br/>plugin"]
  node_webui["WebUI<br/>dashboard<br/>[app.py]"]
end

node_scripts_train["Train<br/>entrypoint<br/>[train.py]"]
node_scripts_eval["Eval Only<br/>entrypoint<br/>[eval_only.py]"]

node_scripts_train -->|"launches"| node_core_engine
node_scripts_eval -->|"runs"| node_core_engine
node_core_engine -->|"loads tasks"| node_core_envs
node_core_engine -->|"queries"| node_core_model
node_core_engine -->|"analyzes"| node_core_gradient
node_core_gradient -->|"guides"| node_core_optimizer
node_core_optimizer -->|"updates"| node_core_scheduler
node_core_scheduler -->|"submits"| node_core_gateway
node_core_gateway -->|"accepts/rejects"| node_core_engine
node_core_envs -->|"implements"| node_bench_alfworld
node_core_envs -->|"implements"| node_bench_docvqa
node_core_envs -->|"implements"| node_bench_math
node_core_envs -->|"implements"| node_bench_officeqa
node_core_envs -->|"implements"| node_bench_searchqa
node_core_envs -->|"implements"| node_bench_sheet
node_sleep_cycle -->|"collects"| node_sleep_harvest
node_sleep_harvest -->|"stores"| node_sleep_memory
node_sleep_memory -->|"feeds"| node_sleep_mine
node_sleep_mine -->|"proposes"| node_sleep_gate
node_sleep_gate -->|"promotes"| node_sleep_cycle
node_plugin_claude -->|"hooks into"| node_sleep_cycle
node_plugin_codex -->|"packages"| node_sleep_cycle
node_plugin_copilot -->|"connects"| node_sleep_cycle
node_plugin_openclaw -->|"runs"| node_sleep_cycle
node_webui -->|"observes"| node_core_engine
node_core_model -->|"serves backends"| node_core_engine

click node_scripts_train "https://github.com/microsoft/skillopt/blob/main/scripts/train.py"
click node_scripts_eval "https://github.com/microsoft/skillopt/blob/main/scripts/eval_only.py"
click node_core_engine "https://github.com/microsoft/skillopt/blob/main/skillopt/engine/trainer.py"
click node_core_envs "https://github.com/microsoft/skillopt/blob/main/skillopt/envs/base.py"
click node_core_model "https://github.com/microsoft/skillopt/blob/main/skillopt/model/router.py"
click node_core_gateway "https://github.com/microsoft/skillopt/blob/main/skillopt/evaluation/gate.py"
click node_core_gradient "https://github.com/microsoft/skillopt/blob/main/skillopt/gradient/aggregate.py"
click node_core_optimizer "https://github.com/microsoft/skillopt/blob/main/skillopt/optimizer/rewrite.py"
click node_core_scheduler "https://github.com/microsoft/skillopt/blob/main/skillopt/scheduler/__init__.py"
click node_bench_alfworld "https://github.com/microsoft/skillopt/tree/main/skillopt/envs/alfworld"
click node_bench_docvqa "https://github.com/microsoft/skillopt/tree/main/skillopt/envs/docvqa"
click node_bench_math "https://github.com/microsoft/skillopt/tree/main/skillopt/envs/livemathematicianbench"
click node_bench_officeqa "https://github.com/microsoft/skillopt/tree/main/skillopt/envs/officeqa"
click node_bench_searchqa "https://github.com/microsoft/skillopt/tree/main/skillopt/envs/searchqa"
click node_bench_sheet "https://github.com/microsoft/skillopt/tree/main/skillopt/envs/spreadsheetbench"
click node_sleep_cycle "https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/cycle.py"
click node_sleep_memory "https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/memory.py"
click node_sleep_harvest "https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/harvest.py"
click node_sleep_mine "https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/mine.py"
click node_sleep_gate "https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/gate.py"
click node_plugin_claude "https://github.com/microsoft/skillopt/tree/main/plugins/claude-code"
click node_plugin_codex "https://github.com/microsoft/skillopt/tree/main/plugins/codex"
click node_plugin_copilot "https://github.com/microsoft/skillopt/tree/main/plugins/copilot"
click node_plugin_openclaw "https://github.com/microsoft/skillopt/tree/main/plugins/openclaw"
click node_webui "https://github.com/microsoft/skillopt/blob/main/skillopt_webui/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_engine,node_core_envs,node_core_model,node_core_gateway,node_core_gradient,node_core_optimizer,node_core_scheduler toneBlue
class node_bench_alfworld,node_bench_docvqa,node_bench_math,node_bench_officeqa,node_bench_searchqa,node_bench_sheet toneAmber
class node_sleep_cycle,node_sleep_memory,node_sleep_harvest,node_sleep_mine,node_sleep_gate toneMint
class node_plugin_claude,node_plugin_codex,node_plugin_copilot,node_plugin_openclaw,node_webui toneRose
class node_scripts_train,node_scripts_eval toneNeutral
```

## Components

### SkillOpt Core

Main optimization library for benchmark-driven skill editing

- [Trainer](https://github.com/microsoft/skillopt/blob/main/skillopt/engine/trainer.py): orchestrator · Coordinates the closed optimization loop · `skillopt/engine/trainer.py`
- [Env Base](https://github.com/microsoft/skillopt/blob/main/skillopt/envs/base.py): adapter base · Shared benchmark environment contract · `skillopt/envs/base.py`
- [Model Router](https://github.com/microsoft/skillopt/blob/main/skillopt/model/router.py): backend router · Abstracts LLM and execution backends · `skillopt/model/router.py`
- [Validation Gate](https://github.com/microsoft/skillopt/blob/main/skillopt/evaluation/gate.py): promotion gate · Accepts or rejects candidate skill updates · `skillopt/evaluation/gate.py`
- [Reflection](https://github.com/microsoft/skillopt/blob/main/skillopt/gradient/aggregate.py): analysis · Aggregates rollout signal into update guidance · `skillopt/gradient/aggregate.py`
- [Skill Update](https://github.com/microsoft/skillopt/blob/main/skillopt/optimizer/rewrite.py): text optimizer · Produces bounded edits to the skill document · `skillopt/optimizer/rewrite.py`
- [Update Policy](https://github.com/microsoft/skillopt/blob/main/skillopt/scheduler/__init__.py): scheduler · Controls timing and selection of updates · `skillopt/scheduler/__init__.py`

### Benchmarks

Task-specific environment adapters and prompt bundles

- [Alfworld](https://github.com/microsoft/skillopt/tree/main/skillopt/envs/alfworld): benchmark env · Task adapter for ALFWorld · `skillopt/envs/alfworld`
- [DocVQA](https://github.com/microsoft/skillopt/tree/main/skillopt/envs/docvqa): benchmark env · Task adapter for document QA · `skillopt/envs/docvqa`
- [Live Math](https://github.com/microsoft/skillopt/tree/main/skillopt/envs/livemathematicianbench): benchmark env · Task adapter for live mathematics · `skillopt/envs/livemathematicianbench`
- [OfficeQA](https://github.com/microsoft/skillopt/tree/main/skillopt/envs/officeqa): benchmark env · Task adapter for office tasks · `skillopt/envs/officeqa`
- [SearchQA](https://github.com/microsoft/skillopt/tree/main/skillopt/envs/searchqa): benchmark env · Task adapter for search-based QA · `skillopt/envs/searchqa`
- [Spreadsheet](https://github.com/microsoft/skillopt/tree/main/skillopt/envs/spreadsheetbench): benchmark env · Task adapter for spreadsheet reasoning · `skillopt/envs/spreadsheetbench`

### SkillOpt Sleep

Offline self-evolution pipeline for agent-session artifacts

- [Sleep Cycle](https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/cycle.py): offline pipeline · Runs the SkillOpt-Sleep self-evolution loop · `skillopt_sleep/cycle.py`
- [Memory](https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/memory.py): state store · Tracks reusable agent memories and state · `skillopt_sleep/memory.py`
- [Harvest](https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/harvest.py): trace ingestion · Collects session traces and artifacts · `skillopt_sleep/harvest.py`
- [Mine Skills](https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/mine.py): skill mining · Extracts candidate reusable skills · `skillopt_sleep/mine.py`
- [Sleep Gate](https://github.com/microsoft/skillopt/blob/main/skillopt_sleep/gate.py): promotion gate · Promotes mined skills after evaluation · `skillopt_sleep/gate.py`

### Integrations

External plugin and UI deployment surfaces

- [Claude Code](https://github.com/microsoft/skillopt/tree/main/plugins/claude-code): plugin · Agent integration for Claude Code · `plugins/claude-code`
- [Codex](https://github.com/microsoft/skillopt/tree/main/plugins/codex): plugin · Agent integration for Codex runtimes · `plugins/codex`
- [Copilot](https://github.com/microsoft/skillopt/tree/main/plugins/copilot): plugin · Copilot instructions and MCP integration · `plugins/copilot`
- [OpenClaw](https://github.com/microsoft/skillopt/tree/main/plugins/openclaw): plugin · Sleep runner and task hooks for OpenClaw · `plugins/openclaw`
- [WebUI](https://github.com/microsoft/skillopt/blob/main/skillopt_webui/app.py): dashboard · Optional experiment monitoring UI · `skillopt_webui/app.py`

### Other components

- [Train](https://github.com/microsoft/skillopt/blob/main/scripts/train.py): entrypoint · Main training launcher · `scripts/train.py`
- [Eval Only](https://github.com/microsoft/skillopt/blob/main/scripts/eval_only.py): entrypoint · Evaluation-only launcher · `scripts/eval_only.py`

## Connections

- Train → Trainer: launches · Training entrypoint starts the main orchestrator
- Eval Only → Trainer: runs · Evaluation entrypoint reuses the core runner
- Trainer → Env Base: loads tasks · Trainer instantiates benchmark environments
- Trainer → Model Router: queries · Rollouts and analyses call through backend abstraction
- Trainer → Reflection: analyzes · Aggregates rollout outcomes into reflection signal
- Reflection → Skill Update: guides · Reflection informs skill rewrite proposals
- Skill Update → Update Policy: updates · Scheduler controls when candidate edits are applied
- Update Policy → Validation Gate: submits · Promoted candidates are checked by validation gate
- Validation Gate → Trainer: accepts/rejects · Gate determines whether checkpoint advances
- Env Base → Alfworld: implements · Concrete benchmark adapter
- Env Base → DocVQA: implements · Concrete benchmark adapter
- Env Base → Live Math: implements · Concrete benchmark adapter
- Env Base → OfficeQA: implements · Concrete benchmark adapter
- Env Base → SearchQA: implements · Concrete benchmark adapter
- Env Base → Spreadsheet: implements · Concrete benchmark adapter
- Sleep Cycle → Harvest: collects · Offline cycle begins with trace ingestion
- Harvest → Memory: stores · Harvested artifacts are accumulated in memory
- Memory → Mine Skills: feeds · Stored traces become mining input
- Mine Skills → Sleep Gate: proposes · Mined skills are evaluated before promotion
- Sleep Gate → Sleep Cycle: promotes · Accepted skills re-enter the cycle
- Claude Code → Sleep Cycle: hooks into · Plugin provides runtime hooks for sleep jobs
- Codex → Sleep Cycle: packages · Plugin bundles skillopt-sleep integration
- Copilot → Sleep Cycle: connects · Plugin exposes Copilot integration boundary
- OpenClaw → Sleep Cycle: runs · Plugin wraps sleep execution for OpenClaw
- WebUI → Trainer: observes · UI monitors experiment progress and results
- Model Router → Trainer: serves backends · Backend router supplies model and execution targets