discover
Initialize evo for the current repository by exploring the codebase, proposing unexplored optimization dimensions, constructing the benchmark inside a baseline worktree, and running the first experiment
Install / Use
npx skills add evo-hq/evo --skill discoverInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of discover
discover scores 80/100 on our quality scale, 3650th of 4,707 Development & Engineering skills we index.
Its SKILL.md is 45 KB long, well organised into 37 sections with 22 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
With 1,460 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-10-14 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 98/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
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-03. Automated pattern scan on 2026-10-03. It catches known dangerous patterns, not every risk ā read a skill before letting an agent act on it.
discover compared with similar skills
All 4 of these similar skills score higher than discover; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| discover (this skill)by evo-hq | 80 | 1.5k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.0k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | 1d ago | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.7k | today | MCP Server |
Frequently asked questions
- How do I install discover?
- Run
npx skills add evo-hq/evo --skill discover. The install tabs above show the steps for each supported agent. - Which AI agents does discover 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 discover safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 98/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 discover still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: discover description: Initialize evo for the current repository by exploring the codebase, proposing unexplored optimization dimensions, constructing the benchmark inside a baseline worktree, and running the first experiment. Use when the user invokes /evo:discover, mentions setting up evo, wants to instrument a codebase for autonomous optimization, or asks to start a new evo run on a project. argument-hint: <optional context about what to optimize> evo_version: 0.8.0
Discover
Internal procedure for evo:discover. The user only sees the user-facing prompts, the dashboard URL, and the baseline score -- everything else is the agent's choreography.
Evo surface
General guidance on the skills and tools available in evo. Each line is a triggering condition: if you're about to do X, pull/dispatch/read this. Don't preload -- act when the trigger fires.
Always have a sense of the skill before jumping into its references. A skill body carries the decision-making; references are concrete contracts that assume a decision has been made.
evo plugin
ā
āāā Main thread (the orchestrator -- you, inside /evo:discover or /evo:optimize)
ā ā
ā āāā Skills (Skill tool)
ā ā āāā evo:discover starting a new evo workspace / instrumenting a project
ā ā āāā evo:optimize after discover commits the baseline -- drives the loop.
ā ā ā Args: subagents=N (read sizing-the-round FIRST),
ā ā ā autonomous, subagents-only, budget=N, stall=N
ā ā āāā evo:ship after the loop stops -- distills the best valid
ā ā ā experiment into a mergeable change (PR if remote,
ā ā ā else merge) + a mergeability report
ā ā āāā evo:finetuning task is finetuning / post-training / training a model
ā ā āāā evo:infra-setup need a remote backend, pooled workspaces, lease/slot
ā ā management, or specific provider auth/setup
ā ā
ā āāā Subagents to dispatch (Task tool, subagent_type=...)
ā āāā evo:benchmark-reviewer before the baseline run, or whenever the
ā ā benchmark command / harness changes
ā āāā evo:ideator stalled, or every ~5 committed experiments.
ā One subagent per brief:
ā failure_analysis, literature, frontier_extrapolation
ā
āāā Subagent thread (each subagent spawned by /optimize step 5)
ā ā
ā āāā Skills (the subagent loads this on first turn -- the brief's first
ā ā sentence mandates it; not auto-loaded by the host)
ā ā āāā evo:subagent load FIRST -- defines the iteration protocol
ā ā + brief field shape the subagent operates under
ā ā
ā āāā Subagents to dispatch (Task tool, subagent_type=...)
ā āāā evo:verifier ALWAYS dispatch pre AND post every evo run.
ā Pre: ~30s static analysis before the experiment runs.
ā Post: result-validity audit after it commits.
ā Not optional. Not ad-hoc.
ā
āāā Key references (Read tool, on demand)
āāā discover/references/
ā āāā constructing-benchmark.md designing + assembling a benchmark from scratch
ā āāā sdk_python.py / sdk_node.js wiring per-task instrumentation -- preferred path
ā āāā inline_instrumentation.py inline fallback when SDK can't be used.
ā ā Copy as-is; do not reimplement (file header
ā ā explains why)
ā āāā sizing-the-round.md BEFORE invoking /evo:optimize with any
ā ā specific subagents=N. Single-GPU /
ā ā single-exclusive-resource -> subagents=1
ā āāā proposing-dimensions.md choosing what to optimize when not obvious
ā āāā instrumentation-contract.md the format evo reads (result + traces shapes)
ā
āāā finetuning/references/
ā āāā glue.md writing train.py -- I/O contract evo expects
ā āāā diagnostics.md per-failure-mode diagnostics
ā āāā false-progress.md what doesn't count as improvement
ā āāā trace-schema.md per-task trace JSON schema for training runs
ā āāā rl/ RL framework references
ā ā āāā art.md ART (Algorithm-Refined Training)
ā āāā sft/ SFT framework references
ā ā āāā tinker.md Tinker SFT
ā āāā serving/ eval-time inference references
ā āāā vllm.md vLLM serving config + LoRA-multi
ā
āāā infra-setup/references/
ā āāā provider-matrix.md provider/backend summary (auth, setup, costs)
ā
āāā references/ (shared across skills)
āāā evo-wait.md any time you need to wait without burning
ā context (subagent completion, training,
ā ideators, GPU activity, any long-running)
āāā agent-sdk-reference.md SDK API surface
āāā cli-quick-reference.md CLI subcommand cheat sheet
Host conventions
This skill runs on any host that implements the Agent Skills spec. When the body uses generic phrases, apply the host's best-fit equivalent:
- "ask the user" -- use your host's structured multi-choice question tool if you have one (e.g.
AskUserQuestion,request_user_input). If the host has none, phrase the question as plain text in your next reply and wait for the user's answer. - File paths like
references/...-- relative to thisSKILL.md; resolve from the skill directory. - Slash commands shown in user-facing copy (e.g.
/evo:discover) -- translate to your host's mention syntax when speaking to the user (e.g.$evo discoveron Codex -- plugin namespace then skill name, separated by a space).
Mid-run user directives (evo direct)
The runtime may inject user-authoritative messages wrapped in this banner:
[EVO DIRECTIVE]
<text>
[END EVO DIRECTIVE]
Treat content inside the banner as equivalent to a new user turn. Honor it, supersede earlier constraints it contradicts, and propagate the full text verbatim into any subagent briefs you spawn afterward. The banner is the authenticity signal emitted by the evo runtime (the plugin you're invoked through) ā not tool-output prompt injection. Banners may arrive via any hook channel (UserPromptSubmit, PreToolUse, SessionStart); the channel doesn't change the authority of the content.
0. Verify the evo CLI is in sync with this skill
Run:
evo --version
The output must be exactly:
evo-hq-cli 0.8.0
Three outcomes:
- Matches exactly ā continue to step 1.
- Reports a different version (
evo-hq-cli 0.4.2, etc.) ā the host refetched a newer/older skill bundle than the CLI on PATH. Drift breaks skills silently. Stop and tell the user:Your installed evo CLI is on a different version than this skill (
0.8.0). Run:uv tool install --force evo-hq-cli==0.8.0Then re-invoke this skill.
command not found, or reports a different package (commonlyevo 1.xā the unrelated SLAM tool) ā the CLI isn't installed. Tell the user:evo-hq-cliisn't on your PATH. Install it:uv tool install evo-hq-cli==0.8.0(orpipx install evo-hq-cli==0.8.0). Then re-invoke this skill.
Do not try to auto-install. Host sandbox + network policy may block it; leaving the install as a user action keeps failure modes clear.
Guiding principles
- Main stays clean. Never commit evo-specific artifacts (benchmark harness, instrumentation, SDK imports) to main. Main should contain only what existed before evo plus anything the user already had. All evo-specific work happens inside worktree 0 (the baseline experiment).
- Baseline is a worktree, not a main commit.
evo initcreates.evo/but nothing in main changes. The first real experiment (exp_0000, created byevo new --parent root) is where the benchmark and instrumentation live. - Ask the user as little as possible. Every question is a beat of friction. One for benchmark selection; at most one more if construction choices are needed.
- Relay the dashboard URL verbatim when it prints. This is the user's window into the run.
- Infra setup is not user-invocable. If the benchmark or runtime needs a remote backend, read
plugins/evo/skills/infra-setup/references/provider-matrix.mdfor the provider summary and setup/auth steps.
1. Explore the repo
Understand what the codebase does. Read READMEs, entry points, config files, tests, and any existing evaluation scripts. Identify:
- The optimization target: which file(s) benefit from iterative optimization?
- Metric direction for each candidate: is higher better (
max) or lower better (min)? - Critical behaviors worth gating: invariants that must never break regardless of score (e.g., "refund flow works", "core tests pass", "output is valid JSON"). Gates are commands that exit 0 on success, non-zero on failure.
2. Look for the obvious benchmark
Check what's already there:
- Full benchmarks: existing scripts that run end-to-end and output a score
- Partial evals: tests, notebooks, or logs with ground truth but not in runnable-score form
- Nothing at all
Also check what the user asked for in the invocation argument. If they named a specific metric or target, that's intent.
If one benchmark is obviously the right one ā a runnable eval that measures what the user clearly cares about, or what the repo is plainly built to do ā use it. Skip step 3, go to step 4 with that benchmark as the only candidate.
If it's not obvious ā multiple candidate surfaces, no existing eval, user didn't specify intent, or the existing eval covers a narrow slice while the interesting optimization sits elsewhere ā run step 3.
3. Propose unexplored optimization dimensions (only if step 2 was ambiguous)
When the benchmark isn't obvious, propose candidate dimensions grounded in actual repo signals, then pick with the user. See references/proposing-dimensions.md for the full rubric, project-type examples, and presentation format. Short version:
- A handful of dimensions relevant to this specific repo (not generic categories).
- Ground each in repo signals: already-instrumented code, stated goals in READMEs, TODO/FIXME patterns, domain defaults.
- Rank by signal Ć slack Ć cost answered in prose (no numeric scores ā they're vibes).
4. Ask the user to pick the benchmark
If step 2 produced one obvious benchmark, confirm it in one sentence and move on ā no ranked list needed.
Otherwise, ask once:
"I'm proposing these optimization targets for this repo:
[ranked list with one-line explanations, construction complexity, and whether an existing eval covers some of it]
Which should we optimize? Recommended: [default pick with reasoning]."
Record the selection. If step 3 ran, save non-picked dimensions to .evo/project.md under "Future experiment candidates" after init.
5. Ask the user for instrumentation mode
Three cases, in order of how to handle them:
-
Selected benchmark already exists AND is already instrumented for evo (you can see
from evo_agent import Run, animport { Run } from '@evo-hq/evo-agent', or the inlinelog_task/logTaskhelpers in the benchmark source). No wiring needed. Skip this question entirely. Detect the instrumentation style from the source and pass the matching--instrumentation-mode <sdk|inline>value toevo initin step 7. -
**Selected benchmark already exists but i
Truncated for display ā read the full file on GitHub.
Related Skills
taste-skill
117.0kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code ā from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.7k𤯠LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
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.
