SkillOpt-Sleep: usage-driven self-evolution for a local Claude agent
Unverified●26/40Claude Code◐PartialHas SKILL.md but declares no allowed-tools — Claude Code will ask for permission each time
Cursor·UnknownWe have not crawled the repo tree, so we will not guess
Codex·UnknownWe have not crawled the repo tree, so we will not guess
Gemini CLI·UnknownThe spec defines no detection rule for Gemini
Copilot·UnknownWe have not crawled the repo tree, so we will not guess
npx agentalley add skillopt-sleepWho is stuck, and on what
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 pr
The whole source
Frontmatter — 2 properties
| 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. |
| 1 | --- |
| 2 | name: skillopt-sleep |
| 3 | 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."B1 — Line is 577 characters — unreadable by eye |
| 4 | ---A5 — No allowed-tools declared — no way to tell what this skill may touch |
| 5 | |
| 6 | # SkillOpt-Sleep: usage-driven self-evolution for a local Claude agent |
| 7 | |
| 8 | SkillOpt-Sleep gives the user's agent a **sleep cycle**. On demand or on a |
| 9 | nightly schedule, it reviews real past Claude Code sessions, re-runs recurring |
| 10 | tasks through the selected backend, and consolidates what it |
| 11 | learns into **memory** (`CLAUDE.md`) and **skills** (`SKILL.md`). With the |
| 12 | default validation gate enabled, it keeps only changes that improve a held-out |
| 13 | score. Live files change only through explicit adoption or a user-requested |
| 14 | `--auto-adopt`. It aims to improve this user's recurring work, while making |
| 15 | each accepted proposal measurable on the run's held-out tasks, |
| 16 | with no model-weight training. It is the deployment-time analogue of training: |
| 17 | short-term experience → long-term competence. |
| 18 | |
| 19 | It synthesizes three ideas: |
| 20 | - **SkillOpt** — the skill/memory doc is trainable text; bounded add/delete/replace |
| 21 | edits; accepted only through a held-out gate; rejected edits are recorded in |
| 22 | the run report for review. |
| 23 | - **Claude Dreams** — consolidation that reads past sessions and proposes changes |
| 24 | inside protected learned blocks; the input is never mutated, and output is |
| 25 | reviewed before adoption. |
| 26 | - **Agent sleep** — periodic background replay turns episodes into durable skill. |
| 27 | |
| 28 | ## When to use this skill |
| 29 | |
| 30 | Trigger when the user wants any of: |
| 31 | - "make my agent learn from how I use it" / "get better the more I use it" / "remember my preferences across sessions" |
| 32 | - a nightly/scheduled or on-demand **offline self-improvement / dream / sleep** run |
| 33 | - to **review past sessions/trajectories** and distill recurring tasks |
| 34 | - to **consolidate** feedback into `CLAUDE.md` or a managed skill |
| 35 | - to **schedule** the cycle (cron) or **adopt** a staged proposal |
| 36 | |
| 37 | ## The cycle (six stages) |
| 38 | |
| 39 | 1. **Harvest** — read `~/.claude/projects/*/<session>.jsonl` + `~/.claude/history.jsonl` (READ-ONLY) → session digests. |
| 40 | 2. **Mine** — digests → `TaskRecord`s (recurring intents + outcome labels + checkable refs where possible). |
| 41 | 3. **Replay** — re-run tasks through the selected backend under the *current* |
| 42 | skill+memory → (hard, soft) scores. |
| 43 | 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. |
| 44 | 5. **Stage** — write the accepted `proposed_CLAUDE.md` and/or |
| 45 | `proposed_SKILL.md`, plus `report.md`, `report.json`, `manifest.json`, and |
| 46 | `diagnostics.json` into `<project>/.skillopt-sleep/staging/<timestamp>/`. |
| 47 | **Nothing live changes.** A rejected run still has a report but no proposed |
| 48 | live-file replacement. |
| 49 | 6. **Adopt** — explicit (or opt-in auto): copy staged files over live ones, backing up first. |
| 50 | |
| 51 | ## How to drive it |
| 52 | |
| 53 | Prefer the `/skillopt-sleep` command. Under the hood it calls the bundled runner: |
| 54 | |
| 55 | ```bash |
| 56 | "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" status # what's happened |
| 57 | "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" dry-run --project "$(pwd)" # no-staging preview |
| 58 | "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" run --project "$(pwd)" # full cycle, stages a proposal |
| 59 | "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" adopt --project "$(pwd)" # apply staged proposal (with backup) |
| 60 | ``` |
| 61 | |
| 62 | - Default backend is `mock` (deterministic, **no API spend**) — good for trying the plumbing. |
| 63 | - Add `--backend claude` or `--backend codex` to spend the user's real budget |
| 64 | for model-driven optimization. A held-out gain is run-specific evidence, not |
| 65 | a guarantee of broader improvement; results depend on the tasks, model, and |
| 66 | checks. |
| 67 | - Scope defaults to the invoked project; `--scope all` harvests every Claude |
| 68 | project into the current run's configured targets. |
| 69 | - A real backend sends truncated transcript/task content to its provider. See |
| 70 | the data-boundary rules below before using one with sensitive sessions. |
| 71 | |
| 72 | ### Scheduling |
| 73 | |
| 74 | ```bash |
| 75 | "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" schedule --project "$(pwd)" --hour 3 --minute 17 |
| 76 | "${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" unschedule --project "$(pwd)" |
| 77 | ``` |
| 78 | |
| 79 | Installs a nightly cron entry. `unschedule --all` removes every managed entry. |
| 80 | |
| 81 | ## Common CLI flags |
| 82 | |
| 83 | | Flag | Default | Description | |
| 84 | |------|---------|-------------| |
| 85 | | `--project PATH` | cwd | Project directory to evolve | |
| 86 | | `--scope all\|invoked` | invoked | Harvest scope | |
| 87 | | `--backend mock\|claude\|codex\|copilot\|handoff\|azure_openai` | mock | Backend (mock = no provider calls) | |
| 88 | | `--model NAME` | backend default | Override the model used for replay | |
| 89 | | `--source claude\|codex\|auto` | claude | Transcript source | |
| 90 | | `--lookback-hours N` | 72 | Harvest window | |
| 91 | | `--max-sessions N` | derived | Cap harvested sessions; defaults to 3 × max tasks (120 with current defaults) | |
| 92 | | `--max-tasks N` | 40 | Cap mined tasks | |
| 93 | | `--target-skill-path PATH` | `~/.claude/skills/skillopt-sleep-learned/SKILL.md` | Explicit SKILL.md to evolve | |
| 94 | | `--tasks-file PATH` | — | Reviewed TaskRecord JSON (skip harvest) | |
| 95 | | `--progress` | off | Print phase progress to stderr | |
| 96 | | `--auto-adopt` | off | Auto-adopt if gate passes | |
| 97 | | `--edit-budget N` | 4 | Max bounded edits per night | |
| 98 | | `--preferences TEXT` | empty | Add house rules to the optimizer's reflection prior | |
| 99 | | `--json` | off | Machine-readable JSON output | |
| 100 | |
| 101 | The CLI also has source/runtime path overrides (`--claude-home`, `--codex-home`, |
| 102 | and `--codex-path`) and action-specific flags. Use |
| 103 | `python -m skillopt_sleep <action> --help` as the authoritative surface. |
| 104 | |
| 105 | ## Config keys (`~/.skillopt-sleep/config.json`) |
| 106 | |
| 107 | Beyond the CLI flags, advanced behavior is controlled via config: |
| 108 | |
| 109 | - **`preferences`** — free-text house rules injected into the optimizer's reflect step (e.g. "Always use async/await", "Answers in `\boxed{}`"). |
| 110 | - **`gate_mode`** — `on` (default, validation-gated) or `off` (greedy, accept all edits). |
| 111 | - **`gate_metric`** — `hard`, `soft`, or `mixed` (default). Controls how the held-out gate scores. |
| 112 | - **`gate_no_regression`** — `false` by default. Set to `true` to reject a candidate when any validation task's configured gate score decreases. |
| 113 | - **`dream_rollouts`** — >1 enables multi-rollout contrastive reflection per task. |
| 114 | - **`recall_k`** — >0 recalls K similar past tasks into the dream (long-term memory). |
| 115 | - **`evolve_memory`** / **`evolve_skill`** — independently toggle CLAUDE.md vs SKILL.md consolidation. |
| 116 | |
| 117 | ## Memory consolidation |
| 118 | |
| 119 | The sleep cycle can consolidate both: |
| 120 | - **SKILL.md** — the managed skill file (bounded edits: add/delete/replace) |
| 121 | - **CLAUDE.md** — the project memory (same bounded edits) |
| 122 | |
| 123 | With the default gate enabled, both are evaluated by the same held-out score. |
| 124 | Set `evolve_memory: false` to consolidate only skills, or `evolve_skill: false` |
| 125 | for only memory. |
| 126 | |
| 127 | ## Hard rules |
| 128 | |
| 129 | - **Never** hand-edit the user's `CLAUDE.md` / `SKILL.md` as part of this skill. |
| 130 | Let the engine's explicit `adopt` or user-requested `--auto-adopt` path apply |
| 131 | the staging manifest and back up existing live files first. |
| 132 | - Harvest is read-only. `mock` replay has no side effects. |
| 133 | - Real backends send truncated transcript excerpts and derived tasks to the |
| 134 | selected provider for mining, replay, judging, and reflection. The Claude |
| 135 | transcript path is not guaranteed to remove every secret before those calls. |
| 136 | Review provider policy and session contents first. For sensitive data, use |
| 137 | `mock` or run `harvest --output <file>`, inspect/redact the JSON, set |
| 138 | `"reviewed": true`, and replay it with `--tasks-file`; real backends refuse an |
| 139 | unreviewed task file. |
| 140 | - Always show the user the **held-out baseline → candidate** score and the |
| 141 | exact proposed edits before suggesting adoption. Evidence before adoption. |
| 142 | - If asked to demonstrate the mechanism without provider calls, run |
| 143 | `python -m skillopt_sleep.experiments.run_experiment --persona researcher --json` |
| 144 | — a deterministic synthetic demo of held-out lift and gate rejection. It |
| 145 | validates the mechanism, not effectiveness on the user's own tasks. |
| 146 | |
| 147 | ## Validate / demo |
| 148 | |
| 149 | ```bash |
| 150 | # deterministic synthetic demo (no API): score rises and the gate blocks a regression |
| 151 | python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves |
| 152 | python -m skillopt_sleep.experiments.run_experiment --persona programmer --assert-improves |
| 153 | ``` |
| 154 | |
| 155 | See the [SkillOpt-Sleep documentation](https://github.com/microsoft/SkillOpt/tree/main/docs/sleep) |
| 156 | for recorded results, limitations, and the supported integration surface. |
| 157 |
Reviews
Installed this one?Write the first review and take the Trailblazer badge.
Alternatives
Subagent Driven DevelopmentUse when executing implementation plans with independent tasks in the current session◐◐◐◐◐●36/40Python Code Style & DocumentationPython code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.◐····●35/40Competitor Price Analysis 💲Competitor pricing strategy analysis and market positioning. Price mapping, pricing gaps identification, elasticity signals evaluation, and strategic pricing optimization. Use when the user asks about competitor pricing, price analysis, pricing strategy, or co◐····●34/40Competitor Price Tracker 📊Set up competitor price tracking and monitoring workflows. Track price changes, detect promotions, analyze pricing patterns, and get alerts for competitive price movements.◐····●34/40