SkillOpt: Executive Strategy for Self-Evolving Agent Skills

Train agent skills like you train neural networks — with epochs, (mini-)batchsize, learning rates, and validation gates — but without touching model weights.

📖 For installation, data preparation, training/eval commands, the full configuration reference, and framework internals, see the Documentation & Reproduction Guide (rendered on GitHub Pages).

SkillOpt 是一个将深度学习训练范式引入 Agent 提示词优化的框架。它的核心思想是：将"技能文档"（一份 Markdown 格式的自然语言指令）视为冻结模型的可训练参数，用 epochs、learning rate、batch size、validation gate 等概念来迭代优化它——整个过程不修改模型权重。

传统做法是靠人工编写 Prompt、或用强模型一次性生成、或通过松散的自我修订来"进化"——这些方法都不像深度学习优化器那样稳定可靠。SkillOpt 改变了这一点。

  [① Rollout]    [② Reflect]   [③ Aggregate]   [④ Select]   [⑤ Update]   [⑥ Gate]
  目标Agent       优化器分析       分层合并        排序裁剪      应用编辑      验证门控
  执行任务 →      生成补丁 →      多个补丁 →      Top-K →      改技能文档 →  合格才接受

Epoch 边界还包含两个机制：

• Slow Update：对前后 epoch 的技能进行纵向对比，生成高层指导注入技能文档（类比 EMA / 正则化）
• Meta Skill：跨 epoch 积累策略记忆，为后续反思提供上下文

1. 文本学习率（Textual Learning Rate）：用自然语言编辑预算（editing budget）替代数值学习率，支持 cosine/linear/constant/autonomous 调度策略
2. Minibatch 反思：轨迹分组批量分析（而非逐条），类 mini-batch SGD——比逐样本分析更稳定
3. 严格验证门控：只在 held-out 集上严格提升时才接受修改，杜绝退化——类比 early stopping
4. 零推理开销部署：最终产物只是一个紧凑的 .md 文件，部署时不需要任何额外的模型调用
5. Skill 跨模型迁移：优化后的 Skills 可跨模型大小、跨执行框架、跨相邻 Benchmark 直接使用
6. Skill-Aware Reflection (EmbodiSkill)：分离技能文档缺陷 vs. 执行失误，通过受保护附录区实现
7. 执行驱动（Exec Harness）：支持直接在 Codex CLI / Claude Code CLI 的真实 Agent 编码循环中训练

• 52 个评估单元（6 Benchmark × 7 模型 × 3 执行驱动）全部达到最佳或并列最佳
• 在 GPT-5.5 上，相比无 Skill 的基线：
  • 直接对话：+23.5 个百分点
  • Codex Agent 循环内：+24.8 个百分点
  • Claude Code 内：+19.1 个百分点
• 优化后的 Skill 产物可跨模型大小、跨执行框架、跨相邻基准直接迁移而无需再优化

SkillOpt-Sleep 将 SkillOpt 的训练纪律应用到你的日常使用中。它给你的本地编码 Agent 一个"夜间睡眠周期"：

收割对话记录 → 挖掘重复任务 → 离线重放 → 门控验证 → 暂存更新技能 → 用户审查后应用

支持 Claude Code、Codex、Copilot 三个平台，零依赖独立运行。详见 docs/sleep/README.md。

# 克隆仓库
git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt

# 安装（推荐开发模式）
pip install -e .

# 或通过 PyPI 安装
pip install skillopt

Python ≥ 3.10 必须。可选依赖见下表：

cp .env.example .env
# 编辑 .env，填入你的 API Key

支持的模型后端：

以 SearchQA（最快完成，约 30 分钟）为例：

# 查看配置
cat configs/searchqa/default.yaml

# 开始训练
python scripts/train.py --config configs/searchqa/default.yaml

训练过程中的典型输出：

[Step 1/8] Rollout: 20 items, 4 workers...
[Step 1/8] Score: 0.65 → Reflect...
[Step 1/8] 6 edit patches generated
[Step 1/8] Selected 4 edits (lr=8, cosine → 7.7)
[Step 1/8] Gate: val score 0.68 > 0.65 ✓ ACCEPT

python scripts/eval_only.py \
  --config configs/searchqa/default.yaml \
  --skill outputs/searchqa/<run_id>/skills/best_skill.md

pip install -e ".[webui]"
python -m skillopt_webui.app
# 打开 http://localhost:7860

CLI 覆写示例：

python scripts/train.py \
  --config configs/searchqa/default.yaml \
  optimizer.learning_rate=16 \
  optimizer.lr_scheduler=linear \
  gradient.analyst_workers=8

outputs/<benchmark>/<run_id>/
├── steps/
│   ├── step_0001/
│   │   ├── candidate_skill.md    # 本步候选技能
│   │   ├── step_record.json      # 步记录
│   │   └── trajectory_digest.json # 轨迹摘要
│   └── step_0002/
├── slow_update/                   # Slow Update 产物
├── meta_skill/                    # Meta Skill 产物
├── skills/                        # 各步技能快照
├── best_skill.md                  # ★ 最终产物：最佳技能文档
├── history.json                   # 训练历史记录
└── config.yaml                    # 回显配置

最终产物 best_skill.md 可以直接作为 System Prompt 部署使用——零额外推理开销。

• [2026-06-15] 😴 SkillOpt-Sleep (preview) — a nightly offline self-evolution companion for local coding agents (Claude Code / Codex / Copilot): review past sessions, replay recurring tasks, and consolidate validated skills behind a held-out gate. See docs/sleep/README.md for what it is, how to use it, and results.
• [2026-06-03] 🎉 gbrain, gbrain-evals, and darwin-skill have all integrated SkillOpt.
• [2026-06-02] 🎉 SkillOpt v0.1.0 is now available on PyPI! Install with pip install skillopt. This initial release includes the full training loop (rollout → reflect → aggregate → select → update → evaluate), multi-backend support (OpenAI / Azure / Claude / Qwen / MiniMax), six built-in benchmarks, and WebUI dashboard.

Modern agent skills are usually hand-crafted, generated one-shot by a strong LLM, or evolved through loosely controlled self-revision — none of which behaves like a deep-learning optimizer for the skill itself, and none of which reliably improves over its starting point under feedback.

SkillOpt treats the skill document as the trainable state of a frozen agent, and trains it with the discipline that makes weight-space optimization reproducible. A separate optimizer model turns scored rollouts into bounded add / delete / replace edits on a single skill document; a candidate edit is accepted only when it strictly improves a held-out validation score. A textual learning-rate budget, a rejected-edit buffer, and an epoch-wise slow / meta update make skill training stable while adding zero inference-time model calls at deployment.

The deployed artifact is a compact best_skill.md (typically 300–2,000 tokens) that runs against the unchanged target model. Across six benchmarks, seven target models, and three execution harnesses (direct chat, Codex CLI, Claude Code CLI), SkillOpt is best or tied-best on all 52 evaluated (model, benchmark, harness) cells and on GPT-5.5 lifts the average no-skill accuracy by +23.5 points in direct chat, +24.8 inside the Codex agentic loop, and +19.1 inside Claude Code. Optimized skill artifacts transfer across model scales, between Codex and Claude Code harnesses, and to nearby benchmarks without further optimization.

For the full method, ablations, and per-cell results see the paper; for a visual walkthrough of the loop see the project page; for deeper API / backend / benchmark docs see docs/.

▶ Watch the full demo on YouTube

A backend = a chat / exec target (e.g. openai_chat, claude_chat, qwen_chat, minimax_chat, codex_exec, claude_code_exec). See docs/guide/new-backend.md for the full contract; in short you add a skillopt/model/<name>_backend.py module, register it in skillopt/model/common.py + backend_config.py, and wire it through the router in skillopt/model/__init__.py. qwen_backend.py and minimax_backend.py are good templates.

A benchmark = a skillopt/envs/<name>/ package with a dataloader.py, a rollout.py, and an initial.md seed skill. See docs/guide/new-benchmark.md for the full contract; the simplest reference is skillopt/envs/searchqa/.

Launch the monitoring dashboard (optional):

pip install -e ".[webui]"
python -m skillopt_webui.app

@misc{yang2026skilloptexecutivestrategyselfevolving,
      title={SkillOpt: Executive Strategy for Self-Evolving Agent Skills}, 
      author={Yifan Yang and Ziyang Gong and Weiquan Huang and Qihao Yang and Ziwei Zhou and Zisu Huang and Yan Li and Xuemei Gao and Qi Dai and Bei Liu and Kai Qiu and Yuqing Yang and Dongdong Chen and Xue Yang and Chong Luo},
      year={2026},
      eprint={2605.23904},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.23904}
}