version unknown

skillopt-sleep

microsoft@microsoft⭐ 19.1k stars· last commit 5d ago· 40 open issues

Use when the user wants their Claude agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, memory/skill consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated CLAUDE.md/SKILL.md behind a held-out gate.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.2/10
Verified
Oct 11, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 19.1k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.2/10
📍

Not yet listed on ClawHub or SkillsMP

// README

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

📖 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 🔥🔥🔥

  • [2026-11] 🎤 SkillOpt is accepted to NeurIPS 2026 as a Spotlight! See you in Sydney!
  • [2026-11] 🏆 SkillOpt won 1st Place in the Executive Challenge at the Microsoft Global Hackathon 2026 (badge, issued by The Microsoft Garage).
  • [2026-07-24] 📰 SkillOpt in the news. Read the official Microsoft Research feature, along with recent coverage from VentureBeat, Synced (机器之心), Flowtivity, and The Decoder.
  • [2026-07-02] 🚀 SkillOpt v0.2.0 is out on PyPI! Headline feature: SkillOpt-Sleep, a nightly offline self-evolution engine (harvest → mine → replay → consolidate behind a held-out validation gate), now shipped as the skillopt-sleep CLI. It also includes experimental multi-objective, replay, and dream-rollout controls; the main CLI keeps conservative defaults and does not expose every experiment-harness control as a flag. The release source adds integration shells for Claude Code, Codex, Copilot, and Devin, plus an OpenClaw reference adaptation; these plugin/MCP files live in the repository rather than the PyPI wheel. It also adds SearchQA split materialization, Windows robustness, and hardened JSON parsing. See the release notes for full release details and contributor acknowledgements.
  • [2026-06-15] 😴 SkillOpt-Sleep (preview) — a nightly offline self-evolution companion for local coding agents (Claude Code / Codex / Copilot): review past sessions, replay recurring tasks, and consolidate validated skills behind a held-out gate. See docs/sleep/README.md for what it is, how to use it, and results.
  • [2026-06-03] 🎉 gbrain, gbrain-evals, and darwin-skill have all integrated SkillOpt.
  • [2026-06-02] 🎉 SkillOpt v0.1.0 is now available on PyPI! Install with pip install skillopt. This initial release includes the full training loop (rollout → reflect → aggregate → select → update → evaluate), multi-backend support (OpenAI / Azure / Claude / Qwen / MiniMax), six built-in benchmarks, and WebUI dashboard.

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


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

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • plugins/claude-code/skills/skillopt-sleep/SKILL.md7.9 KBupstream ↗
    ---
    name: skillopt-sleep
    description: "Use when the user wants their Claude agent to self-improve from past usage, asks about a nightly/offline 'sleep' or 'dream' cycle, memory/skill consolidation, or says things like 'make my agent better the more I use it', 'review my past sessions', 'learn my preferences', 'consolidate what you learned', 'run the sleep cycle', or wants to schedule background self-optimization. Drives the skillopt_sleep engine: harvest past sessions -> mine recurring tasks -> replay through a selected backend -> consolidate validated CLAUDE.md/SKILL.md behind a held-out gate."
    ---
    
    # SkillOpt-Sleep: usage-driven self-evolution for a local Claude agent
    
    SkillOpt-Sleep gives the user's agent a **sleep cycle**. On demand or on a
    nightly schedule, it reviews real past Claude Code sessions, re-runs recurring
    tasks through the selected backend, and consolidates what it
    learns into **memory** (`CLAUDE.md`) and **skills** (`SKILL.md`). With the
    default validation gate enabled, it keeps only changes that improve a held-out
    score. Live files change only through explicit adoption or a user-requested
    `--auto-adopt`. It aims to improve this user's recurring work, while making
    each accepted proposal measurable on the run's held-out tasks,
    with no model-weight training. It is the deployment-time analogue of training:
    short-term experience → long-term competence.
    
    It synthesizes three ideas:
    - **SkillOpt** — the skill/memory doc is trainable text; bounded add/delete/replace
      edits; accepted only through a held-out gate; rejected edits are recorded in
      the run report for review.
    - **Claude Dreams** — consolidation that reads past sessions and proposes changes
      inside protected learned blocks; the input is never mutated, and output is
      reviewed before adoption.
    - **Agent sleep** — periodic background replay turns episodes into durable skill.
    
    ## When to use this skill
    
    Trigger when the user wants any of:
    - "make my agent learn from how I use it" / "get better the more I use it" / "remember my preferences across sessions"
    - a nightly/scheduled or on-demand **offline self-improvement / dream / sleep** run
    - to **review past sessions/trajectories** and distill recurring tasks
    - to **consolidate** feedback into `CLAUDE.md` or a managed skill
    - to **schedule** the cycle (cron) or **adopt** a staged proposal
    
    ## The cycle (six stages)
    
    1. **Harvest** — read `~/.claude/projects/*/<session>.jsonl` + `~/.claude/history.jsonl` (READ-ONLY) → session digests.
    2. **Mine** — digests → `TaskRecord`s (recurring intents + outcome labels + checkable refs where possible).
    3. **Replay** — re-run tasks through the selected backend under the *current*
       skill+memory → (hard, soft) scores.
    4. **Consolidate** — reflect on failures → propose bounded edits → **gate** on a held-out slice; with the default gate enabled, accept only if it strictly improves.
    5. **Stage** — write the accepted `proposed_CLAUDE.md` and/or
       `proposed_SKILL.md`, plus `report.md`, `report.json`, `manifest.json`, and
       `diagnostics.json` into `<project>/.skillopt-sleep/staging/<timestamp>/`.
       **Nothing live changes.** A rejected run still has a report but no proposed
       live-file replacement.
    6. **Adopt** — explicit (or opt-in auto): copy staged files over live ones, backing up first.
    
    ## How to drive it
    
    Prefer the `/skillopt-sleep` command. Under the hood it calls the bundled runner:
    
    ```bash
    "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" status                       # what's happened
    "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" dry-run --project "$(pwd)"    # no-staging preview
    "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" run --project "$(pwd)"        # full cycle, stages a proposal
    "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" adopt --project "$(pwd)"      # apply staged proposal (with backup)
    ```
    
    - Default backend is `mock` (deterministic, **no API spend**) — good for trying the plumbing.
    - Add `--backend claude` or `--backend codex` to spend the user's real budget
      for model-driven optimization. A held-out gain is run-specific evidence, not
      a guarantee of broader improvement; results depend on the tasks, model, and
      checks.
    - Scope defaults to the invoked project; `--scope all` harvests every Claude
      project into the current run's configured targets.
    - A real backend sends truncated transcript/task content to its provider. See
      the data-boundary rules below before using one with sensitive sessions.
    
    ### Scheduling
    
    ```bash
    "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" schedule --project "$(pwd)" --hour 3 --minute 17
    "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" unschedule --project "$(pwd)"
    ```
    
    Installs a nightly cron entry. `unschedule --all` removes every managed entry.
    
    ## Common CLI flags
    
    | Flag | Default | Description |
    |------|---------|-------------|
    | `--project PATH` | cwd | Project directory to evolve |
    | `--scope all\|invoked` | invoked | Harvest scope |
    | `--backend mock\|claude\|codex\|copilot\|handoff\|azure_openai` | mock | Backend (mock = no provider calls) |
    | `--model NAME` | backend default | Override the model used for replay |
    | `--source claude\|codex\|auto` | claude | Transcript source |
    | `--lookback-hours N` | 72 | Harvest window |
    | `--max-sessions N` | derived | Cap harvested sessions; defaults to 3 × max tasks (120 with current defaults) |
    | `--max-tasks N` | 40 | Cap mined tasks |
    | `--target-skill-path PATH` | `~/.claude/skills/skillopt-sleep-learned/SKILL.md` | Explicit SKILL.md to evolve |
    | `--tasks-file PATH` | — | Reviewed TaskRecord JSON (skip harvest) |
    | `--progress` | off | Print phase progress to stderr |
    | `--auto-adopt` | off | Auto-adopt if gate passes |
    | `--edit-budget N` | 4 | Max bounded edits per night |
    | `--preferences TEXT` | empty | Add house rules to the optimizer's reflection prior |
    | `--json` | off | Machine-readable JSON output |
    
    The CLI also has source/runtime path overrides (`--claude-home`, `--codex-home`,
    and `--codex-path`) and action-specific flags. Use
    `python -m skillopt_sleep <action> --help` as the authoritative surface.
    
    ## Config keys (`~/.skillopt-sleep/config.json`)
    
    Beyond the CLI flags, advanced behavior is controlled via config:
    
    - **`preferences`** — free-text house rules injected into the optimizer's reflect step (e.g. "Always use async/await", "Answers in `\boxed{}`").
    - **`gate_mode`** — `on` (default, validation-gated) or `off` (greedy, accept all edits).
    - **`gate_metric`** — `hard`, `soft`, or `mixed` (default). Controls how the held-out gate scores.
    - **`gate_no_regression`** — `false` by default. Set to `true` to reject a candidate when any validation task's configured gate score decreases.
    - **`dream_rollouts`** — >1 enables multi-rollout contrastive reflection per task.
    - **`recall_k`** — >0 recalls K similar past tasks into the dream (long-term memory).
    - **`evolve_memory`** / **`evolve_skill`** — independently toggle CLAUDE.md vs SKILL.md consolidation.
    
    ## Memory consolidation
    
    The sleep cycle can consolidate both:
    - **SKILL.md** — the managed skill file (bounded edits: add/delete/replace)
    - **CLAUDE.md** — the project memory (same bounded edits)
    
    With the default gate enabled, both are evaluated by the same held-out score.
    Set `evolve_memory: false` to consolidate only skills, or `evolve_skill: false`
    for only memory.
    
    ## Hard rules
    
    - **Never** hand-edit the user's `CLAUDE.md` / `SKILL.md` as part of this skill.
      Let the engine's explicit `adopt` or user-requested `--auto-adopt` path apply
      the staging manifest and back up existing live files first.
    - Harvest is read-only. `mock` replay has no side effects.
    - Real backends send truncated transcript excerpts and derived tasks to the
      selected provider for mining, replay, judging, and reflection. The Claude
      transcript path is not guaranteed to remove every secret before those calls.
      Review provider policy and session contents first. For sensitive data, use
      `mock` or run `harvest --output <file>`, inspect/redact the JSON, set
      `"reviewed": true`, and replay 
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/microsoft-skillopt-plugins-claude-code-skills-skillopt-sleep.md

// REPO STATS

19.1k stars
40 open issues
Last commit: 5d ago