/opro-rsi-toolkit

name: opro-rsi-toolkit
description: Reproduce OPRO (Large Language Models as Optimizers, Yang et al. 2023) on an agent and a frozen Benchmark, or on the precise-summary demo task shipped with this Skill: propose instructions from the scored history, measure each one, keep the best.
version: 2026.10.12.1

OPRO

[Large Language Models as Optimizers](https://arxiv.org/abs/2309.03409) (Yang et al., Google DeepMind, 2023; [paper v3](https://arxiv.org/abs/2309.03409v3), §4–5, especially §4.2 and §5.4), code at [google-deepmind/opro](https://github.com/google-deepmind/opro). Verified implementation revision `a76bdce2cbf6d4a0d1e570a6fcfe17be9c2abdd7`: `opro/optimization/optimize_instructions.py` and `opt_utils.py`. OPRO optimizes one instruction: an optimizer model reads the instructions measured so far with their scores, proposes new ones, every proposal is measured on the training cases, and the highest training score is kept. Model weights, tools and the rest of the Target's harness stay fixed; OPRO has no Reflector, Curator, textual gradient or Trace critique, so add none. Run the method the way the paper does; every departure is a declared adaptation reported at the end.

Before you start

This Skill is the experiment's controller and needs `run_subagent`; if that tool is missing you are a subagent: stop and say the Skill needs a top-level Session. If the request only names this Skill, ask for the Target and the Benchmark, and offer the demo task. Otherwise resolve the inputs below, asking only for one the method needs and the request does not give:

• `test_agent_id`: the Target, an existing Agent of this Project, or `create: <id>` for a fresh one. Never the Agent running this Skill: its workers are this Agent.
• `benchmark_id`: a published Benchmark of this Project; its cases are OPRO's training set. When the user asks for the demo task, build it from `references/demo-task.md` first: it fixes the Target, the Benchmark and the budget.
• `case_ids`: every case unless the user names a subset. `runs`: Runs per Case, 1 unless given.
• The Target's runtime, fixed as `references/evaluation.md` says. The proposer is this Session's model.
• The method's parameters, with the values of the source script:

| Parameter | Source | Smoke profile (the default) | | --- | --- | --- | | `num_search_steps` (S) | 200 | 2 | | `num_generated_instructions_in_each_step` (P) | 8 | 2; the demo task uses 4 | | `max_num_instructions` | 20 | 20 | | `num_score_buckets` | 100 | 100 | | `old_instruction_score_threshold` | 0.3 with GPT scorers, 0 with text-bison | 0 | | Exemplars per step, k (`num_few_shot_questions_for_instruction_refinement`) | 3, drawn at random, seeded by the step | 3 | | `few_shot_qa_pairs` | true: each exemplar carries its training answer | false unless the user supplies or authorizes training outputs | | `initial_instructions` | `Let's solve the problem.` | the same, unless the user declares a seed | | Sampling | optimizer temperature 1.0, scorer 0.0 | the providers' defaults (Penguin sets no temperature); record it |

The smoke profile applies unless the user sets parameters. The source's budget (200 steps × 8 proposals) is never a default: run it only when the user asks for it, after you state its arithmetic (see "Budget") and they confirm. A target score or a round limit is not an OPRO parameter: report against one if given, but never stop or skip on it.

Paths and records

The paths of `references/evaluation.md`, from the Environment's `App Data Dir`, plus the snapshots and this experiment's output directory in this Session's scratchpad (`<agent_id>` and `<session_id>` are your own):

PROJECT_DIR  = <app_data_dir>
PROJECT_ID   = basename of PROJECT_DIR
PENGUIN_HOME = dirname of PROJECT_DIR
TARGET       = PROJECT_DIR/agents/<test_agent_id>
STATE        = TARGET/agent_state
BENCHMARK    = PROJECT_DIR/benchmarks/<benchmark_id>
SCOREBOARD   = BENCHMARK/scoreboard.yaml
SNAPSHOTS    = TARGET/snapshots
OUT          = <app_data_dir>/agents/<agent_id>/scratchpad/<session_id>/opro-rsi-toolkit/<experiment_id>/

`experiment_id` is `<UTC timestamp>-<test_agent_id>`. Before the first measurement, write `OUT/experiment.yaml`:

method: OPRO
paper: Large Language Models as Optimizers (Yang et al., 2023)
arxiv_url: https://arxiv.org/abs/2309.03409
github_url: https://github.com/google-deepmind/opro
source_revision: a76bdce2cbf6d4a0d1e570a6fcfe17be9c2abdd7
skill: { name: opro-rsi-toolkit, version: <installed version>, sha256: <SKILL.md digest> }
test_agent_id: <id>
benchmark_id: <id>
case_ids: [<case ids>]
runs: <runs>
runtime: { target: { provider, model_id, thinking_level }, proposer: { provider, model_id } }
parameters: { <every parameter above as used, with the exemplar seeds> }
state: { initial_version, instruction_sha256, skill_sha256, reader_sha256 }
artifact: skills/opro-instruction/instruction.md in the Target's Agent State
source: the Benchmark's training cases
feedback: the proposer sees instructions with their scores and sampled public statements; never a Rubric, a Trace, or an answer that was not authorized
updater: proposer calls on this Session's model; this Session alone publishes a State
frequency: P proposals per step, all against one history snapshot
topology: population (the scored history)
selection: highest training score; an exact tie keeps the earliest
mode: offline, training cases only
scope: the Benchmark's task
adaptations: [<each departure and its reason>]

Keep in OUT, append-only: every meta-prompt and raw proposer reply, every parsed instruction with its version or the reason it was skipped, every measurement with its cells and Session ids, and every failure.

**Versions and snapshots.** A new State version is one more than the highest of the current `version`, every `SNAPSHOTS/v<N>.tar.gz`, and every version the scoreboard records for the Target; versions only increase, and a measured or abandoned number is never reused. Snapshot each State b