Guide · Agent skill

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

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

SkillOpt-Sleep is an agent skill that lets the dsh agent review its own past sessions offline and propose improvements to its instruction and skill files. This guide is for people who may never have used agent skills before; it explains what the skill does, how to install it, how to ask for it in plain language, and what to check before you accept any change. By the end you will be able to preview a cycle with the default mock backend, read a proposal, and decide whether to adopt it.

SkillOpt-Sleep Self-Improvementmicrosoft/SkillOpt · MIT Download the skill

Quick start

1Install the plugin and skill. Make sure the dsh agent runtime has the dsh-skillopt plugin, then download the skill ZIP and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
2Check the state. Run skillopt_status. The default mock backend makes no model calls, so this step is free.
3Preview the cycle. Run skillopt_dry_run with your project directory and source. It harvests, mines and replays but stages nothing.
4Run the full cycle. Run skillopt_run with your project and chosen backend. This stages a proposal and leaves live files unchanged.
5Review the evidence. Compare the held-out baseline and candidate scores and read the exact proposed edits in the report.
6Adopt or discard. If the evidence holds up, run skillopt_adopt, which backs up live files first. Otherwise do nothing; live files stay as they were.
7Schedule optional nightly runs. Use skillopt_schedule with an hour and minute to install a cron entry, and skillopt_unschedule to remove it.

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's description. This one, skillopt-sleep, teaches the dsh agent to run an offline improvement cycle based on its own past work.

The cycle has six stages: harvest reads recent local session records, mine finds recurring tasks, replay re-runs those tasks with a selected backend, consolidate proposes bounded edits and checks them against a held-out validation gate, stage writes accepted proposals to a folder, and adopt copies them over live files with a backup. A proposal is kept only if it scores better on the held-out check. Live files stay unchanged until you explicitly adopt.

Install the skillopt-sleep skill

Download the ZIP for this skill from this page. Then either unzip it into ~/.claude/skills/ to make it available to you across projects, or unzip it into a project's .claude/skills/ folder to limit it to that project.

You can also upload the skill in the Claude apps: open Settings, go to Capabilities, then Skills, and upload the ZIP there.

Installing the skill alone is not enough. The skill drives the skillopt_* tools provided by the dsh-skillopt plugin, so that plugin must be present in your dsh agent runtime.

Project-only: unzip into .claude/skills/ inside the project.
All projects: unzip into ~/.claude/skills/.
Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

Check the setup before your first run

Start with the status tool. It reports the state of the engine, whether it is available, and the latest staged proposal and report. The default backend, mock, makes no model calls, so this step costs nothing.

The validation demo needs Python with the skillopt package. The source gives this command and the demo it runs.

Required: the dsh agent runtime with the dsh-skillopt plugin and skillopt_* tools.
For the validation demo: Python with the skillopt package.
For real backends: API credentials for the backend you choose (codex, claude, copilot, cursor, pi, opencode, or azure_openai).
For nightly runs: cron or an equivalent scheduler.

skillopt_status

pip install skillopt
python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves

Trigger the skill with natural requests

You do not need to name the tools. The skill loads when you ask for things like making the agent better with use, reviewing past sessions, learning your preferences, consolidating what was learned, running the sleep cycle, or scheduling background self-optimization.

The skill will then pick the right tool. Be specific about the project and the backend if you care about either. Preferences you state are passed to the reflection step as house rules.

"Review my past sessions for this project and tell me what you would change."
"Run the sleep cycle in dry-run mode first."
"Learn my preferences: prefer pytest and keep commit messages imperative."
"Schedule the self-optimization cycle nightly at 03:17."

Walk through a typical run

Run a preview first. A dry run performs harvest, mining and replay but stages nothing. Then run the full cycle, which stages a proposal without changing live files by default. Read the report before adopting.

Before suggesting adoption, the skill shows the held-out baseline score next to the candidate score and lists the exact proposed edits. Adopt only if the evidence supports the change.

Preview with skillopt_dry_run, passing the project directory and source.
Run with skillopt_run, choosing a backend and optional preferences.
Review the held-out baseline → candidate scores and the proposed edits.
Adopt with skillopt_adopt, which backs up live files first.

skillopt_status
skillopt_dry_run project=<dir> source=<claude|codex|…>
skillopt_run project=<dir> backend=<codex|claude|…> preferences="Prefer pytest; keep commits imperative."
skillopt_adopt project=<dir>
skillopt_schedule project=<dir> hour=3 minute=17 backend=<codex>

Configure parameters and scheduling

The main parameters are project, backend, source, model, maxTasks and preferences. The default backend is mock, and maxTasks defaults to 40. If you schedule runs, skillopt_schedule installs a nightly cron entry for the project and skillopt_unschedule removes it.

Auto-adopt is operator-only. The source states the model cannot set it, so it is configured in cordis.yml with autoAdopt set to false by default. Advanced engine settings such as gate_mode and gate_metric go in ~/.skillopt-sleep/config.json.

backend: mock (default) or a real backend such as codex or claude.
source: claude, codex, copilot, cursor, pi, opencode, or auto.
maxTasks: mined-task cap, default 40.
preferences: house rules such as "always use async/await".

- insert:
    - id: skillopt
      name: './src/index.js'
      config:
        backend: codex
        project: /path/to/project
        preferences: 'Always use async/await'
        autoAdopt: false

Safety notes: scripts, network and transcripts

This skill runs scripts and uses the network. Real backends send truncated transcript excerpts and derived tasks to the selected model provider for mining, replay, judging and reflection. If sessions are sensitive, do not use a real backend on them directly.

For sensitive sessions, export tasks first with skillopt_harvest output=<file>, redact them, and set the top-level "reviewed" field to true. Then replay with --tasks-file. Real backends refuse task files that have not been reviewed. Harvest itself is read-only, and mock replay has no side effects.

Never hand-edit AGENTS.md or SKILL.md around skillopt_adopt. Let the engine's adopt step apply the staging manifest.

Tips for better results

Run the mock backend first to confirm the plumbing works before spending API budget. Keep preferences short and concrete, since they are used as the reflection prior. Treat the validation demo as a check of the mechanism, not proof that it will help your own tasks; the source says it validates the mechanism, not effectiveness on your own tasks.

Read the docs for recorded results and limitations before you rely on the cycle for anything important.

Start with skillopt_status and a dry run.
Keep preferences specific and brief.
Review every proposal's held-out score and diff before adopting.
Consult the SkillOpt-Sleep docs for limitations.

What people use it for

Developers who run a coding agent daily and want it to learn preferences such as test framework or commit style over time.
Teams experimenting with scheduled, self-optimising agent configurations in a non-sensitive project.
Reviewing past sessions to see which recurring tasks the agent handles poorly.
Updating AGENTS.md or SKILL.md files with reviewed, evidence-based edits instead of manual guesses.

Frequently asked questions

How do I install the skillopt-sleep skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload the ZIP under Settings, then Capabilities, then Skills. The skill also needs the dsh-skillopt plugin to provide its skillopt_* tools.

Is SkillOpt-Sleep free?

The source gives the licence as MIT. The default mock backend makes no model calls, but real backends consume the selected provider's API budget, so those runs cost money. The source does not state any prices.

What do I need to run skillopt-sleep?

You need the dsh agent runtime with the dsh-skillopt plugin and skillopt_* tools. For the validation demo you need Python with the skillopt package. Real backends need API credentials, and nightly runs need cron or an equivalent scheduler.

Does skillopt-sleep change my files automatically?

No. Proposals are staged in a folder inside your project, and live files stay unchanged. Live files change only when you explicitly run skillopt_adopt, which backs up live files first. Auto-adopt exists but is operator-only and the model cannot enable it.

Is it safe to use with private code or sessions?

Use caution. Real backends send truncated transcript excerpts and derived tasks to a model provider. For sensitive sessions, export tasks with skillopt_harvest, redact them, set reviewed to true, and replay with --tasks-file. Alternatively, use the mock backend, which makes no model calls.

What should I use instead if I only want a quick answer?

The source says the cycle is multi-stage and can consume significant API budget, so it is not meant for one-off answers. For a single question, ask the agent directly without running the sleep cycle. The source does not name specific alternative tools.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose skillopt-sleep if you run the dsh agent daily, want it to learn your preferences over time, and want every change reviewed against a held-out check before it touches your files. Skip it for sensitive projects where transcripts must stay local, for quick one-off questions, or if you do not have the dsh-skillopt plugin.

Download the skill