Add demo and implementation: an agent that writes its own skill

[evekhm]

What

A runnable, self-contained example — examples/skill_evolution_lab/ — of an agent that rewrites its own versioned SKILL.md from its conversation traces, with no teacher model, plus the reusable engine that powers it (scripts/skill_evolution.py).

A company-policy Q&A agent ships with a deliberately flawed V0 skill ("answer only from the baked summary, else contact HR") that suppresses a tool which already knows every answer. The engine reads the scored traces — successes and failures — and evolves a tool-first V1. Same model, same tool, same questions across V0/V1, so any quality delta is attributable to the skill.

Contents

• scripts/skill_evolution.py — the evolution engine. Partitions scored conversations into successes/failures, runs a parallel analyst fleet (one analyst per trajectory, each on a frozen copy of the skill), and consolidates recurring rules into a new version (best-of-N, size compaction, anti-parroting reclassification). Standalone — consumes a scored report dict and returns skill text, so it composes with the scorer without importing it.
• examples/skill_evolution_lab/ — the agent (agent/), a golden-Q&A eval spec (eval/eval_spec.json), evolve + disjoint held-out question sets, a one-command run_e2e_demo.sh, a committed sample_run/, DEMO_NARRATION.md, and VERIFICATION.md.
• tests/test_skill_evolution.py — 19 engine unit tests.
• examples/README.md — a "Skill Evolution Lab" section.

Verified

gemini-3-flash-preview, golden-grounded, on a held-out set (see VERIFICATION.md):

Metric	V0 (flawed)	V1 (evolved)
Overall correctness	23.8%	100%
Corrections (anti-parroting)	33.3%	100%

Evolved skill: ~2.5KB, tool-first, with a learned "when corrected, re-verify with a tool — don't just agree" rule.

Dependency / draft status

Draft: the demo's scorer step (run_e2e_demo.sh → quality_report.py) uses the --eval-spec / golden-Q&A / --tag-turns features added in #174. The example code and engine are complete and tested here, but the end-to-end demo should be run after #174 lands. Opening as draft for early review of the example + engine.