SkillAgentSearch skills...

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-anything

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

95/100

Category

Automation

Supported Platforms

Universal

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.

Substance
30/30
Structure
18/20
Description
15/15
Adoption
16/20
Freshness
15/15

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

Review

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 | 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.

SkillScoreStarsUpdatedFormat
gepa-optimize-anything (this skill)by gepa-ai957.4k7d agoSKILL.md
claude-memby thedotmack100117.6ktodayCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.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 | bash to 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.

name: 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:

  1. 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.
  2. 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.
  3. Generalization (dataset=<list>, valset=<list>) — build a candidate that transfers to unseen problems; optimize on dataset, select on valset. E.g. a prompt tuned to generalize. Note: GEPA is the algorithm designed around this mode, and valset-based held-out selection is currently implemented only by the gepa backend — the other backends fold valset into 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)

  1. Candidate — the text you optimize (a str). The seed is the start; None = seedless.
  2. evaluate(candidate, example) -> (score, info) — score is a float (higher is better); info is 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; the best_of_n baseline ignores feedback). When evals batch better than they stream (e.g. a provider batch API), pass batch_evaluator= instead — all pending (candidate, example) pairs in one call; see references/api.md.
  3. Engine (backend) — "gepa" (default), "autoresearch", "meta_harness", the "best_of_n" baseline, or a constructed Engine instance.
  4. Budget — max_evals (server-side eval-call cap, default 100) and/or max_token_cost (USD cap on the backend's own proposer-LLM spend). Setting both to None makes the run unbounded (only a warning). Size max_evals for 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_evals off that set, not off a single proposal. Which set that is depends on the mode:
    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
    
    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.)

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.0 for 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 timeout on 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 aware max_evals then counts only cache misses: a converged search can keep proposing cache-hitting candidates without consuming eval budget, so stop_at_score/max_token_cost become mandatory, not optional. A distinct valset is cached separately from the trainset; valset=None still 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

View on GitHub
GitHub Stars7.4k
CategoryAutomation
Updated7d ago
Forks621

Languages

Jupyter Notebook

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions