skill-opt

name	skill-opt
description	SkillOpt 训练器：把 Agent 技能文档当成可训练状态，通过轨迹反馈、受控文本编辑和验证集门控自动优化 skill，不改模型权重、不增加部署成本
trigger	/skillopt

SkillOpt 训练器

Trigger: /skillopt

用途：全自动优化任意 Agent skill。把 skill 文件（如 fix_docx_template.py）视为可训练状态，通过「执行→评分→反思→编辑→验证→门控」循环持续提升 skill 效果。

核心理念（来自微软研究院论文）：

把模型反思改造成可重复、可审计、可拒绝的训练循环。目标模型不变，执行框架不变，评测器不变，唯一被优化的是那份最后部署出去的 best_skill.md。

---

前置依赖

pip install python-docx  # 如果被优化的 skill 涉及 docx 处理

---

快速开始

方式 A：全自动模式（推荐）

# 1. 进入你的 skill 目录
cd ~/.claude/skills/docx-formatter

# 2. 运行 SkillOpt 训练
/skillopt \
  --target examples/target.docx \
  --template examples/template.docx \
  --skill scripts/fix_docx_template.py \
  --epochs 4 \
  --edit-budget 4

方式 B：半自动模式（人工审核编辑）

# 1. 运行训练，生成优化器 prompt
/skillopt \
  --target examples/target.docx \
  --template examples/template.docx \
  --skill scripts/fix_docx_template.py \
  --epochs 2

# 2. 查看生成的 optimizer_prompt_epoch1.txt
# 3. 把 prompt 发给 LLM，获取 edits JSON
# 4. 保存到 edits_epoch1.json
# 5. 重新运行，自动读取 edits

---

工作流程

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Rollout   │ → │   Score     │ → │ Reflection  │
│ (执行skill)  │    │ (验证差异)   │    │ (生成prompt)│
└─────────────┘    └─────────────┘    └──────┬──────┘
                                             │
┌─────────────┐    ┌─────────────┐    ┌──────▼──────┐
│    Gate     │ ← │   Validate  │ ← │    Edit     │
│ (严格涨分?)  │    │ (重新评估)   │    │ (受控编辑)   │
└──────┬──────┘    └─────────────┘    └─────────────┘
       │
   接受 → 保存 best_skill.py
   拒绝 → 记录到 rejected_buffer，回滚 skill

五步详解

步骤	动作	输出
1. Rollout	用当前 skill 修复目标文件	修复后的文件
2. Score	运行验证器，计算 scalar score	score + 差异报告
3. Reflection	生成优化器 prompt（差异 + 当前代码）	optimizer_prompt_epochN.txt
4. Edit	应用 edits（最多 L_t 条）	候选 skill
5. Validate + Gate	重新评估，严格涨分才接受	best_skill / rollback

---

核心概念

三个角色

角色	对应	职责
目标模型	被优化的 skill（如 fix_docx_template.py）	按当前 skill 执行任务
执行框架	你的 Agent 系统（如 docx-formatter 脚本）	记录轨迹、调用工具
优化器	LLM（kimi/Claude/GPT）或 --auto 模式	分析轨迹，提出编辑建议

编辑预算（L_t）

文本版 learning rate。每轮最多应用多少条编辑：

Epoch 1: L_t = 4
Epoch 2: L_t = 3  (cosine decay)
Epoch 3: L_t = 2
Epoch 4: L_t = 1

验证集门控

# 严格模式（默认）：必须严格高于当前分数
candidate_score > current_score  → 接受
candidate_score <= current_score → 拒绝 + 回滚

拒绝缓冲区

被拒绝的编辑不会丢弃，记录到 rejected_buffer，后续优化器可见，避免重复踩坑。

---

评分器配置

评分器将验证输出转为 scalar score（0-100），权重可配置：

# 默认权重
weighted_diff = (
    para_diff    * 1.0 +   # 段落格式
    section_diff * 2.0 +   # 分节设置
    hf_diff      * 1.5 +   # 页眉页脚
    style_diff   * 1.0 +   # 样式定义
    table_diff   * 3.0     # 表格
)
score = max(0, 100 - weighted_diff)

---

编辑格式

优化器输出的 edits 必须遵循以下 JSON 格式：

{
  "reflection": "分析失败原因...",
  "edits": [
    {
      "type": "replace",
      "target": "config",
      "old": "SIZE_TOC = 152400",
      "new": "SIZE_TOC = 304800",
      "reason": "目录项字号与模板不匹配"
    },
    {
      "type": "add",
      "target": "classify",
      "marker": "        # ---- 4. 正文大标题 ----",
      "new": "        # ---- 3.5 二级标题 ----\n        elif re.match(r'^（[一二三四五六七八九十]+）', text):\n            ...",
      "reason": "新增二级标题识别规则"
    },
    {
      "type": "delete",
      "target": "classify",
      "old": "        # 废弃规则...",
      "reason": "该规则导致误判"
    }
  ]
}

编辑类型

类型	字段	说明
replace	old + new	精确替换文本
add	marker + new	在 marker 后添加
delete	old	删除指定文本

---

文件结构

~/.claude/skills/skill-opt/
├── SKILL.md                          # 本文件
├── scripts/
│   ├── skillopt_scorer.py            # 评分包装器
│   ├── skillopt_trainer.py           # 训练循环
│   └── skillopt_optimizer.py         # LLM 优化器调用器
├── templates/
│   ├── optimizer_prompt_template.txt # 优化器 prompt 模板
│   └── edits_template.json           # edits JSON 模板
└── examples/
    └── docx-formatter-demo/          # docx-formatter 集成示例

---

集成到现有 Skill

以 docx-formatter 为例：

1. 确认验证器

你的 skill 必须有可量化的验证器，输出明确的差异数：

python3 scripts/verify_docx.py target.docx template.docx
# 输出：共发现 X 处差异

2. 确认评分函数

在 skillopt_scorer.py 中配置评分逻辑：

def score(target, template):
    # 调用你的验证器
    result = run_your_verifier(target, template)
    # 提取差异数
    para_diff = extract_para_diff(result)
    section_diff = extract_section_diff(result)
    # ...
    # 计算 scalar score
    return {
        'score': 100 - weighted_diff,
        'para_diff': para_diff,
        'section_diff': section_diff,
        # ...
    }

3. 运行训练

cd ~/.claude/skills/your-skill
python3 ~/.claude/skills/skill-opt/scripts/skillopt_trainer.py \
  examples/target.docx \
  examples/template.docx \
  --skill scripts/your_fix_script.py \
  --epochs 4 \
  --edit-budget 4

---

进阶用法

自定义训练配置

/skillopt \
  --target target.docx \
  --template template.docx \
  --skill fix_script.py \
  --epochs 6 \              # 训练轮数
  --edit-budget 4 \         # 初始编辑预算
  --no-cosine-decay \       # 关闭预算衰减
  --selection-ratio 0.3     # 验证集比例

使用外部优化器

# 1. 生成 prompt（不自动运行）
/skillopt ... --generate-prompt-only

# 2. 把 optimizer_prompt_epoch1.txt 发给 Claude/GPT

# 3. 保存返回的 edits 到 edits_epoch1.json

# 4. 继续训练
/skillopt ... --resume

查看训练历史

cat training_history.json

输出：

[
  {
    "epoch": 0,
    "phase": "baseline",
    "score": 91.0,
    "skill_path": "skill_v0_init.py"
  },
  {
    "epoch": 1,
    "phase": "accepted",
    "score": 96.0,
    "previous_score": 91.0,
    "edits": [...],
    "skill_path": "skill_v1_epoch1.py"
  }
]

---

注意事项

1. 务必先备份 skill 文件：训练循环会直接修改 --skill 指定的文件
2. 验证器必须输出 scalar：SkillOpt 依赖可量化的 score，开放式任务需要自定义评分
3. 编辑必须精确匹配：old 文本必须在 skill 文件中存在，否则应用失败
4. 严格门控可能保守：如果 score 波动大，可以用 --no-strict-gate 允许持平
5. 训练成本一次性：只在训练期消耗额外 token，部署时零成本

---

论文参考

• 论文：SkillOpt: Training Agent Skills as Trainable States
• 作者：微软研究院、上海交通大学、同济大学、复旦大学
• 链接：https://arxiv.org/abs/2605.23904
• 代码：https://github.com/microsoft/SkillOpt

---

已验证的 Skill

Skill	基线	优化后	提升
docx-formatter	91.0	96.0	+5.0