How to use the SkillOpt-Sleep agent skill (skillopt-sleep)

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file that tells an AI agent when to use a capability and how to carry it out. The agent reads the file when a request matches the skill's description.

SkillOpt-Sleep is a usage-driven self-improvement skill. On demand or on a nightly schedule, it works through a fixed cycle: harvest past sessions, mine recurring tasks, replay them through a backend, consolidate reflections into proposed edits, gate those edits on a held-out validation score, and stage the result for review.

• Harvest: reads local session transcripts and normalizes them into session digests.
• Mine: turns digests into recurring task records with outcomes.
• Replay: re-runs those tasks under the current skill and memory.
• Consolidate: reflects on failures and proposes bounded edits.
• Gate: with the default gate on, keeps edits only when the held-out validation score improves.
• Stage: writes the proposal to a staging folder inside your project. Nothing live changes yet.
• Adopt: copies staged files over live files, keeping backups of existing targets.

Install the skillopt-sleep skill

Download the skillopt-sleep ZIP from this page and unzip it. You can install it for yourself or for a single project.

For a personal install, place the unzipped skillopt-sleep folder in ~/.claude/skills/. For a project install, place it in the project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

The skill also depends on the SkillOpt repository. Clone microsoft/SkillOpt locally and make its path available to the runner through the SKILLOPT_SLEEP_REPO environment variable.

• Python 3.10 or newer is required. The runner locates it automatically.
• Bash on macOS or Linux, or CMD or PowerShell on Windows.

Trigger the skill with natural requests

You do not need to type commands to use the skill. Describe what you want and the agent should match the request to the skill's description. The skill fires for requests about learning from past sessions, a nightly or offline sleep or dream cycle, reviewing past sessions, consolidating memory or skills, or scheduling background self-optimization.

Phrasings that should trigger it include asking Codex to learn from how you have been working, asking for a nightly run that reviews recent sessions, or asking for the status of SkillOpt-Sleep.

• Review my past Codex sessions and tell me which tasks keep recurring.
• Run a SkillOpt-Sleep dry run on this project before anything changes.
• Check the status of my SkillOpt-Sleep runs.
• Schedule a background self-optimization run for 3:17 each morning using the codex backend.
• Run the sleep cycle with the codex backend and show me the staged proposal.

Run the commands yourself

The skill drives a bundled runner script. Its actions are status, harvest, dry-run, run, adopt, schedule, and unschedule. Start with status, then a harvest, then a mock dry run.

The default backend is mock, which is deterministic and spends no API budget. Use it as the first smoke check. Only use the codex backend for a real optimization run, since it uses your Codex budget. Codex Desktop session archives are read from ~/.codex/archived_sessions when you pass --source codex. Use --codex-home if your archive lives elsewhere. A Codex skill target must be given with --target-skill-path, for example .agents/skills/example/SKILL.md.

• --backend mock: deterministic, no API spend (default).
• --backend claude: uses the Claude CLI.
• --backend codex: uses the Codex CLI.
• --backend copilot: uses the GitHub Copilot CLI.
• --backend handoff: writes prompt and answer files for an interactive session.
• --backend azure_openai: uses your configured Azure OpenAI endpoint.
• --auto-adopt: adopts automatically if the gate passes. Default is stage only.
• --edit-budget N: maximum bounded edits per night (default 4).
• --lookback-hours N: harvest window in hours (default 72).
• --json: machine-readable output.

Review the staged proposal and adopt it

After a dry run or a run, the engine reports the held-out baseline score, the candidate score, the gate action, and the number of tasks and sessions used. If it prints a staging directory, read report.md there before deciding anything. Staged files live under <project>/.skillopt-sleep/staging/ in a dated folder.

Adoption is the safety boundary. Use the adopt action only after you have reviewed a proposal that is still staged. For a fan-out night, select reviewed proposals with repeatable --skill NAME flags or --all-skills. Do not treat a bare adopt as adopt everything. Do not hand-edit CLAUDE.md or the target skill as a shortcut around adopt.

• Read report.md in the staging directory.
• Check the held-out baseline-to-candidate score and the exact proposed edits.
• Adopt with the adopt action, selecting skills explicitly where needed.

Schedule a nightly run and configure it

The schedule action sets up a recurring background run for a project, backend, and time. It stores the project, backend, time, and optional auto-adopt flag. It does not store --source or --target-skill-path, so set those in ~/.skillopt-sleep/config.json first. Scheduling uses crontab. On systems without crontab, the command prints a line you can install manually.

Config keys in ~/.skillopt-sleep/config.json include preferences (free-text house rules), gate_mode (on or off), gate_metric (hard, soft, or mixed, default mixed), gate_no_regression (false by default), dream_rollouts, recall_k, evolve_memory, and evolve_skill.

• Set "transcript_source": "codex" and an absolute "target_skill_path" before scheduling a Codex-targeted run.
• Set "evolve_memory": false if you do not want CLAUDE.md treated as a secondary target.
• Remove scheduled entries with unschedule. Use unschedule --all to remove every managed entry.

Safety notes: scripts, network and transcripts

The skill runs shell scripts and uses the network when a non-mock backend is selected. It reads local session transcripts. Harvesting is read-only: it does not edit archived sessions or raw transcripts. The Codex harvester removes known secret-shaped strings, developer instructions, and raw tool payloads, but do not assume that removes everything sensitive.

Auto-adopt can overwrite live skill and CLAUDE.md files. Backups are kept for existing targets, but review staged changes first. Live files change only through explicit adoption or a --auto-adopt you requested. The skill does not train model weights.

• Do not use this on projects whose past transcripts must not be read or sent to model backends.
• Non-mock backends may send data to external services.
• Run dry-run with the mock backend before any real run.
• An accepted held-out gain is evidence from one run, not a guarantee of broader improvement.