gepa: Skill for Claude Code

optimize_anything

Naming, precisely. optimize_anything is the tool: a general API for optimizing text artifacts. GEPA is one specific optimizer behind it — reflective evolutionary search, the default backend (engine="gepa") — and, for legacy reasons, also the name of the Python package that ships all of this. In this skill, "the gepa backend" always means the optimizer; statements about "the optimizer" or "the backend" apply to whichever engine you chose.

optimize_anything does black-box optimization: you provide (1) a seed artifact, (2) an evaluator that scores any artifact and returns feedback, and (3) a backend, which repeatedly proposes improved artifacts and scores them through your evaluator. "Black-box" refers to the evaluator, not the artifact: the backend never sees how the score is computed — no gradients, no metric internals — only the scalar score and the feedback text you emit. The candidate itself is visible: the proposer reads and rewrites it, applying the LLM's understanding of your artifact. The framework just imposes no structure on it — any string an evaluator can score works. The leverage is in your score and your feedback.

You write the task and evaluator once, then choose the search algorithm with one engine argument — and the same code runs under any of them:

• gepa — the GEPA optimizer: reflective evolutionary search, in-process (an LLM reflects on feedback and mutates candidates; keeps a Pareto frontier). The default; strongest when feedback is rich.
• autoresearch — an agentic optimizer: one Claude Code subprocess iterates like a researcher in a work dir, scoring candidates through an HTTP eval server.
• meta_harness — an agentic proposer (Claude subprocess) that reads the frontier/history each iteration and writes new candidates for the engine to benchmark.

(There is also a best_of_n engine — sample N independent candidates, keep the best. It is deliberately naive: use it as a baseline to compare an optimizer against, not as the optimizer.)

This makes it easy to start with one backend and benchmark others on the identical task/evaluator. There are also composition/pipeline helpers that combine backends over the same task: optimize_sequential (a pipeline — each stage's best seeds the next), optimize_parallel, optimize_best_of, optimize_vote (re-score each branch's best for a fair pick), and an adaptive scheduler that rotates backends on score plateaus — see references/api.md.