gepa-optimize-anything
Automatically improve any text artifact that can be scored — prompts, programs/code, configs, specs, regex/SQL/schemas, agent scaffolds, or encoded search solutions — with optimize_anything, an LLM-driven optimization API: a search backend repeatedly proposes better versions from execution feedback…
Install / Use
npx skills add gepa-ai/gepa --skill gepa-optimize-anythingInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Our assessment of gepa-optimize-anything
gepa-optimize-anything scores 95/100 on our quality scale, 307th of 2,790 Automation skills we index (top 12%).
Its SKILL.md is 18 KB long, well organised into 22 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
With 7,424 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated 7 days ago, so gepa-optimize-anything is actively maintained.
- Our last check on 2026-11-15 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
ReviewOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below). An AI review judged it risky: Line 97 tells the agent to run `curl -fsSL https://claude.ai/install.sh | bash` to install the Claude CLI.
- noteInstalls by piping a downloaded script into a shellline 97
npm install -g @anthropic-ai/claude-code # or: curl -fsSL https://claude.ai/install.sh | bash
AI review: risky
- Line 97 tells the agent to run `curl -fsSL https://claude.ai/install.sh | bash` to install the Claude CLI.
- Because this is a skill/rules file, that command is an instruction the agent would follow, and piping a remote script into a shell weakens safety.
- The rest of the file is a legitimate guide to using the `gepa` optimization library (pip/npm installs, API keys, sandboxing notes) and is not malicious.
AI review by kimi-k2.7-code on 2026-11-16. Automated pattern scan on 2026-11-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
gepa-optimize-anything compared with similar skills
All 4 of these similar skills score higher than gepa-optimize-anything; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| gepa-optimize-anything (this skill)by gepa-ai | 95 | 7.4k | 7d ago | SKILL.md |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
Frequently asked questions
- How do I install gepa-optimize-anything?
- Run
npx skills add gepa-ai/gepa --skill gepa-optimize-anything. The install tabs above show the steps for each supported agent. - Which AI agents does gepa-optimize-anything work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is gepa-optimize-anything safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below). An AI review judged it risky: Line 97 tells the agent to run
curl -fsSL https://claude.ai/install.sh | bashto install the Claude CLI. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand. - Is gepa-optimize-anything still maintained?
- The repository was last updated 7 days ago, so gepa-optimize-anything is actively maintained.
Skill content
View source on GitHubname: gepa-optimize-anything description: >- Automatically improve any text artifact that can be scored — prompts, programs/code, configs, specs, regex/SQL/schemas, agent scaffolds, or encoded search solutions — with optimize_anything, an LLM-driven optimization API: a search backend repeatedly proposes better versions from execution feedback and an evaluator you provide assigns the score (an objective metric or an LLM-as-judge for subjective tasks). optimize_anything is one interface across several optimizer backends — GEPA (reflective evolutionary search, the default), AutoResearch, MetaHarness — plus a best-of-N baseline: write the evaluator once and switch backend with a single argument. Use whenever a task needs auto-optimizing, tuning, or searching over text with any quality signal (accuracy, pass rate, latency, cost, judge rating); when building an evaluator + proposer loop; when running GEPA; or when comparing optimizers. The candidate can be any string an evaluator can grade, scored on one problem or generalized across many.
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.
What can be a candidate
A candidate is any string your evaluator can score. "Text in → a number out (higher is better), plus optional feedback" is the entire contract, which covers a wide range of artifacts:
- prompts — system/user prompts, instruction templates, rubrics, few-shot exemplars
- programs / code — functions, whole files, CUDA kernels, scored by compiling + running + benchmarking
- configs / specs / schemas / regex / SQL — any text whose effect you can measure
- agent scaffolds — tool instructions, planner/critic prompts, orchestration text
- pure search artifacts — a mathematical construction, a packing layout, a plan, encoded as text
The score can be an objective metric (accuracy, pass rate, runtime, cost) or an LLM-as-judge
rating for subjective tasks (writing quality, helpfulness, style). At this API the candidate is a
single string (seed_candidate: str | None; None = seedless — the engine bootstraps from
objective/background). Multi-component dict candidates exist only in the lower-level
gepa.gepa_launcher.optimize_anything API, not here.
Three optimization modes (choose by how you pass data)
The mode is determined by whether you provide dataset and valset:
- Single-task (
dataset=None, valset=None) — solve one hard problem; the candidate is the solution; the evaluator is called with no example. E.g. one CUDA kernel, a circle-packing layout. - Multi-task (
dataset=<list>, valset=None) — solve a batch of related problems with one shared candidate, transferring insight across them; evaluator called per example. E.g. a single prompt that works across many tasks. - Generalization (
dataset=<list>, valset=<list>) — build a candidate that transfers to unseen problems; optimize ondataset, select onvalset. E.g. a prompt tuned to generalize. Note: GEPA is the algorithm designed around this mode, andvalset-based held-out selection is currently implemented only by the gepa backend — the other backends foldvalsetinto the training pool (they can still generalize; there's just no separate selection split).
test_set is separate from the modes and reporting-only: the seed and the final candidate are
scored on it after optimization for an unbiased number — it never enters the search, selection, or
budget (for the agentic backends it is sealed at the eval server's HTTP layer, so the agent cannot
even see it). See references/api.md for details and when to use each mode.
Install
pip install "gepa[full]" # [full] pulls cloudpickle — needed to pickle closure evaluators for
# parallel workers / opt-in evaluation caching; plain `pip install gepa`
# can fail there when your evaluator closes over data.
# Proposer LLM: the gepa backend's reflection LM defaults to "openai/gpt-5.1" (a LiteLLM id) — set
# that provider's key (OPENAI_API_KEY), or pass your own id (e.g. "anthropic/claude-sonnet-4-6" with
# ANTHROPIC_API_KEY, or a Bedrock ARN with AWS creds). You can also pass any callable implementing
# GEPA's LM protocol — a self-hosted / custom inference engine — instead of a model-id string.
# Agentic backends (autoresearch, meta_harness) additionally need the `claude` CLI on PATH (plus
# `jq` for the generated eval.sh):
npm install -g @anthropic-ai/claude-code # or: curl -fsSL https://claude.ai/install.sh | bash
# ...then run `claude` once to authenticate.
# On Linux they also need bubblewrap: the default sandbox=True jails the claude subprocess with
# bwrap (`sudo apt install bubblewrap` / `sudo dnf install bubblewrap`) and the run aborts at
# launch if it's missing. sandbox=False opts out — the agent then runs unsandboxed (loud warning).
Mental model (4 pieces)
- Candidate — the text you optimize (a
str). The seed is the start;None= seedless. evaluate(candidate, example) -> (score, info)—scoreis a float (higher is better);infois a free-form dict of feedback the backend's proposer reads to make better candidates (the gepa backend's reflection LM, or the agentic backends' agent; thebest_of_nbaseline ignores feedback). When evals batch better than they stream (e.g. a provider batch API), passbatch_evaluator=instead — all pending(candidate, example)pairs in one call; seereferences/api.md.- Engine (backend) —
"gepa"(default),"autoresearch","meta_harness", the"best_of_n"baseline, or a constructedEngineinstance. - Budget —
max_evals(server-side eval-call cap, default 100) and/ormax_token_cost(USD cap on the backend's own proposer-LLM spend). Setting both toNonemakes the run unbounded (only a warning). Sizemax_evalsfor many proposal rounds, not one (see below) — this is the most common way agents misuse this API.
Sizing the valset and the budget (read this — the #1 mistake)
max_evals is the main control over how long the optimizer runs. Leave it at the default (100)
with a large valset, or set it too low, and the run stops after a single proposal, then reports
a "best candidate" that looks fine but is barely optimized.
- valset — on the gepa backend the best candidate is selected by its scores on the valset, so make it a representative subset of your data. There is no fixed size: pick what represents the task (a handful for small/expensive tasks, more when data is cheap and plentiful — anywhere from a few to hundreds). Bigger valset = less noisy selection but more eval calls per candidate.
- budget — every proposed candidate is scored on the whole selection set, so size
max_evalsoff that set, not off a single proposal. Which set that is depends on the mode:
The constant is the same everywhere — let the backend propose AND evaluate ~15–20 candidates (more if you can afford it). Anything much less and the run tries only a couple of candidates — i.e. it's barely optimizing. (This arithmetic is exact for the gepa backend — and the best_of_n baseline — which score every candidate on the full selection set; the agentic backends decide themselves how to spend eval calls, so treat it as a floor.)generalization (dataset + valset): max_evals ≳ 15–20 × len(valset) # scored & selected on valset multi-task (dataset only): max_evals ≳ 15–20 × len(dataset) # scored & selected on dataset single-task (no dataset/valset): max_evals ≳ 15–20 # 1 eval per candidate, so this # IS the number of proposals
After the run, check how many proposals actually happened (on the gepa backend,
result.candidates is the full pool; with engine.write_agent_state=True the
run_dir/iterations/ tree shows each one). If it stopped after one proposal, the budget was too
low — raise it and rerun.
Give every run a real stop condition
max_evals bounds eval calls, but add explicit stops so runs end at the right moment:
stop_at_score— set it whenever your metric has a known ceiling (e.g.1.0for a pass rate / accuracy). The backend stops the moment a candidate reaches it instead of burning the rest of the budget at the optimum.max_token_cost— a hard USD cap on the backend's own proposer/agent LLM spend. Especially important for the agentic backends (autoresearch,meta_harness), whose Claude subprocesses spend tokens between eval calls.- a wall-clock
timeouton the process you launch (e.g.timeout 1200 python run.py) as a backstop. - If you opt in to evaluation caching (
engine_config={"engine": {"cache_evaluation": True}}on the gepa backend — it is off by default), be awaremax_evalsthen counts only cache misses: a converged search can keep proposing cache-hitting candidates without consuming eval budget, sostop_at_score/max_token_costbecome mandatory, not optional. A distinctvalsetis cached separately from the trainset;valset=Nonestill reuses minibatch rollouts.
Minimal working example
The example optimizes a system prompt for concreteness, but the shape is identical for any
candidate — swap SEED for a code file / config / etc. and have evaluate compile/run/measure it.
``
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
