name: darwin-skill
v2.0 · 2026-05-28 — 吸收 Microsoft Research SkillLens(arXiv 2605.23899)的 9 维评分药方 + SkillOpt(arXiv 2605.23904)的 validation-gated 验证机制 + human in the loop 三层守关。
借鉴 Karpathy autoresearch 的自主实验循环,对 skills 进行持续优化。 核心理念:评估 → 改进 → 实测验证 → 人类确认 → 保留或回滚 → 生成成果卡片 GitHub: https://github.com/alchaincyf/darwin-skill
autoresearch 的精髓:
与纯结构审查的区别:不只看 SKILL.md 写得规不规范,更看改完后实际跑出来的效果是否更好。
设计依据:基于 SkillLens 论文(arXiv 2605.23899)实证发现——LLM-as-judge 评估 skill 质量准确率仅 46.4%(接近随机),加入 meta-skill 三维度后提升到 73.8%。本 rubric 强化 dim3 / dim5 评分标准,新增 dim9「反例与黑名单」,权重平衡到 100。目的:让评分对真实质量更敏感,减少 LLM judge 的乐观偏差。
| # | 维度 | 权重 | 评分标准 |
|---|---|---|---|
| 1 | Frontmatter质量 | 7 | name规范、description包含做什么+何时用+触发词、≤1024字符、禁结尾加"灵活应用/根据情况判断"等空话尾巴 |
| 2 | 工作流清晰度 | 12 | 步骤明确可执行、有序号、每步有明确输入/输出 |
| 3 | 失败模式编码 | 12 | 必须显式编码失败模式(写出"如果 X 失败 → Y"的明确分支);有fallback路径、错误恢复;只写正向流程而不写失败分支扣 ≥3 分(SkillLens meta-skill 维度) |
| 4 | 检查点设计 | 6 | 关键决策前有用户确认、防止自主失控;检查点必须显性标记(🔴/STOP/CHECKPOINT),仅靠"如果...建议..."措辞不算 |
| 5 | 可执行具体性 | 17 | 不模糊、有具体参数/格式/示例、可直接执行;禁止"建议/可以考虑/根据情况/灵活把握/视情况而定"等软化措辞——出现 ≥3 处扣 ≥3 分(SkillLens actionable specificity 维度) |
| 6 | 资源整合度 | 4 | references/scripts/assets引用正确、路径可达 |
| # | 维度 | 权重 | 评分标准 |
|---|---|---|---|
| 7 | 整体架构 | 12 | 结构层次清晰、不冗余不遗漏、与花叔生态一致;冗余/AI腔废话段落(说白了/换句话说/首先其次综上等花叔禁用词)出现一处扣 1 分 |
| 8 | 实测表现 | 23 | 用测试prompt跑一遍,输出质量是否符合skill宣称的能力 |
| # | 维度 | 权重 | 评分标准 |
|---|---|---|---|
| 9 | 反例与黑名单 | 6 | skill 必须有"不要做什么"的反例清单;只写"应该做 X"没有"不要做 Y"扣 ≥3 分;红灯/危险动作/反模式应单独章节列出(SkillLens risk-action blacklist 维度) |
rubric 设计依据来自 SkillLens 论文(arXiv 2605.23899) + 本机 controlled study:
结论:rubric 能识别 gross degradation,但 fine-grained quality difference 仍不可信,重要决策必须人审。
→ 详细论文证据 + 5 judges 完整数据 + HL 实战案例数字见 references/skilllens-evidence.md
这是与纯结构评分最大的区别。评分方式:
若子 agent 不可用(超时/资源限制),退化为「干跑验证」:读完 skill 后模拟一个典型 prompt 的执行思路,判断流程是否合理;必须在 results.tsv 标注 dry_run。dry_run 比例 > 30% → 评估失效警告(来自本机 controlled study:dim8 实测维度权重 23%,无 full_test 验证时分数不可信)。
skill 应当能在 Claude Code / Codex / Cursor / OpenClaw / Hermes / Gemini CLI / OpenCode 等 50+ skills-compatible runtime 通用——否则其他 agent 解析时会被「在 Claude Code 里」「Claude Code skill」等措辞误判为「不是给我用的」直接拒装(实例:nuwa-skill 因此被 Marvis agent 拒绝)。
grep -nE "(在 Claude Code|Claude Code skill|Claude Code 用户|Cursor only|Codex 中|^\[!\[Claude Code|~/\.claude/skills/[a-z]|/plugin install\b)" SKILL.md README.md 2>/dev/null
输出非空 = 红灯命中 → 强制把 Phase 2 第一轮定为 P0「runtime drift 修复」(写入 results.tsv 的 note 列 runtime_warn=N)。
frontmatter 触发词、花叔生态内部 skill 名引用、明确标注 runtime-specific 章节、commit message——这些正当出现,不算红灯。
→ 红灯/绿灯完整对照表 + 例外清单详细规则 + Phase 1/2/3 各阶段审查时机见 references/runtime-neutrality.md
1. 确认优化范围:
- 全部skills → 扫描 .claude/skills/*/SKILL.md
- 指定skills → 用户指定列表
2. 创建 git 分支:auto-optimize/YYYYMMDD-HHMM
3. 初始化 results.tsv(如不存在)
4. 读取现有 results.tsv 了解历史优化记录
在评估之前,为每个skill设计测试prompt。这步很关键——没有测试prompt,「实测表现」维度就打不了分。
for each skill:
1. 读取 SKILL.md,理解它做什么
2. 设计2-3个测试prompt,覆盖:
- 最典型的使用场景(happy path)
- 一个稍复杂或有歧义的场景
3. 保存到 skill目录/test-prompts.json:
[
{"id": 1, "prompt": "用户会说的话", "expected": "期望输出的简短描述"},
{"id": 2, "prompt": "...", "expected": "..."}
]
展示所有测试prompt给用户,确认后再进入评估。测试prompt的质量决定了优化方向是否正确。
for each skill in 优化范围:
# 结构评分(主agent可以做)
1. 读取 SKILL.md 全文
2. 按维度1-7逐项打分(附简短理由)
# 效果评分(用子agent做,独立于主agent)
3. 对每个测试prompt,spawn子agent:
- with_skill: 带着SKILL.md执行测试prompt
- baseline: 不带skill执行同一prompt
4. 对比两组输出,打维度8的分
# 汇总
5. 计算加权总分
6. 记录到 results.tsv
如果子agent不可用(超时、环境限制),维度8用干跑验证打分,标注 dry_run。不要因为跑不了测试就跳过这个维度——哪怕是模拟推演也比完全不看效果好。
基线评估完成后,展示评分卡:
┌──────────────────────────┬───────┬──────────────┬──────────────┐
│ Skill │ Score │ 结构短板 │ 效果短板 │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ huashu-proofreading │ 78 │ 边界条件 │ 测试prompt2 │
│ huashu-slides │ 72 │ 指令具体性 │ baseline持平 │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ 平均 │ 75 │ │ │
└──────────────────────────┴───────┴──────────────┴──────────────┘
🔴 CHECKPOINT · 🛑 STOP:暂停等用户确认,再进入优化循环。
用户确认后,按基线分数从低到高排序,先优化最弱的。
for each skill:
round = 0
while round < MAX_ROUNDS (默认3):
round += 1
# Step 1: 诊断
找出得分最低的维度(结构或效果都算)
# HL-3 警告:dim2/dim3/dim4 是相关簇,修一个时另两个常跟着涨
# → 不要因为 dim3 最低就单独修,要看整簇短板再决定是否同步改
# Step 2: 提出改进方案
针对最低维度,生成1个具体改进方案:
- 改什么(具体段落/行)
- 为什么改(对应rubric哪条)
- 预期提升多少分
# Step 3: 执行改进
编辑 SKILL.md
git add + commit(message: "optimize {skill}: {改进摘要}")
# Step 4: 重新评估
- 结构维度:主agent重新打分
- 效果维度:spawn独立子agent重跑测试prompt(关键!不能自己评自己)
# Step 5: 决策
if 新总分 > 旧总分:
status = "keep",更新旧总分
# HL-4 见好就收:连续2轮 Δ < 2 分 → break 进 Phase 3
if last_delta < 2.0 and this_delta < 2.0:
print("触顶信号:连续2轮边际收益 < 2 分,停止优化避免过度调整")
break
else:
status = "revert"
git revert HEAD(创建新commit回滚,不用reset --hard)
记录失败尝试到 results.tsv
break # 该skill到瓶颈,跳到下一个
# Step 6: 日志
results.tsv 追加行
# === 🔴 CHECKPOINT · 每个 skill 优化完后强制人审 ===
展示该skill的改动摘要:
- git diff(改前 vs 改后)
- 分数变化(哪些维度提升/下降)
- 测试prompt输出对比(如果跑过的话)
等用户确认 OK 再继续下一个skill。
如果用户说"不好",回滚到该skill的优化前版本。
当 hill-climbing 连续2个skill都在 round 1 就 break(涨不动)时,提议一次「探索性重写」:
1. 选一个瓶颈skill
2. git stash 保存当前最优版本
3. 从头重写SKILL.md(不是微调,是重新组织结构和表达方式)
4. 重新评估
5. if 重写版 > stash版: 采用重写版
else: git stash pop 恢复
这解决了 hill-climbing 的局部最优问题——有时候需要「先拆后建」才能突破瓶颈。 🔴 CHECKPOINT · 🛑 STOP:必须征得用户同意后才执行。
## 优化报告
### 总览
- 优化skills数:N
- 总实验次数:M
- 保留改进:X(Y%)
- 回滚次数:Z
- 实测验证:A次完整测试 / B次干跑
### 分数变化
┌──────────────────────────┬────────┬────────┬────────┐
│ Skill │ Before │ After │ Δ │
├──────────────────────────┼────────┼────────┼────────┤
│ huashu-proofreading │ 78 │ 87 │ +9 │
│ huashu-slides │ 72 │ 83 │ +11 │
├──────────────────────────┼────────┼────────┼────────┤
│ 平均 │ 75 │ 85 │ +10 │
└──────────────────────────┴────────┴────────┴────────┘
### 主要改进
1. [skill-A] 补充了边界条件处理,测试输出质量提升明显
2. [skill-B] 重组了workflow结构,baseline对比优势增大
timestamp commit skill old_score new_score status dimension note eval_mode
2026-03-31T10:00 baseline huashu-proofreading - 78 baseline - 初始评估 full_test
2026-03-31T10:05 a1b2c3d huashu-proofreading 78 84 keep 边界条件 补充fallback full_test
2026-03-31T10:10 b2c3d4e huashu-proofreading 84 82 revert 指令具体性 过度细化 dry_run
新增 eval_mode 列:full_test(跑了子agent测试)或 dry_run(模拟推演)。
文件位置:.claude/skills/darwin-skill/results.tsv
4 条经实战验证(huashu-gpt-image +10.85 / huashu-weread-advisor +14.9 / claude-design +16.5)。详细案例数据见 references/skilllens-evidence.md 的「HL 实战案例」节。
按优先级排序,每轮只做最高优先级的一个:
Agent Skills Standard + skills.sh + Multi-Runtime 三个中立 badgexxx-codex)的,可跳过本项流程假设环境理想,但实操常遇异常。以下预定义 fallback,保证优化过程不会「一跑就卡住」。
| 场景 | 触发条件 | 处理动作 |
|---|---|---|
| 不在 git 仓库 | git rev-parse 失败 |
询问用户:执行 git init 或回退到文件备份;用户选后者则 cp SKILL.md SKILL.md.bak.YYYYMMDD-HHMM 代替 revert |
| results.tsv 缺失 | 文件不存在 | 新建并写表头行(9列:含 eval_mode) |
| results.tsv 损坏 | 列数不匹配 / 非TSV | 备份为 .bak.YYYYMMDD-HHMM 后重建,告知用户 |
| 分支已存在 | git checkout -b 失败 |
分支名末尾加 -2 / -3;第3次失败则切回现有分支并询问继续还是新起 |
git revert 失败 |
冲突 / 工作树脏 | 先 git stash,重试;仍失败则从上一个 commit 的 SKILL.md 读出覆盖当前文件手动恢复 |
| MAX_ROUNDS 触顶(默认3) | 已跑3轮仍有短板 | 不强制 break,展示当前最弱维度问用户「继续加1轮 / 进入Phase 2.5 / 收工」 |
| 优化后超 150% 体积 | 新文件 > 原 × 1.5 | 拒绝提交,回到改进步骤精简(删冗余/合并重复),再评 |
| test-prompts.json 已存在 | 文件已在 skill 目录 | 默认复用并展示,问用户「复用 / 重写 / 追加」三选一 |
| SKILL.md 找不到 | 目录存在但无 SKILL.md | 该 skill 终止,results.tsv 记 status=error,继续下一个 |
| 分数计算规则 | 浮点精度漂移 | 总分保留 1 位小数,改进需严格 > 旧分(不靠四舍五入) |
原则:异常先告知用户,再按规则处理;绝不静默跳过或静默失败。
来自本机 results.tsv 早期 40 次 0 revert 的教训 + Judge G/H 自指评估暴露的反模式。每条都是真实踩过的坑。
| # | 反模式 | 为什么不要做 | 替代做法 |
|---|---|---|---|
| 1 | 同 context 自评自改 | 改完后立刻在同一 Claude session 打分,会有「我刚改的肯定更好」乐观偏差(SkillLens 实证 LLM-as-judge 准确率仅 46.4%) | 必须 spawn 独立子 agent 评分,且至少 2 个 judge 共识才信 |
| 2 | git reset --hard 当回滚 |
会丢工作树未提交改动;CI 历史断裂 | 用 git revert HEAD 创建反向 commit,保留可追溯链 |
| 3 | 为凑分增冗余 | 触顶后继续硬改往往是「加废话/加段落让 LLM 觉得更详细」,实际质量不变 | 触顶信号(连续 2 轮 Δ<2 分)→ break 进 Phase 3,见好就收 |
| 4 | 跳过 test-prompts 直接评分 | 没有 test-prompts 的 dim8 是凭空打分,权重 23% 等于编造 | Phase 0.5 强制设计 2-3 prompts;若用户不给,默认编 3 个并展示确认 |
| 5 | 轮内改多个维度 | 多变量同时变,分数升降无法归因到具体改动 | 每轮 1 个维度;相关簇(dim2/3/4)改其一时观察另两个是否跟涨 |
| 6 | dry_run 比例 > 30% | dim8 实测维度形同虚设,分数虚高(早期 40 次记录 67% dry_run,0 revert) | 强制至少 1 个真实 full_test;dry_run 多的优化在 results.tsv 显式打 ⚠️ |
| 7 | 静默跳过异常 | 遇到 git/tsv 异常时静默继续,破坏 ratchet 完整性 | 异常表 10 条 fallback 必须先告知用户再处理 |
| 8 | 忽视维度相关性单独优化 | dim2/3/4 是相关簇,单独优化 dim2 时常发现已被前轮 dim3 修复推到顶 | 找最低维度时同时看相关簇短板,决定是否同步改 |
触发场景:每轮 Phase 2 改动前对照本表一次。任一反模式命中 → 改方案重写。
xxx-codex、huashu-slides-codex),任何「在 Claude Code 里」「Claude Code skill」「单一 badge 钉死」「安装命令只给 .claude/skills/ 一种路径」都视为 gate 不通过,须在 P0 优先修复(详见「Runtime 适配性审查」章节)用户:"优化所有skills"
→ Phase 0-3 完整流程
→ 默认:先基线评估,按分数升序优先优化最低 5-10 个
用户:"优化 huashu-slides 这个skill"
→ 只对指定skill执行 Phase 0.5-2
用户:"评估所有skills的质量"
→ 只执行 Phase 0.5-1(设计测试prompt + 基线评估),不进入优化循环
用户:"看看skill优化历史"
→ 读取并展示 results.tsv
"You write the goals and constraints in program.md; let an agent generate and test code deltas indefinitely; keep only what measurably improves the objective." — Karpathy, autoresearch
本skill的对应关系:
区别:增加了人在回路(autoresearch是全自主的,skill优化需要人的判断力),以及双重评估机制(结构+效果),因为skill的「好坏」比loss数值更微妙。
每个skill优化完成后(或全量汇总后),自动生成视觉成果卡片,截图保存为PNG。
模板位置:templates/result-card.html
3种风格,每次随机选择一种:
| 风格 | CSS类 | URL hash | 视觉特点 |
|---|---|---|---|
| Warm Swiss | .theme-swiss |
#swiss |
暖白底+赤陶橙,Inter字体,干净网格 |
| Dark Terminal | .theme-terminal |
#terminal |
近黑底+荧光绿,等宽字体,扫描线 |
| Newspaper | .theme-newspaper |
#newspaper |
暖白纸+深红,衬线字体,双栏编辑风 |
```
用 scripts/screenshot.mjs 截图(2x 高清,只截 .card 元素,自动 open 图片): node .claude/skills/darwin-skill/scripts/screenshot.mjs \ /abs/path/to/card.html /abs/path/to/output.png
npx playwright screenshot "file:///path/to/card.html#[theme]" \ output.png --viewport-size=960,1280 --wait-for-timeout=2000
提示用户查看成果卡片 PNG
| 路径 | 用途 |
|---|---|
templates/result-card.html |
3风格主模板(swiss/terminal/newspaper,hash切换) |
templates/result-card-dark.html / -white.html |
单一风格替代模板(需要锁定风格时用) |
scripts/screenshot.mjs |
2x 高清截图,只截 .card,自动 open |
results.tsv |
历次优化日志(9列含 eval_mode) |
{skill目录}/test-prompts.json |
每个 skill 的测试 prompt 集(用于维度8实测) |