EvoSkill

┌──────────────────────────────────────────────────────────────────┐
│              EvoSkill: Evolutionary Skill Discovery               │
│                                                                   │
│  Input: Coding agent + benchmark dataset + scoring function       │
│  Output: Optimized skill library (structured skill folders)       │
│                                                                   │
│  ┌────────────────────────────────────────────────────────┐       │
│  │  Iteration t                                           │       │
│  │                                                        │       │
│  │  1. SELECT parent program from frontier (round-robin)  │       │
│  │  2. EVALUATE parent on training batch                  │       │
│  │  3. COLLECT failures (score < threshold τ)             │       │
│  │  4. PROPOSE skill via failure analysis (Proposer)      │       │
│  │  5. BUILD skill folder (Skill-Builder)                 │       │
│  │  6. EVALUATE candidate on validation set               │       │
│  │  7. UPDATE frontier if candidate outperforms weakest   │       │
│  │  8. APPEND to feedback history                         │       │
│  │                                                        │       │
│  │  Repeat for T iterations                               │       │
│  └────────────────────────────────────────────────────────┘       │
│                                                                   │
│  Invariant: Underlying model is FROZEN throughout                 │
│  Output: Best program in frontier G                               │
└──────────────────────────────────────────────────────────────────┘

.claude/skills/data-extraction-verification/
├── SKILL.md          # Trigger metadata + procedural instructions
├── helpers/
│   ├── validate.py   # Helper scripts for verification
│   └── templates/    # Reference materials
└── examples/         # Usage examples (optional)

┌─────────────────────────────────────────────────────────────────┐
│                    Three-Agent System                             │
│                                                                  │
│  ┌──────────────┐                                                │
│  │  Executor (A) │  Executes tasks under current program         │
│  │               │  Read access to base repo                     │
│  │  Role: Worker │  No write access to skills                    │
│  └──────┬───────┘                                                │
│         │ Output traces, predicted answers                       │
│         ▼                                                        │
│  ┌──────────────┐                                                │
│  │  Proposer (P) │  Analyzes failures + ground truth             │
│  │               │  Reads feedback history H                     │
│  │  Role: Critic │  Proposes skill edits or new skills           │
│  │               │  Read access to base repo                     │
│  └──────┬───────┘                                                │
│         │ Textual proposal π                                     │
│         ▼                                                        │
│  ┌──────────────┐                                                │
│  │ Skill-Builder │  Materializes proposal into skill folder      │
│  │      (S)      │  Write access to skills directory             │
│  │               │  Bootstrapped with meta-skill for authoring   │
│  │  Role: Builder│  Read access to base repo                     │
│  └──────────────┘                                                │
│                                                                  │
│  Access Control:                                                 │
│  - All agents: READ access to base agent repository              │
│  - Only Skill-Builder: WRITE access to skills directory          │
│  - Proposer: maintains cumulative feedback history H             │
└─────────────────────────────────────────────────────────────────┘

# Default: Claude Opus
python scripts/run_loop.py --model opus

# Alternatives
python scripts/run_loop.py --model sonnet
python scripts/run_loop.py --model haiku

# Via OpenCode SDK with third-party models
python scripts/run_eval.py --sdk opencode --model deepseek-ai/DeepSeek-V3

H = [(proposal_1, score_1, verdict_1),
     (proposal_2, score_2, verdict_2),
     ...
     (proposal_t, score_t, verdict_t)]

# Install
uv sync  # or pip install -e .

# Set API key
export ANTHROPIC_API_KEY=your-key-here

# Run the evolutionary loop on OfficeQA
python scripts/run_loop.py --mode skill_only --max-iterations 20

# Run the evolutionary loop on SealQA
python scripts/run_loop_sealqa.py --mode skill_only --max-iterations 20

# Evaluate a configuration
python scripts/run_eval.py --model opus --max-concurrent 8

from src.api import EvoSkill

# Run the full self-improvement loop
result = await EvoSkill(
    task="sealqa",
    model="opus",
    mode="skill_only",
    max_iterations=20,
    frontier_size=3,
    concurrency=4,
    train_ratio=0.18,
    val_ratio=0.12,
).run()

main (base agent)
├── evo/iter-1/candidate-1    (+ data-extraction-verification skill)
├── evo/iter-2/candidate-1    (+ quantitative-analysis skill)
├── evo/iter-3/candidate-1    (rejected — score decreased)
└── evo/iter-4/candidate-1    (+ search-persistence-protocol)

Cost per iteration ≈ 
    Cost(Executor on training batch)      [most expensive]
  + Cost(Proposer analyzing failures)     [moderate]
  + Cost(Skill-Builder creating skill)    [moderate]
  + Cost(Executor on validation set)      [most expensive]

┌───────────────────────────────────────────────────────────────────────┐
│                      EvoSkill System Architecture                      │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                     Data Layer                                    │  │
│  │                                                                   │  │
│  │  Dataset D = {(x_i, y_i)}    LLM Classifier     Stratified       │  │
│  │  ┌───────────────┐          ┌──────────┐        Partitions       │  │
│  │  │ Raw benchmark │──────────│ Cluster  │───────► Train / Val /   │  │
│  │  │ questions     │  K cats  │ into K   │        Test splits      │  │
│  │  └───────────────┘          │categories│                          │  │
│  │                              └──────────┘                          │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                              │                                         │
│                              ▼                                         │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                     Evolution Layer                                │  │
│  │                                                                   │  │
│  │  Frontier G = {p_1, p_2, ..., p_k}  (top-k programs)            │  │
│  │                                                                   │  │
│  │  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐   │  │
│  │  │ Parent   │───►│ Evaluate │───►│ Collect  │───►│ Propose  │   │  │
│  │  │ Select   │    │ on Train │    │ Failures │    │ Skill    │   │  │
│  │  │(round-   │    │ Batch    │    │ (< τ)    │    │ Change   │   │  │
│  │  │ robin)   │    └──────────┘    └──────────┘    └────┬─────┘   │  │
│  │  └──────────┘                                         │          │  │
│  │       ▲                                               ▼          │  │
│  │       │         ┌──────────┐    ┌──────────┐    ┌──────────┐   │  │
│  │       │         │ Update   │◄───│ Evaluate │◄───│ Build    │   │  │
│  │       └─────────│ Frontier │    │ on Val   │    │ Skill    │   │  │
│  │                 │ (if      │    │ Set      │    │ Folder   │   │  │
│  │                 │ better)  │    └──────────┘    └──────────┘   │  │
│  │                 └──────────┘                                    │  │
│  │                                                                   │  │
│  │  Feedback History H: [(π_1,s_1), (π_2,s_2), ..., (π_t,s_t)]    │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                              │                                         │
│                              ▼                                         │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                     Storage Layer                                 │  │
│  │                                                                   │
│  │  Git Repository (fixed codebase)                                  │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐                 │  │
│  │  │ main       │  │ program    │  │ program    │                 │  │
│  │  │ (base)     │  │ branch 1   │  │ branch 2   │                 │  │
│  │  │            │  │ + skills   │  │ + skills   │                 │  │
│  │  │            │  │ + metadata │  │ + metadata │                 │  │
│  │  └────────────┘  └────────────┘  └────────────┘                 │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘

# Simplified pseudocode from Algorithm 1
H = []                    # feedback history
G = {base_agent}          # frontier (initially just base)
s_base = evaluate(A, V)   # baseline score

for t in range(T):
    # Round-robin parent selection
    parent = G[t % len(G)]

    # Collect failures
    failures = collect_failures(parent, train_batch, threshold=τ)
    if not failures:
        continue

    # Propose skill change
    proposal = proposer(failures, H)

    # Build candidate
    candidate = skill_builder(parent, proposal)

    # Evaluate
    score = evaluate(candidate, validation_set)

    # Frontier update
    if len(G) < k or score > min(G.scores):
        G.add(candidate)
        if len(G) > k:
            G.remove(worst)

    # Record history
    H.append((proposal, score))

return best(G)

src/agent_profiles/
├── __init__.py
├── base_agent/
│   ├── __init__.py
│   ├── base_agent.py      # Default agent options
│   └── prompt.txt          # Base system prompt
├── sealqa_agent/
│   ├── __init__.py
│   ├── sealqa_agent.py    # SealQA-specific options
│   └── prompt.txt          # SealQA system prompt
└── dabstep_agent/
    └── ...

# Scoring interface
def score(question: str, predicted: str, ground_truth: str) -> float:
    """Return score in [0.0, 1.0]."""
    ...

Git branch structure:
  main                          # Fixed codebase
  ├── evo/base                  # Base program (no skills)
  ├── evo/iter-1/candidate-0    # First evolved program
  ├── evo/iter-2/candidate-0    # Second evolved program
  └── evo/iter-N/candidate-0    # N-th evolved program

Each branch contains:
  .claude/skills/               # Accumulated skill folders
  .agent-metadata.json          # System prompt, lineage, score

Maintain frontier of top-k candidates
Each iteration:
  1. Select candidate from frontier
  2. Evaluate candidate → get textual feedback
  3. Editor LLM uses feedback to produce improved candidate
  4. New candidate enters frontier if better

Maintain frontier of top-k PROGRAMS (agent + skills)
Each iteration:
  1. Select program from frontier (round-robin)
  2. Execute program on tasks → collect FAILURE TRACES
  3. Proposer LLM diagnoses failures → produces SKILL PROPOSAL
  4. Skill-Builder LLM materializes proposal → SKILL FOLDER
  5. New program enters frontier if validation score improves

Input to Proposer:
  - Execution traces (full agent conversation for each failed question)
  - Predicted answers (what the agent output)
  - Ground-truth answers (correct answers for diagnosis)
  - Feedback history H (all prior proposals and outcomes)

Proposer Analysis Steps:
  1. Review execution traces to identify WHERE the agent went wrong
  2. Classify failure mode:
     - Data extraction error (wrong cell, wrong metric)
     - Reasoning error (incorrect computation, wrong formula)
     - Search error (premature termination, missed source)
     - Comprehension error (misunderstood question intent)
  3. Check existing skills: is there a skill that SHOULD have prevented this?
     - If yes: propose EDIT to strengthen that skill
     - If no: propose NEW skill to address the gap
  4. Consult history H: has a similar proposal been tried before?
     - If tried and failed: propose different approach
     - If tried and partially worked: propose refinement
  5. Output: structured proposal π specifying skill name, trigger,
     instructions, and rationale

Frontier G = {p_1, p_2, ..., p_k}  where k = frontier_size (default: 3)

Selection: round-robin cycling
  Iteration 1: parent = G[0]
  Iteration 2: parent = G[1]
  Iteration 3: parent = G[2]
  Iteration 4: parent = G[0]  (cycle restarts)
  ...

This ensures:
  - Every frontier member gets explored before any is revisited
  - No single program dominates the mutation budget
  - Diverse exploration starting points

Replacement: score-based
  if candidate_score > min(G.scores):
    G.add(candidate)
    if len(G) > k:
      G.remove(argmin(G.scores))

Iteration 0: program_0 = {system_prompt}
Iteration 1: program_1 = {system_prompt, skill_A}
Iteration 3: program_3 = {system_prompt, skill_A, skill_B}
Iteration 7: program_7 = {system_prompt, skill_A, skill_B (edited), skill_C}

Run 1 (5% train):  discovers skills {A, B, C}
Run 2 (10% train): discovers skills {B', D, E}
Run 3 (15% train): discovers skills {A', E', F}

Merge strategy:
  1. Identify unique skills by name/description
  2. For overlapping skills (B/B', A/A', E/E'):
     keep version from highest-scoring run
  3. Result: merged library {A', B, C, D, E, F}

Dataset D → LLM Classifier → K categories
  Category 1: questions about debt instruments
  Category 2: questions about revenue figures
  Category 3: questions about cross-document comparison
  ...

Stratified split ensures:
  - Every category appears in train, val, and test
  - Evolution sees diverse failure modes (not just one category)
  - Validation is representative of the full distribution

EvoSkill/
├── src/
│   ├── api.py              # High-level Python API
│   ├── loop/               # Self-improving loop implementation
│   ├── agent_profiles/     # Per-task agent configurations
│   │   ├── base_agent/
│   │   ├── sealqa_agent/
│   │   └── dabstep_agent/
│   ├── evaluation/         # Scoring functions
│   │   ├── eval_full.py    # Full evaluation runner
│   │   ├── sealqa_scorer.py
│   │   └── multi_tolerance.py
│   ├── prompts/            # Proposer/Builder prompt templates
│   ├── schemas.py          # Pydantic data models
│   ├── frontier.py         # Git-based frontier management
│   └── data/               # Dataset splitting utilities
├── scripts/
│   ├── run_loop.py         # CLI: run evolution loop
│   ├── run_loop_sealqa.py  # CLI: run SealQA loop
│   ├── run_eval.py         # CLI: run evaluation
│   └── run_eval_sealqa.py  # CLI: run SealQA eval
├── .dataset/               # Benchmark data (user-provided)
├── .claude/skills/         # Evolved skill folders (output)
├── pyproject.toml          # Package configuration
└── uv.lock                 # Dependency lock file

# Async (recommended)
result = await EvoSkill(task="sealqa").run()

# Sync (convenience wrapper)
result = EvoSkill(task="sealqa").run_sync()

# Evaluation only
summary = await EvalRunner(task="sealqa", model="sonnet").run()

# Task registration
register_task(TaskConfig(
    name="my_task",
    make_agent_options=my_options_factory,
    scorer=my_scorer,
    default_dataset=".dataset/my_data.csv",
))

Context budget:
  System prompt:                    ~2K tokens
  Skill triggers (all skills):     ~500 tokens × N_skills
  Active skill (on demand):        ~2K-5K tokens per skill
  Task question:                   ~1K-10K tokens
  Tool outputs:                    ~5K-50K tokens (document content)
  Agent reasoning:                 ~5K-20K tokens

Total: ~15K-80K tokens per question

Context budget:
  System prompt + instructions:    ~3K tokens
  Failure traces (N failures):     ~5K-20K tokens per failure
  Ground-truth answers:            ~500 tokens per failure
  Feedback history H:              ~1K-5K tokens (growing)
  Existing skill inventory:        ~1K-3K tokens

Total: ~20K-100K tokens per iteration

Context budget:
  Meta-skill (authoring guidelines): ~3K tokens
  Parent program metadata:           ~1K tokens
  Proposal π:                        ~2K-5K tokens
  Base repository context:           ~5K-10K tokens

Total: ~10K-20K tokens per skill construction

Startup: Load ALL skill triggers
  ┌────────────────────────────────────┐
  │ data-extraction-verification       │  ~50 tokens
  │ trigger: "extracting table data"   │
  ├────────────────────────────────────┤
  │ quantitative-analysis             │  ~50 tokens
  │ trigger: "financial calculation"   │
  ├────────────────────────────────────┤
  │ search-persistence-protocol        │  ~50 tokens
  │ trigger: "searching for answers"   │
  └────────────────────────────────────┘
  Total: ~150 tokens for 3 skills

Activation: Load ONLY matching skill
  ┌────────────────────────────────────┐
  │ data-extraction-verification       │
  │ [Full SKILL.md: ~2000 tokens]     │
  │ [Helper scripts: executed, not    │
  │  loaded into context]             │
  └────────────────────────────────────┘
  Total: ~2000 tokens (one skill)

After 20 iterations:
  H ≈ 20 × (proposal summary + score + verdict)
    ≈ 20 × 200 tokens
    ≈ 4000 tokens

After 100 iterations:
  H ≈ 100 × 200 tokens
    ≈ 20,000 tokens

Evolution trajectory (OfficeQA example):

Iteration 0:  Base agent (60.6% accuracy)
              Skills: {}

Iteration 3:  +data-extraction-verification
              Skills: {DEV}
              Accuracy: 63.4%

Iteration 7:  +quantitative-analysis-methodology
              Skills: {DEV, QAM}
              Accuracy: 65.8%

Iteration 12: Refined DEV (strengthened table parsing rules)
              Skills: {DEV', QAM}
              Accuracy: 67.9%

Independent runs on same task → merge unique skills
Result: 67.9% > 65.8% (best individual)

SealQA skill → BrowseComp (no modification)
Result: 43.5% → 48.8% (+5.3%)

Skills evolved with Opus → applied with Sonnet/Haiku
Architecturally supported (skills are model-agnostic text)
Empirical validation is future work

Workflow:
  1. Define a benchmark dataset with (question, ground_truth) pairs
  2. Implement a scoring function
  3. Run EvoSkill's evolutionary loop
  4. Deploy discovered skills to production agents

Result: Domain-specialized agent without fine-tuning or manual skill authoring

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│  Evolutionary Optimization          Agent Skill Ecosystem    │
│  (AlphaEvolve, GEPA,       ←────►  (Claude Code Skills,    │
│   FunSearch, OpenELM)               Codex Skills, ROMA)     │
│         │                                    │               │
│         └──────────────┬─────────────────────┘               │
│                        │                                     │
│                        ▼                                     │
│              ┌─────────────────┐                             │
│              │    EvoSkill     │                              │
│              │                 │                              │
│              │  Evolutionary   │                              │
│              │  optimization   │                              │
│              │  OF agent       │                              │
│              │  skills         │                              │
│              └─────────────────┘                              │
│                        │                                     │
│                        ▼                                     │
│              Transferable, interpretable                     │
│              capability improvements                         │
│              WITHOUT model modification                      │
│                                                              │
└──────────────────────────────────────────────────────────────┘

@misc{alzubi2026evoskill,
  title={EvoSkill: Automated Skill Discovery for Multi-Agent Systems},
  author={Salaheddin Alzubi and Noah Provenzano and Jaydon Bingham 
          and Weiyuan Chen and Tu Vu},
  year={2026},
  eprint={2603.02766},
  archivePrefix={arXiv},
  primaryClass={cs.AI},
  url={https://arxiv.org/abs/2603.02766},
}

@misc{alzubi2026roma,
  title={ROMA: Recursive Open Meta-Agent Framework for Long-Horizon 
         Multi-Agent Systems},
  author={Salaheddin Al Zu'bi and Bala Nama and Ashish Kaz 
          and Aditya Eswaran and Weiyuan Chen and Shantanu Khetan 
          and Rajat Bala and Tu Vu and Samuel Oh},
  year={2026},
  eprint={2602.01848},
  archivePrefix={arXiv},
  primaryClass={cs.AI},
  url={https://arxiv.org/abs/2602.01848},
}

@misc{lee2025feedbackdescent,
  title={Feedback Descent: Open-Ended Text Optimization via 
         Pairwise Comparison},
  author={Yoonsang Lee and Jarett Boen and Chelsea Finn},
  year={2025},
  eprint={2511.07919},
  archivePrefix={arXiv},
  url={https://arxiv.org/abs/2511.07919},
}