agent-skill-evolution

name	agent-skill-evolution
description	Agent skill evolution capability pack. Gives AI agents the judgment rules for building self-improving agents — architecture decisions (fixed vs evolvable instruction), training loop design (rollout→reflect→edit→gate), edit safety (bounded edit, LR schedule, protected regions), validation gates, offline consolidation (sleep cycles), and multi-timescale memory. Research-grounded rules from SkillOpt (Microsoft, arXiv 2605.23904), SkillOpt-Sleep, and EmbodiSkill. Use for any self-evolving agent design, skill optimization pipeline, or agent self-improvement task.
keywords	["self-evolving agent","自演化","skill optimization","prompt optimization","self-improvement","自我改进","validation gate","验证门","bounded edit","protected regions","sleep cycle","离线学习","offline learning","offline consolidation","training loop","训练循环","SkillOpt","text-space optimization","experience replay","multi-timescale memory","agent learning"]
type	reference-based

CONSUMES: Agent description + self-improvement requirements + optional existing skill/memory docs + evaluation setup (held-out set, success metric) PRODUCES: Applied self-evolution judgment rules + architecture decision + training loop design + safety mechanism review + gate configuration guidance

Agent Skill Evolution Capability Pack

Version: 0.1.0 Compatibility: Claude Code / Codex / Copilot / OpenClaw (via SkillOpt-Sleep adapters) License: Apache 2.0

---

What This Pack Does

AI agents asked to "learn from experience" or "improve over time" default to vague suggestions: "add a feedback loop," "fine-tune the model," or "log failures and iterate." These miss the engineering reality: an agent modifying its own instructions without a validation gate, edit budget, and protected regions is not learning — it is drifting. SkillOpt's empirical evidence: ungated self-modification collapsed accuracy from 0.554 to 0.026 (−52.8 percentage points) over 5 nights.

This pack embeds the judgment rules from SkillOpt (Microsoft, arXiv 2605.23904) — the first production-grade framework for text-space skill optimization, proven across 6 benchmarks, 7 models, and 3 harnesses (all 52 cells best/tied-best, with improvements of +23.5, +24.8, +19.1 pts on key benchmarks). The rules cover architecture decisions, training loop design, edit safety, validation gates, offline consolidation (sleep cycles), and multi-timescale memory.

Pack = self-evolution judgment. Your orchestration system = process constraints. No overlap.

---

Cross-Cutting Rule: No Gate = No Evolution

An agent modifying its own instructions without a held-out validation gate is not learning — it is drifting. SkillOpt evidence: ungated self-modification collapsed accuracy from 0.554 to 0.026 (−52.8 pts) over 5 nights. The gate uses strictly-greater-than acceptance (VG1) — a tie means reject. Without this, every self-modification risks catastrophic forgetting that accumulates silently until the agent is unusable.

This rule overrides all others. If you cannot implement a validation gate (no held-out set, no checkable metric), do NOT build a self-evolving agent — maintain the skill manually instead.

---

Quick Rule Index

ID	Rule	Reference
AD1	Checkable correctness signal required	references/architecture-decisions.md
AD2	Fixed vs Evolvable instruction (gate+budget+regions+staging)	references/architecture-decisions.md
AD3	Online vs Offline consolidation (offline+gate safer)	references/architecture-decisions.md
AD4	Single-model vs Dual-model architecture	references/architecture-decisions.md
TL1	Six-stage pipeline contract (rollout→reflect→aggregate→select→update→gate)	references/training-loop.md
TL2	Reflect modes — shallow (per-trajectory) vs deep (cross-trajectory)	references/training-loop.md
TL3	Hierarchical aggregate — failure patches priority	references/training-loop.md
TL4	Contrastive reflection — K≥3 rollouts, spread-based selection, cache key includes rollout index	references/training-loop.md
ES1	Edit mode selection — patch > rewrite_from_suggestions > full_rewrite	references/edit-safety.md
ES2	LR schedule — cosine > constant; 2-4 epochs sufficient	references/edit-safety.md
ES3	Protected regions — marker-based write isolation, 4-layer enforcement	references/edit-safety.md
ES4	Lapse vs Defect classification (EXECUTION_LAPSE vs SKILL_DEFECT)	references/edit-safety.md
VG1	Strictly-greater-than acceptance (tie = reject)	references/validation-gate.md
VG2	Metric selection — hard/soft/mixed; mixed most stable for small validation sets	references/validation-gate.md
VG3	Selection cache by SHA content hash — skip redundant validation rollouts	references/validation-gate.md
VG4	Longitudinal 4-quadrant comparison (improved/regressed/persistent_fail/stable_success)	references/validation-gate.md
OC1	Six-stage Sleep pipeline (harvest→mine→replay→consolidate→stage→adopt)	references/offline-consolidation.md
OC2	Harvest is read-only — never modify source transcripts	references/offline-consolidation.md
OC3	Heuristic miner (free, deterministic) vs LLM miner (accurate, costs API)	references/offline-consolidation.md
OC4	Experience replay — associative recall via token Jaccard, recall_k=10/20	references/offline-consolidation.md
OC5	Dream augmentation — synthetic variants expand training only, never validation	references/offline-consolidation.md
OC6	"Nothing live changes" — staging dir + backup + explicit adopt	references/offline-consolidation.md
OC7	Task guardrail — inject target's output contract into reflect prompt	references/offline-consolidation.md
MT1	Three memory tiers — step buffer / slow update / meta skill	references/multi-timescale-memory.md
MT2	Write isolation — step-level edits cannot modify epoch-level guidance	references/multi-timescale-memory.md
MT3	Appendix consolidation — accumulate lapse notes, LLM-compact at threshold (15-20 notes)	references/multi-timescale-memory.md
SI1	Claude Code plugin — install, configure, schedule (3:17 AM cron), mock backend for testing	references/skillopt-sleep-integration.md
SI2	Cross-platform plugin shells — one engine, thin per-platform adapters	references/skillopt-sleep-integration.md
SI3	Safety contract — harvest read-only, nothing live changes, staging + adopt	references/skillopt-sleep-integration.md

---

Step 0: Context Detection

When the user mentions self-improvement for an agent, detect the context and load the relevant reference:

User Signal	Reference to Load
"should this agent learn", "self-evolving", "自演化", "自我改进", "improve over time", "learn from experience"	references/architecture-decisions.md
"training loop", "训练循环", "rollout", "reflect", "pipeline", "epoch", "step"	references/training-loop.md
"edit safety", "bounded edit", "learning rate", "LR schedule", "protected region", "lapse", "defect", "EXECUTION_LAPSE", "SKILL_DEFECT"	references/edit-safety.md
"validation gate", "验证门", "held-out", "accept", "reject", "gate metric", "mixed metric"	references/validation-gate.md
"sleep cycle", "离线学习", "offline", "consolidation", "harvest", "dream", "replay", "staging", "adopt"	references/offline-consolidation.md
"memory tier", "multi-timescale", "appendix", "step buffer", "meta skill", "slow update"	references/multi-timescale-memory.md
"install SkillOpt", "plugin", "cron", "schedule", "Claude Code plugin", "Codex plugin", "mock backend"	references/skillopt-sleep-integration.md

---

Step 1: Apply Rules

1. Read the referenced file(s) — each reference contains rules with IDs (AD1, TL1, etc.), source citations, and SkillOpt evidence data.
2. Apply rules to the user's specific scenario — adapt the general principles to their agent, evaluation setup, and platform constraints.
3. Cite specific numbers when they're relevant — the pack's value is in the research-grounded specifics, not the general principles. A rule without its number is a generic suggestion.

---

Step 2: Output

Structure your response around the user's needs:

• Architecture decision: Use AD1-AD4. End with a clear recommendation (build self-evolving / keep fixed / hybrid).
• Pipeline design: Use TL1-TL4. Show the six-stage flow with their specific choices.
• Safety review: Use ES1-ES4 + VG1-VG4. Verify all four safety mechanisms are present (use scripts/gate-check.sh as a checklist).
• Integration guide: Use SI1-SI3. Platform-specific setup steps.

---

Anti-Skip Table

Agent might think...	Why it's wrong
"The feedback loop is obvious — just log failures and iterate"	A feedback loop without a validation gate is unguarded drift. SkillOpt evidence: −52.8 pts over 5 nights without the gate (AD2).
"We can fine-tune the model instead of editing the prompt"	Text-space skill optimization (editing the prompt/SKILL.md) has zero inference-time overhead and works across models. Fine-tuning requires training infrastructure, model access, and redeployment. Different problems.
"Protected regions are overkill — the gate catches regressions"	The gate's held-out set may not cover every protected behavior. 4-layer defense (ES3) catches what the gate misses. One layer is not enough (~5% failure rate per layer).
"We don't need staging — the gate already validates"	The gate validates on the held-out set. Staging + human review catches qualitative issues the gate can't measure (confusing wording, style drift, off-brand tone). OC6.

---

Tool Quick Reference

SkillOpt (recommended reference implementation)

pip install skillopt
# Key commands:
skillopt train --config config.yaml     # run the 6-stage training loop
skillopt evaluate --skill SKILL.md      # run validation gate on held-out set
skillopt sleep --config sleep.yaml      # run overnight consolidation cycle
skillopt adopt                          # promote staged skill to live
# Mock test (zero API cost):
python -m skillopt_sleep run --backend mock

• Repository: github.com/microsoft/SkillOpt (7,761 stars)
• Paper: arXiv 2605.23904
• When to use: As the training engine for agents with checkable metrics. The pack teaches the judgment rules; SkillOpt is one production implementation.
• When NOT to use: For agents without a checkable correctness signal (AD1). For subjective quality tasks, consider LLM-as-judge with calibrated agreement (ICC > 0.80) as a proxy metric.