How to use the SkillOpt-Sleep Cursor skill: install and run

What the skill makes the agent do

SkillOpt-Sleep reviews recent local Cursor sessions, mines recurring tasks, replays those tasks, and proposes bounded improvements to a project Cursor skill. With the default gate enabled, a proposal is accepted only when it improves the held-out score. A normal run stages the proposal for review, and nothing live changes until you explicitly adopt it. The skill does not train model weights.

The skill has no session-end hook and no MCP server. It runs only when you ask, or when you explicitly request a schedule.

Install the skill from the ZIP

Download the skillopt-sleep ZIP from this page and unzip it. Place the skillopt-sleep folder in one of these locations, depending on whether you want it for all projects or one project.

You can also upload the skill in the Claude apps under Settings, then Capabilities, then Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project folder

Install the SkillOpt-Sleep engine

The skill drives an engine. You need either the installed skillopt-sleep command or a SkillOpt source checkout with the SKILLOPT_SLEEP_REPO environment variable set to that checkout. If neither is available, the skill stops and asks you to install the engine. It will not substitute hand-written edits for the engine workflow.

Use one runner consistently. The installed form is skillopt-sleep <action>. From a source checkout on macOS or Linux, the runner is bash with the plugins/run-sleep.sh script. On Windows it is PowerShell with plugins/run-sleep.ps1.

• Local Cursor JSONL transcripts under ~/.cursor/projects
• An authenticated Cursor Agent CLI (cursor-agent) for the cursor backend
• Optional: authenticated claude, codex or copilot CLIs, or Azure OpenAI configuration, for those backends

Ask for it with natural requests

You do not need to remember command names. The skill triggers when you ask Cursor to learn from recent local sessions, run an offline sleep or dream cycle, consolidate recurring work into a Cursor skill, or check SkillOpt-Sleep status, harvest, dry-run, run, scheduling, review or adoption.

Good requests name the action and the scope. For example, ask for a status check first, or ask for a dry-run on the current project before any real run.

• Check SkillOpt-Sleep status for this project.
• Harvest recent Cursor sessions and show me the recurring tasks you found, without calling any model.
• Run a dry-run of SkillOpt-Sleep with the mock backend.
• Show me the latest staged proposal and what would change before adopting it.

Run the cycle step by step

Use the target path .cursor/skills/skillopt-sleep-learned/SKILL.md for Cursor-visible learning. Pass it with --target-skill-path on harvest, dry-run and run. Without it, the shared engine uses a Claude-managed skill under ~/.claude/skills, which is not the intended Cursor project skill.

Start with the deterministic mock backend. It is the default and makes no provider calls. Move to the cursor backend only after the mock check looks right, and keep runs small.

• The first harvest uses a 72-hour lookback. Use --lookback-hours N for a wider window or --lookback-hours 0 for all history.
• A stateful run records a harvest checkpoint, so later runs use it instead of the initial lookback.
• Inspect counts with harvest or dry-run before the first real run, because those actions do not advance state.
• Use --scope invoked for the current workspace or --scope all for every Cursor workspace.

Review and adopt the proposal

A normal run stages its proposal under <project>/.skillopt-sleep/staging/<timestamp>/. Review the staged result with status. Adoption is a separate, manual step, and the engine backs up existing live targets before it changes them.

For fan-out proposals, use repeatable --skill NAME or --all-skills after review. Bare adopt refuses a night that contains fan-out rows.

• A held-out gain is evidence for that run, not a promise of general improvement.
• Session and task limits are workload bounds, not hard limits on calls, tokens, time or money. Start with small limits.

Safety notes: scripts, network and transcripts

This skill runs scripts and uses the network. The cursor, claude, codex, copilot and azure_openai backends make paid provider calls and send replay content to the provider. Ordinary Cursor backend calls run in a new empty temporary workspace in read-only Ask mode, with file reads, file writes and MCP tools denied.

Harvesting keeps user and assistant text, tool names and explicit turn errors. It excludes raw tool arguments, tool outputs and non-message records, and it redacts known secret-shaped strings. Pattern-based redaction cannot guarantee that a transcript is safe to send, so for sensitive sessions export tasks first with --output reviewed-tasks.json, inspect and redact the file, and set its top-level reviewed field to true before any real-backend run.

Tool-aware replay for Cursor is temporarily disabled. A task containing a tool_called check fails before Agent mode starts. Use another backend for tool- or repository-dependent tasks.

• Real backends reject task files that remain unreviewed.
• gate_no_regression is a config-only safeguard in ~/.skillopt-sleep/config.json. It defaults to false.
• Do not put raw transcripts, credentials or sensitive task content into messages, commits or summaries.