skill-evolution

Evolve Agent Skills (SKILL.md) through a contrastive loop with a held-out gate.

Portable CLI for improving your skill tonight — not a SkillOpt-scale trainer. Inspired by SkillEvolver and EmbodiSkill. The 0.2 loop also takes the validation gate from SkillOpt, first-class DELETE/DEMOTE from SkillProx, and the Agent Skills directory format.

How It Works

          ┌─────────────┐
          │ Initial Skill│
          └──────┬───────┘
                 │
    ┌────────────▼────────────┐
    │  1. Strategy Explorer    │  Generate K diverse approaches
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │  2. Task Executor        │  Run each strategy; optional scripts/
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │  3. External Evaluator   │  Task keywords / patterns (no self-grade)
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │  4. Trajectory Comparator│  Success vs failure → delta signals
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │  5. Skill Patcher        │  ADD / REFINE / DEMOTE / DELETE
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │  6. Auditor + held-out   │  SkillJack provenance, shrinkage, gate
    └────────────┬────────────┘
                 │
          ┌──────▼───────┐
          │ Evolved Skill │──── repeat for R rounds
          └──────────────┘

Key design principles:

• Contrastive updates: signals come from successful vs failed trajectories
• Scorable tasks: an empty KeywordEvaluator is refused (it would mark every run SUCCESS)
• Held-out gate: train patches that drop held-out scores are rolled back (SkillOpt)
• Shrinkage: DELETE/DEMOTE are first-class; growth-only patches are a defect (SkillProx)
• Independent audit: overfitting, silent bypass, provenance / SkillJack

Quick Start

Install

pip install skill-evolution

Or for development (reproducible lock used by CI):

git clone https://github.com/victorzhong0110/skill-evolution.git
cd skill-evolution
pip install -r requirements-dev.txt
pip install -e . --no-deps

pip install -e ".[dev]" still works; versions then float within the ranges in pyproject.toml.