| name | agent-evolution |
| description | Run self-evolution cycle — score agents, detect drift, propose instruction improvements. Use at session end, weekly cadence, or monthly deep review. |
Agent Evolution Skill
Run the self-evolving agent improvement cycle — from data collection through scoring, drift detection, and instruction evolution.
When to Use
- Session end: Quick status check and data collection
- Weekly review: Full scoring + drift detection + trend analysis
- Monthly audit: Complete audit with paper export and evolution proposals
Quick Status Check (Session End)
./run.sh evolve --status
./run.sh feedback log --agent <name>
Weekly Evolution Cycle
Run these 5 steps in order:
-
Collect session data:
.venv/bin/python scripts/agent_session_collector.py
-
Score agents:
.venv/bin/python scripts/agent_scorer.py --all
-
Detect drift:
.venv/bin/python scripts/agent_drift_detector.py
-
Check compliance:
.venv/bin/python scripts/agent_compliance_checker.py
-
Analyze trends:
.venv/bin/python scripts/agent_trends.py --weekly
Or one command: ./run.sh evolve --review weekly
Monthly Deep Review
Additional steps beyond the weekly cycle:
-
Run weekly cycle first (steps 1-5 above)
-
Export paper data:
.venv/bin/python scripts/export_paper_data.py
-
Propose evolutions:
.venv/bin/python scripts/agent_evolve_instructions.py --propose
-
Review proposals:
.venv/bin/python scripts/agent_evolve_instructions.py --list
-
Apply approved:
.venv/bin/python scripts/agent_evolve_instructions.py --apply --confirm
Or: ./run.sh evolve --review monthly
Rollback
Emergency rollback procedure:
.venv/bin/python scripts/agent_evolve_instructions.py --rollback <agent-name>
Key Data Files
| File | Purpose |
|---|
logs/agent-performance/scorecard_index.json | Latest scores per agent |
logs/agent-performance/evolution-log.json | Applied evolution history |
logs/agent-performance/pending-evolutions.json | Proposed changes |
logs/agent-performance/sessions/*.json | Raw session data |
logs/agent-performance/trends/*.json | Trend analyses |
logs/agent-performance/backups/*.bak | Agent file backups |
Safety Rules
- Level 2+ changes on safety-critical agents are BLOCKED
- Maximum 3 auto-edits per week
- Always verify with
--dry-run or --propose before --apply
- Backups are created automatically; rollback with
--rollback
Burn-in Period
The system requires 15-20 sessions of data collection before evolution proposals become meaningful. During burn-in, focus on OBSERVE and MEASURE only — do not EVOLVE.