claude-skills/engineering/skillopt-sleep

SkillOpt-Sleep (vendored plugin)

This folder started as a verbatim copy of the skillopt_sleep engine and the Claude Code plugin surface from microsoft/SkillOpt (skillopt_sleep/, plugins/claude-code/, plugins/run-sleep.sh), only relocated so path resolution (CLAUDE_PLUGIN_ROOT-relative lookups in scripts/sleep.sh / scripts/run-sleep.sh) resolves correctly at this folder's location. Licensed under the MIT License © Microsoft Corporation. A small number of targeted patches were made afterward to close gaps between this plugin's own safety claims and what the code actually did — see Deviations from upstream below. Re-apply all of these on re-vendor; they are not upstream yet.

Deviations from upstream

1. Cosmetic — check_paths.py wording. skills/skillopt-sleep/SKILL.md's frontmatter description said "...consolidate validated CLAUDE.md/SKILL.md behind a held-out gate" — the CLAUDE.md/SKILL.md substring reads as a broken relative path to this repo's [A-Za-z0-9_\-./]+/SKILL\.md linter regex. Reworded to "CLAUDE.md and SKILL.md"; no behavior or meaning changed.
2. Safety — secrets weren't redacted in the files that actually go live. staging.py's redact_secrets() was applied to diagnostics.json and CLI error logging, but not to proposed_SKILL.md / proposed_CLAUDE.md — the exact files adopt() copies over your live CLAUDE.md / managed SKILL.md (with --auto-adopt, with no human in the loop). Since reflect()'s prompt is built from real harvested session text, a secret pasted into a real debugging session could have landed in your live memory file unredacted, despite the "secrets are redacted from prompts" claim below. Fixed: write_staging() now runs both through redact_secrets() before writing.
3. Safety — the crontab line was built via unescaped f-string interpolation. scheduler.py's _runner_cmd() wrapped project (an arbitrary filesystem path) in manual "..." quoting, then wrote the result straight into your real crontab — which cron runs through sh -c on every fire. A path containing ", `, $( ), or ; could break out of the quoting and inject an arbitrary command into your crontab. Fixed: project, logdir, log, and the repo root are now shlex.quote()-d before interpolation.
4. Safety — max_tokens_per_night was a dead config key. config.py declared it in DEFAULTS, and budget.py already had a Budget / plan_depth heuristic built for exactly this purpose, but nothing in the production run_sleep_cycle() path ever read it — a --backend claude/--backend codex night had no real ceiling on API spend. Fixed: cycle.py now starts a Budget right after backend construction (so harvest/mine spend counts too), sizes dream_rollouts down via plan_depth() when the remaining budget is tight, and appends a report note whenever it caps rollouts or the budget is exhausted at night's end — no silent truncation. This caps rollout depth per task, not a hard mid-call abort inside a single dream_consolidate() call; a night can still overshoot the cap somewhat if an individual rollout is unusually token-heavy. That residual gap is real and not yet closed.
5. Cosmetic — dead hardcoded path. backend.py's resolve_codex_path() listed ~/.nvm/versions/node/v22.22.3/bin/codex as a candidate ahead of the generic "any nvm node version" scan a few lines later, which already covers it. Removed; no behavior change for anyone not on that exact nvm version, one less leftover-looking line for everyone else.
6. Safety — redact_secrets was a dead config key. config.py declared "redact_secrets": True in DEFAULTS, but write_staging() called redact_secrets() unconditionally — the safe direction, but the knob had no effect either way. Fixed: cycle.py now reads cfg.get("redact_secrets", True) and threads it through write_staging() and the diagnostics.json fields; disabling it is honored (it's the user's config) but never silently — a report note fires whenever it's off.
7. Hardening — adopt() now re-redacts as defense-in-depth. Previously adopt() copied the staged proposed_SKILL.md/proposed_CLAUDE.md straight to the live path with shutil.copy2. Since write_staging() already redacts, this was redundant for the common case, but didn't cover a human hand-editing the staged proposal between stage and adopt (the exact workflow staging exists to allow). adopt() now reads, re-runs redact_secrets(), and writes each file rather than a raw byte copy; _backup() of the prior live file is unaffected (that's a backup of what already existed, not the incoming content).
8. Safety — scheduler.py's extra param wasn't shell-quoted. project/logdir/log/repo-root were shlex.quote()-d in fix #3 above, but extra (today only ever "" or the literal "--auto-adopt" from __main__.py) was appended raw. Not exploitable today since it's a hardcoded flag literal, but reopens the same class of bug if a future change lets extra carry anything else. Fixed: extra is now shlex.split() into tokens and each token shlex.quote()-d before joining, so a multi-token or attacker-influenced extra can't break out of the command the way project used to.
9. Safety — the cross-night task archive (state.json) was never redacted. state.py's add_to_archive() persists raw TaskRecord content (intent / context_excerpt / attempted_solution — real harvested prompt/response text) to ~/.skillopt-sleep/state.json indefinitely, for recall_k associative recall across nights. Unlike proposed_SKILL.md/proposed_CLAUDE.md/diagnostics.json (fixes #2, #6), this file lives entirely outside the staging dir a user is ever told to review — a secret pasted into a real debugging session would have landed there and stayed. Fixed: cycle.py now redacts each task dict before archiving, using the same redact_enabled flag (and loud report-note-on-disable) as everything else.
10. Safety — report.md / report.json were never redacted. These are the two artifacts a human is told to read first (the SKILL.md's own workflow says "Read the generated report.md... show the user the exact proposed edits"), yet EditRecord.content/.rationale — sourced from the optimizer's reflect() output over real failing task responses — were written unredacted, while the sibling proposed_SKILL.md/ proposed_CLAUDE.md/diagnostics.json got fixed in earlier rounds. Fixed: write_staging() now redacts the rendered report_md string and report.to_dict() (via redact_secrets's existing recursive dict/list/ str handling) before writing report.md/report.json.
11. Safety/cosmetic — dead config knob: replay_mode. config.py declared "replay_mode": "mock" | "fresh" (worktree), but the only production code path that reads it prints a cosmetic label in the report — there is no worktree-replay implementation anywhere in this engine. Implementing real worktree isolation was judged too invasive for a vendored copy (a substantial new feature in code this repo doesn't otherwise maintain); instead, cycle.py now appends a loud report note whenever replay_mode is set to anything but "mock", so the report never implies real worktree isolation that isn't happening.
12. Sensitive — hardcoded internal Azure OpenAI infrastructure removed. backend.py shipped an AzureOpenAIBackend/AzureResponsesBackend pair with 5 internal-looking Azure endpoint hostnames and a hardcoded Managed Identity client ID, explicitly commented as sourced from "the intern's avail_api.md" — reads like leaked internal Microsoft dev-infra topology. This backend was already unreachable from this plugin's documented mock/claude/codex/copilot --backend choices (only settable by hand-editing ~/.skillopt-sleep/config.json directly) and requires azure-identity/openai third-party packages this repo never claims to depend on. Removed entirely (classes, constants, get_backend()/ build_backend() dispatch branches and the now-unused azure_endpoint parameter); get_backend("azure") now safely falls back to MockBackend instead of raising or wiring internal infra. Same class of "leftover internal-looking detail" as fix #5's dead nvm path, but materially more sensitive, so it was removed rather than just flagged.
13. Safety — unvalidated tool names reachable via --tasks-file. attempt_with_tools() (all three CLI backends) used a task's tool name both as a shim filename (os.path.join(work, tname)) and interpolated unescaped into the shim's generated shell body (f'echo "{tname}" >> ...'). Tool names originate from a hand-authored --tasks-file's judge.checks[].arg (op=="tool_called"), never validated as a safe identifier — a crafted name containing ../, ", backticks, or $( ) could traverse out of the working dir or inject a command into the generated shim. Not reachable via the harvest/mine path today (the LLM miner excludes this check type), but --tasks-file is a documented, user-facing input. Fixed: a shared _sanitize_tool_names() helper filters to a safe-identifier allowlist (^[A-Za-z0-9_-]{1,64}$) before any name is used as a filename or shell text, in all three backends.
14. Cosmetic — dead cross-reference in SKILL.md. skills/skillopt-sleep/SKILL.md pointed to docs/superpowers/specs/2026-06-07-skillopt-sleep-claude-code-plugin-design.md "for the full design" — that path is not in this repo (see "What was and wasn't vendored" below; docs/ was deliberately excluded). An agent following the pointer hits a missing file. Fixed: points to the real upstream guide URL (microsoft.github.io/SkillOpt/docs/guideline.html#sleep) instead, with a note on why the local path is absent.
15. Safety — commands/skillopt-sleep.md didn't signal that schedule installs immediately. The command doc's action table listed schedule as an ordinary action alongside status/dry-run/run (all of which are safe previews or explicitly staged), while its own "Safety reminders" section separately said to point users at the print-only install-cron.sh instead — two different, uncoordinated stories about the same action. scheduler.schedule() writes directly to the user's real crontab the moment it runs, with no confirmation step in between. Fixed: "Steps to follow" now has an explicit step 1 telling the agent to confirm with the user before running schedule (what project/hour/ minute/backend will be scheduled), with install-cron.sh offered as the print-only alternative; "Safety reminders" now says the same thing instead of contradicting the action table.
16. Hardening — state/staging directories and files had no restrictive permissions. state.json (the cross-night task archive) and .skillopt-sleep/staging/<ts>/'s proposal/report/diagnostics files contain real harvested session content in plaintext, created via plain os.makedirs/open(..., "w") — world-readable-by-default on a typical multi-user Linux box (subject to the process umask). redact_secrets() scrubs known secret patterns, but the files still carry real task intents, code excerpts, and project context otherwise. Fixed: both state.py and staging.py now os.chmod() every directory they create to 0o700 and every file they write to 0o600 (best-effort, silently skipped on platforms without POSIX permission bits). Live CLAUDE.md/ SKILL.md files themselves are intentionally left at their existing permissions — those are the user's own, often-committed files, not new output this plugin introduces.
17. Cosmetic — misleading redaction placeholder label. staging.py's sk-[A-Za-z0-9_-]{10,} pattern matched any sk--prefixed key (OpenAI, Anthropic's sk-ant-..., and other vendors sharing the convention) but labeled every match [REDACTED_OPENAI_KEY] regardless of which vendor's key shape it actually was. Redaction itself was unaffected — the text was scrubbed either way — but the placeholder implied a narrower match than the pattern actually has. Fixed: relabeled to [REDACTED_API_KEY].
18. Cosmetic/hardening — stale fallback paths in the shell launchers. scripts/sleep.sh's header comment and its SKILLOPT_SLEEP_REPO fallback branch referenced upstream's <repo>/plugins/run-sleep.sh layout; scripts/run-sleep.sh's header comment and its CLAUDE_PLUGIN_ROOT branch likewise assumed the upstream three-level <repo>/plugins/claude-code/ structure (CLAUDE_PLUGIN_ROOT/../../ skillopt_sleep). In this vendored copy scripts/ and skillopt_sleep/ are siblings directly under the plugin root (engineering/skillopt-sleep/), so CLAUDE_PLUGIN_ROOT (when Claude Code sets it) points straight at a dir containing skillopt_sleep/, not two levels above one. Both scripts' primary co-located/repo-relative resolution branches happen to still succeed for this layout regardless (so this was unreachable in normal operation), but the documented SKILLOPT_SLEEP_REPO and CLAUDE_PLUGIN_ROOT escape hatches would have silently failed to resolve for anyone actually relying on them — e.g. after a future re-vendor that missed copying run-sleep.sh into scripts/. Fixed: sleep.sh's explicit-env branch now checks $SKILLOPT_SLEEP_REPO/scripts/run-sleep.sh; run-sleep.sh now checks $CLAUDE_PLUGIN_ROOT/skillopt_sleep (this repo's actual layout) ahead of the upstream two-levels-up check (kept for portability if this script is ever reused in that shape again). Verified both fixed branches resolve correctly in isolation from the co-located fallback.
19. Safety — the CLI's own stdout/--json/--output bypassed redact_secrets() entirely. Rounds 1-3 covered every file write_staging()/state.py write, but __main__.py's cmd_run() reads the same in-memory Report object and prints EditRecord.content (raw, from reflect()'s output over real task responses) directly to the console, and _report_payload() serializes it unredacted for --json — write_staging()'s redaction runs on a copy (redact_secrets(report.to_dict())) used only for the on-disk JSON, it never touches report.edits itself. Concretely: scheduler.py's cron entry redirects run's stdout/stderr straight into <project>/.skillopt-sleep/cron.log — a secret that leaked into a proposed edit's content would land there in plaintext on every scheduled night, in a file that (unlike state.json/staged files) also had no chmod protection (see the second fix below). cmd_harvest()'s debug output (--json, --output <file>, and the plain-text loop) has the same shape: it prints raw mined TaskRecord.intent text so a human can review it before setting "reviewed": true on a --tasks-file, which means redacting it doesn't reduce what's reviewable (only secret-shaped substrings are stripped) while closing the same leak path. Fixed: _report_payload() and cmd_run()'s plain-text edit printing, and cmd_harvest()'s payload (covering its --output file, --json stdout, and plain-text loop uniformly), all now run through redact_secrets(), gated on the same redact_secrets config flag as everywhere else. Also hardened scheduler.py's generated cron line to chmod 700 the .skillopt-sleep log dir and chmod 600 cron.log itself (best-effort, 2>/dev/null) before each run appends to it — that file was never covered by the state/staging chmod pass in fix #16. Verified: a synthetic secret seeded into a task's intent no longer appears in cmd_run's --json payload or plain-text edit output, or in cmd_harvest's redacted payload; executing the actual generated cron line end-to-end produces a 0700 log dir and 0600 log file on disk.
20. Bug — scheduler.py's per-project marker match used unanchored substring comparison. schedule()/unschedule() both located "this project's" managed cron line via marker not in ln, a bare substring test, not an exact-match or delimiter-anchored check. Failure scenario: two projects scheduled where one path is a literal prefix of the other (e.g. /home/user/app and /home/user/app-v2) — _project_marker produces # project=/home/user/app, which is itself a substring of # project=/home/user/app-v2's line. Running schedule() or unschedule() for /home/user/app would silently drop /home/user/app-v2's cron entry too, with no error or warning — the user's other project's nightly job just disappears. harvest.py's _project_matches() (added in this same PR) already gets this right a few hundred lines away (a == b or a.startswith(b + os.sep) or b.startswith(a + os.sep)); scheduler.py's marker matching didn't follow the same discipline. Fixed: added _line_matches_project(), which anchors on ln.rstrip().endswith(marker) since the marker is always the last token of a generated line (see schedule()'s cron_line construction) — used at both call sites. Verified two ways: a standalone reproduction confirmed the bug before the fix and its absence after, and a full schedule()/unschedule() round-trip through the actual public API (with crontab -l/crontab - swapped for an in-memory fake) confirmed scheduling both /home/user/app and /home/user/app-v2, then unscheduling only app, correctly leaves app-v2's line intact.
21. Cosmetic — install-cron.sh's printed --backend value was unquoted. scheduler.py::_runner_cmd quotes every interpolated value with shlex.quote(), but the standalone install-cron.sh script (which only prints a crontab line for the user to copy into crontab -e — nothing is executed automatically) interpolated --backend ${BACKEND} unquoted in its heredoc, next to otherwise-quoted ${RUNNER}/${PROJECT}. Low risk since BACKEND is normally one of a fixed small set of values and the script never executes anything itself, but inconsistent with the quoting discipline applied everywhere else. Fixed: quoted as "${BACKEND}".
22. Hardening — schedule had no confirmation gate at the CLI layer. The deviation #15 "confirm with the user before schedule" safeguard lived only in commands/skillopt-sleep.md's agent-facing instructions — cmd_schedule() itself called scheduler.schedule() directly and installed a real crontab entry immediately. That's fine for the documented Claude Code agent workflow (which confirms in chat first), but anyone invoking python -m skillopt_sleep schedule directly bypassed it entirely, with no gate in the CLI itself. Fixed: schedule now requires --yes; without it, an interactive terminal gets a [y/N] prompt and a non-interactive one (no TTY) refuses outright with an exit code (2) pointing at --yes. commands/skillopt-sleep.md updated so the driving agent passes --yes once it has confirmed with the user in chat — that chat confirmation is what --yes records, not a redundant re-prompt (which would hang forever with no TTY to answer from inside a non-interactive Bash tool call anyway). Verified: non-interactive schedule without --yes refuses with exit 2; with --yes it proceeds to the same scheduler.schedule() call as before.
23. Hardening — mkdir-then-chmod wasn't atomic. write_staging() (staging.py) and SleepState.save() (state.py) called os.makedirs(path, exist_ok=True) and only chmod'd afterward, leaving a brief window where a freshly-created sensitive directory sat at the process's default umask — exactly what this plugin's chmod hardening (deviation #16) exists to close. Fixed: the os.makedirs() calls that create the state dir, the per-run staging leaf dir, and the adopt-time backup dir now pass mode=0o700 directly, closing the window for the common first-creation case. The existing post-creation chmod calls are kept, not removed — mode= only governs the leaf directory mkdir() itself creates (intermediate parent directories still fall back to the umask default) and is itself still subject to umask, so it narrows the window rather than eliminating every case (e.g. a directory that already existed from before this fix, or an intermediate parent). The equivalent race for individual files (open(path, "w") then chmod after) is a smaller, harder-to-close window — closing it fully would mean rewriting every file-write call site to use os.open() with an explicit mode instead of the builtin open(), which felt like a larger rewrite than this specific, low-severity (requires a local attacker with precise timing) finding warranted; left as a known, narrower residual gap rather than silently claimed as fully closed.

What this plugin is

SkillOpt-Sleep gives a local Claude Code agent a nightly sleep cycle: it reviews real past sessions in this repo, replays recurring tasks offline on your own API budget, and consolidates what it learns into this repo's CLAUDE.md memory and SKILL.md skills — but only through a held-out validation gate, and only after you explicitly adopt the staged proposal.

It is the deployment-time companion to the (not vendored) skillopt training package: SkillOpt trains a skill offline against a labeled benchmark; SkillOpt-Sleep applies the same bounded-edit + held-out-gate discipline to actual usage of this repo instead, so it needs no benchmark dataset.

harvest ~/.claude transcripts (read-only)
  → mine recurring tasks
  → replay offline
  → consolidate (reflect → bounded edit → GATE)
  → stage proposal (nothing live changes)
  → you review and run "adopt" (backs up first)

Why this is a fit for a skills library with no test harness

This repo's CLAUDE.md intentionally has no build system or test framework, and skill scripts/ are stdlib-only with no LLM calls, so the full microsoft/SkillOpt training package (benchmark-driven, requires labeled train/val/test data per task, needs numpy/openai/azure-*) was not vendored — there is no natural ground-truth benchmark for something like finance/dcf-valuation or c-level-advisor/vpe-advisor.

skillopt_sleep, by contrast, has zero third-party dependencies (stdlib only), its default mock backend spends no API budget, and it mines its "benchmark" from how the skills in this repo actually get used in real sessions rather than a pre-labeled dataset. That matches the repo's deterministic-first, portable-first philosophy far better than the training package does.

Use in this repo

# from the repo root:
engineering/skillopt-sleep/scripts/sleep.sh status                          # what's happened (read-only)
engineering/skillopt-sleep/scripts/sleep.sh dry-run  --project "$(pwd)"     # safe preview, stages nothing
engineering/skillopt-sleep/scripts/sleep.sh run      --project "$(pwd)"     # full cycle, stages a proposal
engineering/skillopt-sleep/scripts/sleep.sh adopt    --project "$(pwd)"     # apply staged proposal (backs up first)

Or, once the plugin is installed via Claude Code's plugin marketplace, use the bundled /skillopt-sleep [run|dry-run|status|adopt|harvest|schedule|unschedule] slash command (see commands/skillopt-sleep.md and skills/skillopt-sleep/SKILL.md).

Default backend is mock (deterministic, no API spend — safe to try immediately). Add --backend claude to spend real budget replaying this repo's own recurring tasks and get genuine lift on CLAUDE.md / a target SKILL.md.

Safety model

• Harvest is read-only over ~/.claude session transcripts.
• Edits are proposed, gated against a held-out replay slice, and staged under .skillopt-sleep/staging/<date>/ — nothing live is touched.
• adopt is explicit and backs up the prior file first (unless you opt into --auto-adopt).
• max_tasks_per_night is a hard cap (mining stops there). max_tokens_per_night sizes dream_rollouts down via plan_depth() and is reported when hit, but is not a hard mid-call abort — see deviation #4 above for the exact scope.
• Secrets (API keys, bearer tokens, private-key blocks) are redacted before anything is written to the staging dir, including proposed_SKILL.md / proposed_CLAUDE.md (deviation #2 above) — not just diagnostics — and re-redacted again at adopt() time as defense-in-depth against a hand-edited staged proposal (deviation #7). Disabling this via redact_secrets: false is honored but never silent — it logs a report note (deviation #6). The same flag now also covers the cross-night task archive (state.json, deviation #9), report.md/report.json (deviation #10) — the two files a human is actually told to read first — and every CLI console/--json/--output code path (cmd_run, cmd_harvest), not just what gets written to disk (deviation #19). cron.log (the CLI's redirected stdout/stderr) is now chmod 600 too, matching state/staging (deviation #19).
• The generated crontab line, including the extra flags parameter, is fully shlex.quote()-d, not just the path arguments (deviations #3, #8, #21). schedule/unschedule locate a project's own line via an anchored end-of-line match, not a bare substring test, so scheduling/unscheduling one project can't silently drop a sibling project whose path happens to be a prefix of it (deviation #20).
• replay_mode: "fresh" (worktree replay) is not implemented — every replay runs as "mock" regardless, and the report says so explicitly rather than implying isolation that isn't happening (deviation #11).
• Tool names reachable via a hand-authored --tasks-file are validated against a safe-identifier allowlist before being used as a shim filename or interpolated into generated shell text (deviation #13).
• Only mock/claude/codex/copilot backends are supported — a Microsoft-internal Azure OpenAI backend was removed rather than carried forward (deviation #12).
• schedule installs a real crontab entry immediately — unlike every other action, it is not a preview or a staged proposal. An agent driving /skillopt-sleep schedule must confirm with the user first (deviation #15); install-cron.sh remains available as a print-only alternative.
• Every directory state.py/staging.py create is chmod 0700 and every file they write is chmod 0600 (best-effort), so state.json and staged proposals/reports/diagnostics aren't left at the world-readable process umask default on a shared machine (deviation #16).

What was and wasn't vendored

Vendored	Not vendored
skillopt_sleep/ engine (stdlib-only)	skillopt/ training package (needs numpy/openai/azure-* + labeled benchmarks)
plugins/claude-code/skills|hooks|commands|scripts/	plugins/codex/, plugins/copilot/, plugins/devin/, plugins/openclaw/ (other-agent plugin variants)
plugins/run-sleep.sh shared launcher	skillopt_webui/ (optional Gradio dashboard)
LICENSE	docs/, ckpt/, data/, index.html (training-package docs/site/checkpoints)
	AzureOpenAIBackend/AzureResponsesBackend from backend.py — removed post-vendor, see deviation #12 (Microsoft-internal endpoints/client ID, unreachable from this plugin's supported --backend choices, needs deps not vendored here)

Updating

Re-vendor from upstream when the plugin changes:

git clone --depth 1 https://github.com/microsoft/SkillOpt.git /tmp/skillopt-upstream
cp -r /tmp/skillopt-upstream/skillopt_sleep engineering/skillopt-sleep/skillopt_sleep
cp -r /tmp/skillopt-upstream/plugins/claude-code/skills/skillopt-sleep engineering/skillopt-sleep/skills/skillopt-sleep
cp -r /tmp/skillopt-upstream/plugins/claude-code/hooks engineering/skillopt-sleep/hooks
cp -r /tmp/skillopt-upstream/plugins/claude-code/commands engineering/skillopt-sleep/commands
cp /tmp/skillopt-upstream/plugins/claude-code/scripts/sleep.sh /tmp/skillopt-upstream/plugins/claude-code/scripts/install-cron.sh engineering/skillopt-sleep/scripts/
cp /tmp/skillopt-upstream/plugins/run-sleep.sh engineering/skillopt-sleep/scripts/run-sleep.sh
cp /tmp/skillopt-upstream/LICENSE engineering/skillopt-sleep/LICENSE