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

What the skillopt-sleep skill makes your agent do

An agent skill is a folder with a SKILL.md file that tells Claude how to handle a certain kind of request. This one gives Claude Code a 'sleep cycle'. On demand or on a nightly schedule, it reads your recent Claude Code session logs, re-runs recurring tasks, and drafts proposed changes to CLAUDE.md (project memory) and SKILL.md (skill files).

Nothing live is changed by the cycle itself. Each proposed change is scored against a held-out set of tasks, and only changes that score better are staged. Live files change only when you explicitly adopt the staged proposal, and adoption backs up existing files first.

• Harvests past sessions from your local ~/.claude session files (read-only)
• Mines recurring tasks from those sessions
• Replays tasks through a selected backend under your current skill and memory
• Proposes bounded add, delete or replace edits and gates them on a held-out slice
• Stages results in a folder for review before anything live changes

How to install the skillopt-sleep skill

Download the ZIP for skillopt-sleep from the directory page. Unzip it into one of two locations: ~/.claude/skills/ to make the skill available in all your projects, or the .claude/skills/ folder inside a single project to limit it to that project.

If you use the Claude apps instead of Claude Code, you can upload the skill under Settings, then Capabilities, then Skills.

The source describes the runner as a bundled script referenced through ${CLAUDE_PLUGIN_ROOT}, and its requirements mention the plugin being installed. Before you rely on the commands below, confirm that the unzipped folder contains scripts/sleep.sh, and check how your setup defines that variable. The source does not spell out this path for a manual ZIP install.

• Option 1: unzip into ~/.claude/skills/ for all projects
• Option 2: unzip into <project>/.claude/skills/ for one project
• Option 3: upload the skill in the Claude apps under Settings, then Capabilities, then Skills

How to trigger the skill with natural requests

You do not need to remember command names to start. The skill activates on requests about self-improvement, sleep or dream cycles, memory consolidation, and scheduling. The source lists phrases such as the ones below as triggers.

The skill also has a /skillopt-sleep command, which the source says is the preferred way to drive it.

• 'Make my agent better the more I use it'
• 'Review my past sessions'
• 'Learn my preferences'
• 'Consolidate what you learned'
• 'Run the sleep cycle'
• 'Schedule background self-optimization'

Run a preview, a full cycle and adopt a proposal

Start with status to see what has happened, then run dry-run. Dry-run previews the cycle without writing a staged proposal. The full run stages a proposal. Adopt applies the staged proposal to your live files and creates a backup first.

The default backend is mock. It is deterministic and makes no API calls, so it is the right place to test the plumbing. Real backends use your budget and send content to a provider, as covered below.

Scope defaults to the project you invoke the skill in. Staged output is written under <project>/.skillopt-sleep/staging/ with a timestamped folder containing proposed_CLAUDE.md and/or proposed_SKILL.md, report.md, report.json, manifest.json and diagnostics.json. A rejected run has a report but no proposed replacement for the live file.

• status: shows what has happened so far
• dry-run: preview with no staging
• run: full cycle that stages a proposal
• adopt: applies the staged proposal, with a backup

Schedule the nightly cycle (optional)

The schedule action installs a nightly cron entry at the hour and minute you give. Unschedule removes the entry for one project, and unschedule with --all removes every managed entry. Only schedule if you are comfortable with a cron entry being added to your system.

Scheduling needs cron. The source does not describe how the scheduled run reports its results, so check the staging folder after the first run.

• Installs a nightly cron entry at the time you choose
• Use unschedule --project to remove one project's entry
• Use unschedule --all to remove every managed entry

Common flags and config settings

Most runs need only --project, --backend and --progress. Run python -m skillopt_sleep <action> --help for the authoritative list of options for each action. Advanced behaviour is set in ~/.skillopt-sleep/config.json.

• --project PATH: project directory to evolve (default: current directory)
• --scope all or invoked: harvest scope (default: invoked)
• --backend mock, claude, codex, copilot, handoff or azure_openai (default: mock)
• --lookback-hours N: harvest window (default: 72)
• --max-tasks N: cap on mined tasks (default: 40)
• --edit-budget N: maximum bounded edits per night (default: 4)
• --preferences TEXT: house rules added to the optimizer's reflection step
• --auto-adopt: adopt automatically if the gate passes (off by default)
• --json: machine-readable output
• Config: preferences, gate_mode (on by default), gate_metric (hard, soft or mixed; default mixed), gate_no_regression (false by default), evolve_memory and evolve_skill (toggle CLAUDE.md and SKILL.md consolidation separately)

What you need and the safety notes

The skill needs Claude Code with the skill installed, a Bash shell, and Python, because the runner calls python -m skillopt_sleep. It also needs access to your local ~/.claude session files. A real model backend (claude, codex, copilot or azure_openai) needs API access and budget. Scheduling needs cron.

The skill runs scripts and uses the network when you choose a real backend. Harvesting is read-only, and mock replay has no side effects. A real backend sends truncated transcript excerpts and derived tasks to the provider you selected. The source says the Claude transcript path is not guaranteed to remove every secret before those calls.

For sensitive sessions, stay on mock. If you need a real backend, the source suggests running harvest with --output to write a file, inspecting and redacting the JSON, setting 'reviewed': true, and then replaying from that file.

• Requires: Claude Code, Bash, Python, access to ~/.claude session files
• Optional: API access and budget for claude, codex, copilot or azure_openai
• Optional: cron for scheduling
• Runs scripts: yes. Uses network: yes (only with a real backend)
• Never hand-edit CLAUDE.md or SKILL.md through this skill; use adopt instead