SkillOpt#

SkillOpt makes bounded edits to a skill document, with an optional validation gate, slower epoch-end updates, and a meta skill. Choose it when the learnable object is a skill or instruction document and you can afford validation rollouts.

Setup#

python -m pip install -e . -r requirements-skillopt.txt

In a complete task config, select evolver.name: skillopt, provide data.val, and configure the learner’s llm. Start with OfficeQA, the SkillOpt paper’s setting, which also uses SkillOpt on the acting side.

Update and selection#

Each framework step runs a SkillOpt update on the batch. With use_gate: true, the method keeps an update only if its validation score improves. The slow update and meta skill run at an epoch boundary when enabled. Finalization considers the method’s retained validation candidates.

A slow update can make the last step of an epoch substantially more expensive than other steps. Set trainer.call_timeout_min with that work in mind.

Parameters and defaults#

description: SkillOpt bounded, validation-gated skill optimization (microsoft/SkillOpt), one SkillOpt step per training
  step, with its slow update and meta skill at the end of each epoch. Uses the run's `llm` tool and run_agent.
class: evolver.py:SkillOptEvolver
needs: [validation_data]
params:
  file: ADAPTER.md            # the skill document
  minibatch_size: 8           # rollouts per reflection call
  merge_batch_size: 8         # patches per merge call
  analyst_workers: 16         # parallel model calls
  failure_only: false         # reflect on failures only
  learning_rate: 4            # most edits per step
  min_learning_rate: 2
  lr_scheduler: cosine        # constant, linear or cosine
  total_steps: null           # steps in the run, for linear or cosine decay; null: constant learning rate
  use_gate: true              # keep an update only if the validation score improves
  gate_metric: hard           # hard, soft or mixed
  gate_mixed_weight: 0.5
  success_score: 1.0          # a run scoring at least this counts as solved
  use_slow_update: true       # with the meta skill, at an epoch's last step: allow for it in trainer.call_timeout_min
  slow_update_samples: 20     # training tasks run with both epochs' skills
  slow_update_gate: false     # true: the slow update passes the validation gate too (the paper's protocol)
  use_meta_skill: true
  prompt_env: ""              # officeqa: SkillOpt's OfficeQA analyst prompts; empty: its generic prompts
  obs_chars: 0                # characters of each tool result shown to the analyst; 0: all, as in SkillOpt
  trajectory_view: full       # paper: clip trajectories and prompts as SkillOpt did for the paper (v0.1.0)
  codex_trace_to_optimizer: true   # show the analyst a run's Codex trace summary (SkillOpt's Codex harness)
  promote_final: true         # score the final skill on validation and keep it if it beats the best
  max_tokens: null            # null: SkillOpt's own limit for each call
  temperature: null           # null: the endpoint's default
  seed: 42

Key controls and their interactions#

Control	Values / interpretation	Effect
`file`	One learnable document path	The optimized skill; defaults to `ADAPTER.md`
`learning_rate`, `min_learning_rate`	Edit-count bounds / 4 and 2	Bound selected patches, not model optimizer step size
`total_steps`, `lr_scheduler`	Positive step count and `constant`, `linear`, or `cosine`	Null/zero total uses a constant schedule; the update counter advances when patches reach merge/selection
`analyst_workers`, `minibatch_size`	Positive parallel-worker and reflection-batch sizes	Control reflection concurrency and grouping independently of `agent.concurrency`
`use_gate`	Boolean / true	A candidate must strictly beat the current metric; false still evaluates validation and force-accepts a valid candidate
`gate_metric`, `gate_mixed_weight`	`hard`, `soft`, or `mixed`; weight in [0, 1]	Select the metric for validation comparison; see below
`use_slow_update`, `slow_update_gate`	Booleans / true and false	Enable epoch-end work and separately choose whether its slow-update candidate must pass validation
`promote_final`	Boolean / true	If final current skill differs from best, re-evaluate it at finalization and promote it only on improvement
`codex_trace_to_optimizer`	Boolean / true	Show the analyst each run’s Codex trace summary (`codex_trace_summary.txt` in the run’s log, written by SkillOpt’s Codex harness), as SkillOpt does for a Codex target

Understand the validation score#

This integration converts each judged attempt to a hard success flag using score >= success_score (default 1.0). Its soft value comes from the judge result’s extra.f1 when present, otherwise the numeric score. hard compares aggregate success, soft compares aggregate partial credit, and mixed uses (1 - weight) * hard + weight * soft. Keep the components on comparable scales.

Ordinary gating requires strict improvement, so ties reject. The pinned upstream gate implementation defines that comparison. Disabling use_gate does not save the validation calls in this integration. Validation is cached by skill content, while final promotion deliberately refreshes the final candidate’s score.

Budget the epoch boundary#

With the corresponding features enabled, the end of an epoch performs slow-update and meta-skill work after the ordinary step update. slow_update_samples controls additional training comparisons. The default slow_update_gate: false means the ordinary gate setting does not automatically protect a slow update. The OfficeQA configs explicitly choose their protocol.

Allow enough trainer.call_timeout_min for the entire call, not just a single reflection. Inspect saved state/ and output/report.md to distinguish no patches, invalid edits, gate rejection, and final promotion.

Do not describe a run as a paper reproduction solely because it uses SkillOpt. Data revision, models, tools, gating, and trajectory truncation must match the claimed protocol. The OfficeQA recipe records the current differences.