microsoft/skillopt

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.