SkillOpt (arXiv:2605.23904, Executive Strategy for Self-Evolving Agent Skills)\norganizes a hill-climb into epochs × mini-batches under a decaying integer\nedit budget. The name is the paper's; the algorithm edits whatever the\nselected capability owns — a prompt, a tool surface, a skill package — and never\nassumes which.
\nRead the shared step first, then this file. Parent materialization, the\noptimizer call, the val evaluation, the significance gate, accept/reject,\nsnapshot/best, the memory and handover files: all of that is\nharness.run_step, documented once in algorithms/hill-climb/SKILL.md\n§ \"One iteration, end to end\" and algorithms/hill-climb/references/run-step.md.\nThis file states only what SkillOpt does differently.
Know the bound before reaching for this algorithm: run_step lets a caller\nvary exactly two things — parent_dir and instructions. SkillOpt pins\nparent_dir to the current best, identical to hill-climb, so everything novel\nlives in the instructions string plus the choice to run one extra step per\nepoch. It is prompt shaping and step scheduling, not a different search.
L. lr_schedule.build_schedule emits one\ninteger per step over constant | linear | cosine, clamped to\n[--min-edit-budget, --edit-budget] (core/cap_evolve/lr_schedule.py:42-55).\nL is stated to the optimizer in prose — \"at most L bounded edits\" — and is\nnever mechanically enforced. See the next section before you tune it.skillopt.py:120-125, :330-335). It carries no description of what the\nrejected edit changed, so treat it as a weak signal — the run-global\nLEDGER.md that run_step already injects names the tasks each prior edit\nbroke and fixed, which is strictly more useful.run_step and the same val gate — it is never\nforce-accepted (skillopt.py:493-499). Disable with --no-slow-update.\nA fourth bucket, improved, is computed and logged but is not exclusive\nwith the others and never reaches the prompt (skillopt.py:184-191, :139-166).Epochs shuffle the train ids seeded by epoch number, so a rerun is reproducible.\nsteps_per_epoch = ceil(len(train) / (batch_size × accumulation)).
The knob is real: L decays, it is an integer, and the schedules are correct.\nThe justification is weaker than the ML vocabulary implies, and pretending\notherwise would mislead anyone tuning it.
What plausibly holds: the gate accepts or rejects a whole candidate. A candidate\nbundling six edits where five help and one hurts is rejected entirely, and you\nlearn nothing about which edit was the problem. Fewer edits per candidate means\nan accepted candidate is more likely to contain only good edits and a rejected\none is cheaper to attribute and revert. That argues for small edits — it does not\nby itself argue for decay.
\nWhat does not transfer: in SGD, LR decay exists because nothing stops a large\nstep from overshooting near an optimum. Here the val significance gate already\nrejects an overshooting edit before it can become the parent. The overshoot\nprotection is the gate, so the decay is not doing that job.
\nWhat is unmeasured: no ablation in this repo isolates the schedule's effect.\nAt realistic step counts the choice barely exists — over 12 steps from 4 down\nto 2, linear and cosine differ at 2 of 12 positions. Prefer constant or\nlinear and spend your tuning budget on --n-trials and the gate instead. This\nis a heuristic that has not been isolated; do not present it as a proven one.
These are shipped-behavior defects in core/cap_evolve/skillopt.py. The skill\ndescribes what the code does today, not what it intends to do. Line numbers are\nagainst current main — check them; if one no longer says what it is cited for,\nthe gap has moved and this section is what needs re-deriving.
skillopt.py:237, sliced at :291) but are handed to\nctx.instructions (:300) to filter the parent's val rows\n(harness.py:2270-2272; the same train-vs-val mismatch at :323, :327), and\nsplits are disjoint slices (splits.py:117-119). So the focus summary always\nrenders 0 solid / 0 flaky / 0 failing of 0 focused task(s) of N on val, the\nfailure index is empty, and ## Failure patterns still unsolved never appears —\nwhile the (mini-batch of N train tasks, L=…) label still prints, which is why it\nlooked healthy. (The whole-val protect-these-ids block is populated, from\nharness.py:2279 — that is the only per-task content a step gets, and #391 added\nthe of N on val scope precisely so those two numbers stop contradicting each\nother.) Until #371 lands the per-step signal is the label plus the L sentence, so\nthe epoch/mini-batch structure is bookkeeping rather than focus. PR #370 fixed the\nsame defect in hill-climb's cyclic/hardest-first modes.skillopt.py:467-472 calls evaluate_candidate(..., split=\"train\") twice with\nno ids=, then discards everything outside the ~20 sampled ids\n(:473-475). Budget it as 2 × len(train) × n_trials rollouts per boundary.prev_epoch_best_id != run_dir.best_id (skillopt.py:464); if\nnothing moved, both sides stay current_val — the same list — so 0 regressed\nand 0 improved are reported over val tasks while the log line claims a\ntrain sample size (:478-482). The consolidation step still runs.requested_edits vs applied_changes surfaces nothing, and the number is wrong.\n_changed_components (skillopt.py:406-435) counts files whose bytes differ, not\nedits, and applied_changes is written at :346/:353 and read nowhere — no\ndashboard column, no check, no warning. It also over-counts, because its ignore\nlist (:420) matches seven .md basenames while run_step injects a whole\nread-context — guidance/, trajectories/, prior_iterations/*/diff.patch — that\n_SNAPSHOT_IGNORE keeps out of the parent snapshot, so every injected file reads\nas an applied edit. Measured zero-API on examples/toy_calc at L=4: a step whose\noptimizer edited exactly one file logged applied_changes: 10 (9 injected + 1\nreal), and the next step logged 10 again with the capability file byte-identical\nto its parent. The metric has no zero, so it cannot detect the one thing it exists\nto detect: an optimizer that made no edit at all.skillopt.py:147 tells the optimizer to\ncompare \"the skill\" regardless of which capability is under optimization. An\nalgorithm must be capability-agnostic; this text is not.--epochs, --batch-size, --accumulation (mini-batches per step; multiplies\nthe effective batch), --edit-budget / --min-edit-budget / --lr-schedule,\n--slow-update-sample, --no-slow-update. --resume, --no-regression,\n--n-trials, --workers, --gate-mode, --k-se, --protected-paths,\n--store behave as in hill-climb.
--max-iterations is accepted and ignored — the loop is epoch-driven, so\ncap-evolve run's iteration cap has no effect here (scripts/run.py:42-43, whose\nhelp text now says so). Control the step count with --epochs/--batch-size.
python scripts/run.py --run-dir .capevolve/run_X --project .capevolve/project \\\n --optimizer 'python .../run-optimizer/scripts/run.py --name mock --workdir {workdir} --prompt {prompt}' \\\n --epochs 4 --batch-size 8 --accumulation 1 \\\n --edit-budget 4 --lr-schedule linear --min-edit-budget 2 --n-trials 4\nRequires baseline.json first, like its sibling algorithms.
references/concepts.md — the loop step by step, the schedule shapes with\nworked values, and the buffer / consolidation mechanics. Load it when you need\nto change the loop or reason about its rollout cost, not to run it.