Skill 训练器 — 用户侧协议

你现在运行 skill-trainer 技能。目标：把学员手写的 SKILL.md 送进一次真正的 训练循环，让它在留出集上跑得比原版更准，并交出一份「你会拿到什么」清清楚楚 的 best_skill.md + 前后分数对比报告。

心智模型

Skill 也能像神经网络一样有 loss 曲线可看。 六步循环缺一不可：

1. Rollout — 用当前候选 SKILL.md 在一小批任务上跑一次真实回复。
2. Reflect — 对每条 rollout 结果按 rubric 打分，指出扣分点。
3. Aggregate — 把所有扣分点聚合出「哪一类问题最影响分数」。
4. Select — 从一组候选修改（新增规则、改写规则、去除冗余）里挑最有希望的一批。
5. Update — 把候选修改应用到 SKILL.md，得到下一版候选。
6. Validate — 在留出集上打分。新版本必须 ≥ 上一版才接受，否则回滚。

任何一版的产出物是同一个包：

• out/best_skill.md — 当前最优 SKILL.md
• out/validation-gate.json — baseline / optimized 两组分数 + gate 结论
• out/validation-gate.html — 同一份数据的可视化对比

前置条件

• 本地 Python ≥ 3.11、pip
• 一个 Clawvard API key（在 https://clawvard.school 免费领）
• 训练集 + 验证集：两个 JSONL 文件，每行至少包含 id / prompt / ideal（理想输出）三个字段
• 无需 clone 任何私有仓库；所有依赖都是公开可达的 npm / PyPI 包

工作流程

步骤 1：装 SkillOpt

pip install "skillopt>=0.2.0"
skillopt-sleep --version

如果 pip 报权限错误，换成 pip install --user skillopt 或先跑 python3 -m venv .venv && source .venv/bin/activate。

步骤 2：拉后端脚手架

一条命令搞定：Clawvard 后端适配层放到 skillopt/model/，同时在当前目录 生成一份可运行的 trainer.yaml 模板。

curl -fsSL https://clawvard.school/skills/skill-trainer/setup.sh | bash

装好之后跑一次 self-check：

python3 -c "from skillopt.model.clawvard_backend import sanity_check_env; sanity_check_env()"

步骤 3：把数据切成 JSONL

每行至少包含：

{"id":"t-001","prompt":"客户咨询：我的订单 A1023 什么时候到？","ideal":"..."}

写脏东西前先脱敏（真实姓名、手机号、身份证号一律替换）。

• 训练集 30-60 条足够跑通六步循环。
• 验证集 15-25 条即可，规模不影响 gate 的意义。
• 边缘样本（客户情绪激烈 / 信息不全 / 多商品混合）单独放验证集，专门检验优化后的 skill 有没有真的变稳。

步骤 4：配 trainer.yaml

打开 setup.sh 生成的模板，改三处：

• seed_skill 指向你的手写 SKILL.md
• train_set.path / val_set.path 指向你的两个 JSONL
• exec_backend.params.model 选一个 Clawvard 支持的 Claude 型号 （claude-sonnet-4-6 / claude-opus-4-8 / claude-haiku-4-5-20251001）

不要改 exec_backend.module。它已经指向 Clawvard 后端；改走别的 base URL 或 provider 会被后端拒绝，是刻意为之的守门。

步骤 5：启动训练循环

export CLAW_API_KEY=sk-xxx
skillopt-sleep --config trainer.yaml

一次典型 60 训练 + 20 验证的 skill，跑 2-3 epoch 在几分钟到十几分钟之间。 在进度里会看到每个 epoch 尝试了哪些候选修改（select）、哪几条被接受 （update）、验证集分数是否守住 gate。

步骤 6：读 out/，确认 gate 通过

三个文件都会写出：

• out/best_skill.md — 直接可以覆盖你原来的 SKILL.md
• out/validation-gate.json — 结构化数据；跑 CI / 做长期追踪的口子
• out/validation-gate.html — 打开浏览器就能看的对比页

接受这一版的判定：验证集 optimized ≥ baseline。否则回滚，重新调 rubric 或补数据集，然后再跑一次。

Prompt 模板

启动 skill-trainer skill。我在 ./skills/{slug}/SKILL.md 有一版手写的 {场景}
skill；训练集 ./data/{slug}-train.jsonl（{N} 条），验证集
./data/{slug}-val.jsonl（{M} 条）。请：
1) 用 skillopt-sleep 跑完整六步循环（rollout → reflect → aggregate → select
   → update → validate），2) 每一步把当前得分同步给我，3) 产出
   ./out/best_skill.md + ./out/validation-gate.html，4) 验证集分数必须
   ≥ baseline 才 PASS，否则回滚并告诉我原因。

调试 tips

• 训练分数上升、验证分数不升 → 训练集里有捷径样例；把边缘样本从训练集挪 到验证集，或补一批多样性更高的训练样例，再跑一次。
• 每 epoch 分数都往下走 → 候选修改把已有 SKILL.md 里正确的规则覆盖掉了， 改 select 阶段的策略（保留旧规则、增补新规则，而不是重写）。
• 报「quota_exceeded」 → Clawvard 余额不足或触发了平台的日模型上限；到 https://clawvard.school 补 credits，或换一个更小的模型再跑。
• 报「rate_limited」 → 把 concurrency 从 8 降到 4，或把训练集切成两半 分两次跑。
• best_skill.md 只是加了很多规则、可读性变差 → 在下一轮 rubric 里加一 个「简洁度」维度（例如「行数 / 段数」上限），让 select 阶段把冗余规则拒掉。

产出物

• ./out/best_skill.md — 一份分数经过验证的最优 SKILL.md，可以直接覆盖原 版并装进 Claude Code。
• ./out/validation-gate.json — 结构化 before/after 分数、每维通过率、每 epoch 增删的规则清单。
• ./out/validation-gate.html — 同一份数据的可视化：左侧 Markdown 预览 + 右侧 metrics table + epoch × 分数折线。

学习完成后

告诉用户：

我已经学会了 skill-trainer。给我你手写的 SKILL.md 和一小份训练 / 验证数 据，我把它送进 rollout → reflect → aggregate → select → update → validate 的循环，交出一份验证集分数比 baseline 高的 best_skill.md，以及一份可以贴 到 PR / 周报里的分数对比报告。