darwin-skill

Darwin Skill 2.0

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 的精髓：

1. 单一可编辑资产 — 每次只改一个 SKILL.md
2. 双重评估 — 结构评分（静态分析）+ 效果验证（跑测试看输出）
3. 棘轮机制 — 只保留改进，自动回滚退步
4. 独立评分 — 评分用子 agent，避免“自己改自己评”的偏差
5. 人在回路 — 每个 skill 优化完后暂停，用户确认再继续

与纯结构审查的区别：不只看 SKILL.md 写得规不规范，更看改完后实际跑出来的效果是否更好。

---

评估 Rubric（9 维度，总分 100）

设计依据：基于 SkillLens 论文（arXiv 2605.23899）实证发现——LLM-as-judge 评估 skill 质量准确率仅 46.4%（接近随机），加入 meta-skill 三维度后提升到 73.8%。本 rubric 强化 dim3 / dim5 评分标准，新增 dim9“反例与黑名单”，权重平衡到 100。目的：让评分对真实质量更敏感，减少 LLM judge 的乐观偏差。

结构维度（59分）— 静态分析

#	维度	权重	评分标准
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 引用正确、路径可达

效果维度（35分）— 需要实测

#	维度	权重	评分标准
7	整体架构	12	结构层次清晰、不冗余不遗漏、与花叔生态一致；冗余/AI 腔废话段落（说白了/换句话说/首先其次综上等花叔禁用词）出现一处扣 1 分
8	实测表现	23	用测试 prompt 跑一遍，输出质量是否符合 skill 宣称的能力

Meta-skill 维度（6分）— 反例与黑名单

#	维度	权重	评分标准
9	反例与黑名单	6	skill 必须有“不要做什么”的反例清单；只写“应该做 X”没有“不要做 Y”扣 ≥3 分；红灯/危险动作/反模式应单独章节列出（SkillLens risk-action blacklist 维度）

评分规则

• 维度 1-7、9：每个维度打 1-10 分，乘以权重得到该维度得分
• 维度 8（实测表现）：跑 2-3 个测试 prompt，按输出质量打 1-10 分
• 总分 = Σ(维度分 × 权重) / 10，满分 100
• 改进后总分必须 严格高于 改进前才保留

Rubric 的实证基础

rubric 设计依据来自 SkillLens 论文（arXiv 2605.23899） + 本机 controlled study：

• SkillLens 发现 LLM-as-judge 准确率仅 46.4%（接近随机），加入 meta-skill 三维度后升到 73.8%
• 本机对 huashu-research 做 4 类 degradation → 5 个独立 judge 盲测一致 V1>V2，Δ 均值 +46.5（5/5 high confidence）

结论：rubric 能识别 gross degradation，但 fine-grained quality difference 仍不可信，重要决策必须人审。

→ 详细论文证据 + 5 judges 完整数据 + HL 实战案例数字见 references/skilllens-evidence.md

关于“实测表现”维度

这是与纯结构评分最大的区别。评分方式：

1. 为每个 skill 设计 2-3 个典型用户 prompt（不是边缘 case，是最常见的使用场景）
2. 用子 agent 执行：一个带 skill 跑，一个不带 skill 跑（baseline）
3. 对比输出质量，从以下角度打分：
   • 输出是否完成了用户意图？
   • 相比不带 skill 的 baseline，质量提升明显吗？
   • 有没有 skill 引入的负面影响（过度冗余、跑偏、格式奇怪）？

若子 agent 不可用（超时/资源限制），退化为“干跑验证”：读完 skill 后模拟一个典型 prompt 的执行思路，判断流程是否合理；必须在 results.tsv 标注 dry_run。dry_run 比例 > 30% → 评估失效警告（来自本机 controlled study：dim8 实测维度权重 23%，无 full_test 验证时分数不可信）。

---

Runtime 适配性审查（gate 项，独立于 9 维度评分）

skill 应当能在 Claude Code / Codex / Cursor / OpenClaw / Hermes / Gemini CLI / OpenCode 等 50+ skills-compatible runtime 通用——否则其他 agent 解析时会被“在 Claude Code 里”“Claude Code skill”等措辞误判为“不是给我用的”直接拒装（实例：nuwa-skill 因此被 Marvis agent 拒绝）。

Phase 1 基线评估时强制跑一次红灯扫描

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>/devnull

输出非空 = 红灯命中 → 强制把 Phase 2 第一轮定为 P0“runtime drift 修复”（写入 results.tsv 的 note 列 runtime_warn=N）。

例外（允许的“Claude Code 痕迹”）

frontmatter 触发词、花叔生态内部 skill 名引用、明确标注 runtime-specific 章节、commit message——这些正当出现，不算红灯。

→ 红灯/绿灯完整对照表 + 例外清单详细规则 + Phase 1/2/3 各阶段审查时机见 references/runtime-neutrality.md

---

自主优化循环

Phase 0: 初始化

1. 确认优化范围：
   - 全部 skills → 扫描 .claude/skills/*/SKILL.md
   - 指定 skills → 用户指定列表
2. 创建 git 分支：auto-optimize/YYYYMMDD-HHMM
3. 初始化 results.tsv（如不存在）
4. 读取现有 results.tsv 了解历史优化记录

Phase 0.5: 测试 Prompt 设计

在评估之前，为每个 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 的质量决定了优化方向是否正确。

Phase 1: 基线评估（Baseline）

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：暂停等用户确认，再进入优化循环。

Phase 2: 优化循环

用户确认后，按基线分数从低到高排序，先优化最弱的。

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 的优化前版本。

Phase 2.5: 探索性重写（按需触发）

当 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：必须征得用户同意后才执行。

Phase 3: 汇总报告

## 优化报告

### 总览
- 优化 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 对比优势增大

---

results.tsv 格式

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

---

实战 high-leverage 操作（精髓速查）

4 条经实战验证（huashu-gpt-image +10.85 / huashu-weread-advisor +14.9 / claude-design +16.5）。详细案例数据见 references/skilllens-evidence.md 的“HL 实战案例”节。

• HL-1（dim4）显性视觉标记是杠杆：加 🔴 CHECKPOINT / 🛑 STOP，靠“必须”措辞不行——LLM 解析时扫描视觉标记。4 行改动撬动 dim4 +3 分
• HL-2（dim3）if-then 三段式 fallback 表：把“症状/解法”两列升级为“触发条件 / 一线修复 / 仍失败兜底”三段式。SkillLens failure-mechanism encoding 维度的落地
• HL-3（Phase 2 诊断）维度相关簇警告：dim2/3/4 是相关簇——修 dim3 时 dim2 常跟着涨。“找最低维度”时同时看相关簇短板再决定是否同步改
• HL-4（Phase 2 退出）触顶自动 break：连续 2 轮 Δ < 2 分 → break 进 Phase 3。+0.15 是停手信号不是继续信号；硬凑 MAX_ROUNDS=3 引入 over-engineering

---

优化策略库

按优先级排序，每轮只做最高优先级的一个：

P0: Runtime 适配性问题（gate 项命中 → 必须先修）

• README/SKILL.md 出现红灯措辞（如“在 Claude Code 里”“Claude Code skill”）→ 替换为 runtime-neutral 措辞
• Badge 钉死单一 runtime → 改为 Agent Skills Standard + skills.sh + Multi-Runtime 三个中立 badge
• 安装章节只给一种 runtime 的路径 → 改为“一行命令（auto-detect）+ 手动路径表 + 作为参考资料”三层结构
• 工作流硬编码 runtime-specific 工具且无 fallback → 给出通用替代方案或标注“仅在某 runtime 可用”
• 例外：skill 名明确标注单 runtime（如 xxx-codex）的，可跳过本项

P0: 效果问题（实测发现的）

• 测试输出偏离用户意图 → 检查 skill 是否有误导性指令
• 带 skill 比不带还差 → skill 可能过度约束，考虑精简
• 输出格式不符合预期 → 补充明确的输出模板

P1: 结构性问题

• Frontmatter 缺少触发词 → 补充中英文触发词
• 缺少 Phase/Step 结构 → 重组为线性流程
• 缺少用户确认检查点 → 在关键决策处插入

P2: 具体性问题

• 步骤模糊（“处理图片”）→ 改为具体操作和参数
• 缺少输入/输出规格 → 补充格式、路径、示例
• 缺少异常处理 → 补充“如果 X 失败，则 Y”

P3: 可读性问题

• 段落过长 → 拆分+用表格
• 重复描述 → 合并去重
• 缺少速查 → 添加 TL;DR 或决策树

---

异常与边界条件

流程假设环境理想，但实操常遇异常。以下预定义 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 位小数，改进需严格 > 旧分（不靠四舍五入）

原则：异常先告知用户，再按规则处理；绝不静默跳过或静默失败。

---

darwin 操作反例黑名单（dim9 应用：darwin 自己优化时不要做的事）

来自本机 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