Claude Skill

darwin-skill

Darwin Skill 2.0 (达尔文.skill 2.0): autonomous skill optimizer, v2.0 integrates Microsoft Research SkillLens (arXiv 2605.23899) 9-dim rubric + SkillOpt (arXiv 2605.23904) validation-gated design + human-in-the-loop checkpoints. Evaluates SKILL.md files using a 9-dimension rubric (s

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download kingxiaozhe-cm-workflow-skills_darwin-skill-3f79f65.zip · 37 KB

kingxiaozhe/cm-workflow 27 0 forks MIT Updated 1d ago

Part of kingxiaozhe/cm-workflow — 24 skills

Install

skills CLI npx skills add https://github.com/kingxiaozhe/cm-workflow/tree/main/skills/darwin-skill

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kingxiaozhe-cm-workflow@llmmart

Git git clone https://github.com/kingxiaozhe/cm-workflow.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kingxiaozhe/cm-workflow collection as a plugin from our marketplace. Git is the plain clone.

README

English | 中文

Darwin Skill Animation
_{动画由 huashu-design skill 制作}

达尔文.skill 2.0

像训练模型一样优化你的 Agent Skills。

受 Andrej Karpathy 的 autoresearch 启发，将自主实验循环从模型训练搬到 Skill 优化领域。一个只能向前转的棘轮。

v2.0 · 更新于 2026-05-28 · 吸收微软研究院 SkillLens 与 SkillOpt 两篇论文做的系统性升级。

npx skills add alchaincyf/darwin-skill

Note

🤝 微软研究院把达尔文列进了 SkillOpt 的官方集成名单。 2026-06-03，微软在 SkillOpt 仓库的更新里写道： 「gbrain, gbrain-evals, and darwin-skill have all integrated SkillOpt.」 我们吸收了它的 validation-gated 框架，它把达尔文写进了自己的集成名单。这是一次双向的致意。👉 去 SkillOpt 仓库看看

What's New in 2.0

2.0 不是缝缝补补，是系统性吸收微软研究院 2026-05-22 两篇论文后的结构性升级。五个变化：

1. 评分标准 8 维 → 9 维（吸收 SkillLens 实证的 73.8% rubric 药方）

原「错误处理」维度升级为 失败模式编码 (Failure Mechanism Encoding)：不只是「告诉 agent 别犯错」，而是把已知失败路径显式编码进 skill
原「明确性」维度升级为 可执行具体性 (Actionable Specificity)：明文禁止「建议/可以考虑/根据情况/灵活把握/视情况而定」等模糊词
新增第九维 高风险行动黑名单 (High-Risk Action Blacklist)：rm/git reset --hard/force push 等破坏性操作必须在 skill 中显式列禁

2. 验证机制对齐 SkillOpt 的 validation-gated 设计

多评委独立审查：每轮启动 2 个独立评委
评委不复用：下一轮启动全新评委，避免锚定效应
早停机制：单轮涨幅 < 1 分自动停手，避免凑分堆冗余
干跑模式控制：干跑比例 > 30% 自动告警

3. Human in the Loop 三层守关（达尔文区别于 SkillOpt 全自动设计的核心）

Phase 1 基线评估：自动 + 人工审报告，决定改什么
Phase 2 单维度优化：🔴 CHECKPOINT 强制暂停，等用户确认
Phase 2.5 测试提示词跑（可选）
Phase 3 回归测试：🛑 STOP 涨幅低于阈值强制停手

4. 反例黑名单 8 条（明文禁止的反模式）

同一个 AI 又改又评（SkillLens 实证：LLM 自评准确率仅 46.4%）
用 git reset --hard 当回滚手段（应用 git revert）
为凑分而堆冗余
跳过测试提示词直接评分
一轮内改多个维度
干跑比例 > 30%
静默跳过异常
忽视维度相关簇

5. 实测验证数据

huashu-gpt-image skill：80.8 → 91.5 → 91.65（+10.85，6 个独立评委共识）
darwin-skill 自评：86.05 → 92.05 → 92.7

核心循环

Core Loop

为什么做这个

Agent Skill 生态在快速扩张。Claude Code、Codex、OpenClaw、Trae、CodeBuddy 等工具都支持 SKILL.md 格式。当你有 10 个 Skills 时可以手动维护；当你有 60+ 个 Skills 时，你需要一个系统。

传统的 Skill 审查是纯结构性的：检查格式对不对、步骤有没有编号、路径能不能访问。但一个格式完美的 Skill，跑出来的效果可能很差。

达尔文.skill 同时评估结构质量和实际效果，然后只保留真正有改进的修改。

从 autoresearch 到 Skill Optimizer

这个项目直接受 Karpathy autoresearch 启发。autoresearch 的做法是：写一个 program.md 定义目标和约束，让 agent 自主生成和测试代码变更，只保留可测量的改进。

我们把同样的思路搬到了 Skill 优化：

autoresearch	达尔文.skill	为什么这样映射
`program.md`	本 SKILL.md	定义评估标准和约束规则
`train.py`	每个待优化的 SKILL.md	被优化的资产，每次实验只改它
`val_bpb`	9 维加权总分（满分 100）	可量化的优化目标
`git ratchet`	keep / revert 机制	只保留有改进的 commit
`test set`	test-prompts.json	验证改进是否真的有效
全自主运行	人在回路	Skill 的好坏比 loss 更微妙，需要人的判断

五条核心原则

#	原则	说明
01	单一可编辑资产	每次只改一个 SKILL.md，变量可控，改进可归因
02	双重评估	结构评分（静态分析）+ 效果验证（跑测试看输出）
03	棘轮机制	只保留改进，自动回滚退步，分数只升不降
04	独立评分	评分用子 agent，避免「自己改自己评」的偏差（SkillLens 实证 LLM 自评仅 46.4% 准确率）
05	人在回路	每个 Skill 优化完后暂停，用户确认再继续下一个

9 维度评估体系

总分 100。结构维度靠静态分析，效果维度必须实测。v2.0 新增三个维度直接来自 SkillLens 论文的实证 rubric。

Evaluation Rubric

新增的三个维度（SkillLens 73.8% rubric 药方）：

维度	说明
失败模式编码	显式编码已知失败路径，不是简单「别犯错」式叮嘱
可执行具体性	禁用「建议/可以考虑/根据情况/灵活把握/视情况而定」等模糊措辞
高风险行动黑名单	rm / git reset --hard / force push 等破坏性操作必须明文列禁

实测表现权重最高。Skill 写得再漂亮，跑出来效果不好就是零。

优化循环：5 个阶段

系统在每个阶段内自主运行，但在阶段之间暂停等待人类确认。

Optimization Lifecycle

Phase 2 的核心逻辑（v2.0 强化）：

找出得分最低的维度
针对该维度生成 1 个具体改进方案（一轮只改一个维度，反例黑名单第 5 条）
编辑 SKILL.md，git commit
启动 2 个独立子 agent 重新评分（下一轮换全新评委，避免锚定）
新分 > 旧分 → 保留；否则 → git revert（禁用 git reset --hard，反例黑名单第 2 条）
单轮涨幅 < 1 分 → 自动早停（避免凑分堆冗余）
🔴 CHECKPOINT 暂停，展示 diff + 分数变化，等用户确认

棘轮机制

分数只能上升。每一轮要么改进 Skill，要么干净地回滚。不会随时间积累局部退化。

Ratchet Mechanism

轮次 2 的 75 分低于当前最优的 78 分，被自动回滚。有效基线始终锁定在 78，后续改进从 78 继续。

快速开始

npx skills add alchaincyf/darwin-skill

安装后在任何支持 Skill 的 Agent 工具中说「优化所有skills」或「优化某个skill」就行。

无法访问 GitHub 的朋友，可以直接下载 zip 包：darwin-skill.zip，解压后把 SKILL.md 放到 ~/.claude/skills/darwin-skill/ 目录即可。

设计灵感

这个项目的设计直接受 Andrej Karpathy 的 autoresearch 启发。

核心机制完全相同：只保留可测量的改进，其余全部回滚。

v2.0 在此基础上吸收了微软研究院 2026-05-22 发布的两篇论文：SkillLens 提供了实证验证的 rubric 设计，SkillOpt 提供了 validation-gated edits 的形式化框架。

References & Credits

v2.0 的设计直接基于以下学术工作。强烈推荐 skill 生态的研究者和工程师阅读：

SkillLens

Microsoft Research. From Raw Experience to Skill Consumption: A Systematic Study of Model-Generated Agent Skills. arXiv:2605.23899, 2026.

论文：https://arxiv.org/abs/2605.23899
贡献：实证验证的 73.8% rubric 药方。达尔文.skill v2.0 的三个新维度（Failure Mechanism Encoding / Actionable Specificity / High-Risk Action Blacklist）直接来自该论文。同时也是「同一个 AI 又改又评」反模式的实证来源——LLM 自评准确率仅 46.4%。

SkillOpt

Microsoft Research. SkillOpt: Executive Strategy for Self-Evolving Agent Skills. arXiv:2605.23904, 2026.

🔗 代码仓库：github.com/microsoft/SkillOpt（pip install skillopt，v0.1.0 已上 PyPI）
项目页：https://microsoft.github.io/SkillOpt/
论文：https://arxiv.org/abs/2605.23904
贡献：validation-gated edits 的形式化框架。把 skill 当作 frozen 模型的「外部可训练状态」，每次编辑都必须通过独立验证才能保留。达尔文.skill v2.0 的多评委独立审查、评委不复用、早停机制、干跑比例控制都对齐了该框架。
🤝 双向印证：2026-06-03，SkillOpt 官方仓库把 darwin-skill 写进了集成名单，原文是 "gbrain, gbrain-evals, and darwin-skill have all integrated SkillOpt." 它给我们框架，我们给它实战验证。

autoresearch

Andrej Karpathy. autoresearch. GitHub repository, 2026.

代码：https://github.com/karpathy/autoresearch
贡献：达尔文.skill 1.0 的原始灵感来源。核心机制（program.md / train.py / val_bpb / git ratchet / test set）的映射逻辑完全继承自 autoresearch。

达尔文 vs SkillOpt 的关键区别：SkillOpt 是全自主系统，达尔文.skill 强调 human-in-the-loop——Skill 的好坏比 validation loss 更微妙，关键阶段（基线评估、单维度优化、回归测试）强制暂停，让人来做最终判断。

关于作者


🌐 官网	bookai.top · huasheng.ai
𝕏 Twitter	@AlchainHust
📺 B站	花叔
▶️ YouTube	@Alchain
📕 小红书	花叔
💬 公众号	微信搜「花叔」

许可证

MIT

女娲造 Skill。
达尔文 让 Skill 进化。

只保留改进，时间就站在你这边。

MIT License © 花叔 Huashu

_{作者的其他项目 · also by 花叔}

Skill manifest

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

单一可编辑资产 — 每次只改一个 SKILL.md
双重评估 — 结构评分（静态分析）+ 效果验证（跑测试看输出）
棘轮机制 — 只保留改进，自动回滚退步
独立评分 — 评分用子agent，避免「自己改自己评」的偏差
人在回路 — 每个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

关于「实测表现」维度

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

为每个skill设计2-3个典型用户prompt（不是边缘case，是最常见的使用场景）
用子agent执行：一个带skill跑，一个不带skill跑（baseline）
对比输出质量，从以下角度打分：
- 输出是否完成了用户意图？
- 相比不带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>/dev/null

输出非空 = 红灯命中 → 强制把 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	静默跳过异常	遇到 git/tsv 异常时静默继续，破坏 ratchet 完整性	异常表 10 条 fallback 必须先告知用户再处理
8	忽视维度相关性单独优化	dim2/3/4 是相关簇，单独优化 dim2 时常发现已被前轮 dim3 修复推到顶	找最低维度时同时看相关簇短板，决定是否同步改

触发场景：每轮 Phase 2 改动前对照本表一次。任一反模式命中 → 改方案重写。

约束规则

不改变skill的核心功能和用途 — 只优化"怎么写"和"怎么执行"，不改"做什么"
不引入新依赖 — 不添加skill原本没有的scripts或references文件
每轮只改一个维度 — 避免多个变更导致无法归因
保持文件大小合理 — 优化后SKILL.md不应超过原始大小的150%
尊重花叔风格 — 中文为主、简洁为上
可回滚 — 所有改动在git分支上，用git revert而非reset --hard
评分独立性 — 效果维度必须用子agent或至少干跑验证，不能在同一上下文里「改完直接评」
Runtime 中立性 — skill 必须能在 Claude Code、Codex、Cursor、OpenClaw、Hermes 等任何 skills-compatible runtime 中正常运行。除非 skill 名明确绑定单一 runtime（如 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的对应关系：

program.md → 本文件（评估rubric和约束规则）
train.py → 每个SKILL.md
val_bpb → 9维加权总分（含实测表现 + meta-skill 反例黑名单）
git ratchet → 只保留有改进的commit
test set → 每个skill的test-prompts.json

区别：增加了人在回路（autoresearch是全自主的，skill优化需要人的判断力），以及双重评估机制（结构+效果），因为skill的「好坏」比loss数值更微妙。

学术依据 & Credits

SkillLens（arXiv 2605.23899）：9 维 rubric 的实证来源（LLM 自评 46.4% → 加 meta-skill 三维度后 73.8%）。
SkillOpt（arXiv 2605.23904）：validation-gated edits 形式化框架。代码 github.com/microsoft/SkillOpt（pip install skillopt）、项目页 microsoft.github.io/SkillOpt。🤝 2026-06-03 微软官方仓库已把 darwin-skill 列入集成名单。
autoresearch：github.com/karpathy/autoresearch，本 skill 1.0 的原始灵感。

成果卡片生成（Result Card）

每个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`	暖白纸+深红，衬线字体，双栏编辑风

生成流程

1. 复制 templates/result-card.html 到临时工作文件
2. 用 sed/编辑工具 替换占位数据：
   - data-field="skill-name" → 实际skill名
   - data-field="score-before/after/delta" → 实际分数
   - 9个维度的 dim-bar-before/after width → 实际百分比（若模板仍是旧 8 维布局，加一行 dim9 反例黑名单条目）
   - data-field="improvement-1/2/3" → 实际改进摘要
   - data-field="date" → 当前日期
3. 随机选择风格：hash 设为 swiss/terminal/newspaper 之一
4. 用 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
5. 提示用户查看成果卡片 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实测） |

### 何时生成

- **单skill卡片**：每个skill优化完成后，展示该skill的分数变化
- **总览卡片**：全部优化完成后（Phase 3），展示全局战绩

### 品牌元素

- 顶部：Darwin.skill 品牌标识 + 日期
- 底部：「Train your Skills like you train your models」+ github.com/alchaincyf/darwin-skill

Files (cm-workflow)

references

runtime-neutrality.md 3.9 KB

# Runtime 适配性审查（详细对照表 + 扫描命令）

> SKILL.md 在「Runtime 适配性审查」章节会引用本文件。Phase 1 基线评估时跑红灯扫描需要查这里。

---

## 背景

花叔的 skills 基于 Anthropic 开放的 [Agent Skills](https://agentskills.io) 协议，应当能在 Claude Code、Codex、Cursor、OpenClaw、Hermes Agent、CodeBuddy、Workbuddy、Gemini CLI、OpenCode 等 50+ skills-compatible runtime 上通用。

这是 skill 分发力的根本——一个被误判为「单一 runtime 绑定」的 skill，会被其他 agent 直接拒绝安装（实例：nuwa-skill 因 README 写「在 Claude Code 里使用」被 Marvis agent 拒绝）。

**适用范围**：除非 skill 名字明确声明绑定单一 runtime（如 `huashu-slides-codex`、`xxx-for-claude-code`），所有 skill 必须通过本审查。

---

## 红灯信号（出现即扣分，必须在 P0 优化轮修复）

| 红灯类型 | 典型表现 | 危害 |
|---|---|---|
| Badge 钉死 | `[![Claude Code Skill]]`、`[![Cursor Only]]` 之类的单一 runtime badge | 视觉上首屏定调，其他 runtime 用户直接退出 |
| 措辞钉死 | 「在 Claude Code 里」「Cursor 用户可以」「Codex 中使用」「Claude Code skill」 | 让 agent 解析时误判为"不是给我用的" |
| 安装命令钉死 | 只给 `~/.claude/skills/` 路径、只给 `/plugin install`、只给某 runtime 私有 CLI | 不知道这是 Claude Code 命令的 agent 会拒绝 |
| 工具调用钉死 | 工作流里硬编码 `mcp__claude-in-chrome__*`、`PostToolUse hook` 等单 runtime 能力，且不给替代方案 | 其他 runtime 没这些工具 → 流程跑不通 |
| 路径硬编码 | `~/.claude/skills/xxx/`、`.claude/agents/yyy` 作为唯一路径 | 其他 runtime 用 `~/.cursor/skills/` `~/.codex/skills/` |

---

## 绿灯措辞（推荐改写）

| 红灯 | 绿灯 |
|---|---|
| "在 Claude Code 里" | "在你的 agent 里" / "在任何 skills-compatible runtime 中" |
| "Claude Code skill" | "Agent Skill" |
| "Claude Code 用户" | "skills-aware agent 用户" |
| 单一 badge 钉死 | `Agent Skills Standard` + `skills.sh Compatible` + `Multi-Runtime` 三个中立 badge |
| 只给 `npx skills add ...` 一行 | 三层结构：① 自动检测的一行命令 ② 折叠展开的各 runtime 手动路径 ③ 「作为参考资料 cat 进 context」fallback |
| 工具名硬编码 | "用一个 browser automation 工具（例如 Claude 的 chrome MCP、Playwright 等）" |

---

## 例外清单（允许的「Claude Code 痕迹」）

不是所有 Claude-Code 相关字符都要清除。下面这些是**正当出现**的，不算红灯：

1. **Frontmatter `description` 里的中英文触发词**——这是 skill 入口，其他 runtime 解析 frontmatter 时同样能匹配
2. **花叔生态内部联动的 skill 名引用**——如「调用 huashu-design」「跟 darwin-skill 配套」
3. **明确标注的 runtime-specific 章节**——如「### 仅 Claude Code 优化（按需触发）」+ 解释清楚是 nice-to-have
4. **commit message、changelog、内部脚本**——不属于用户读到的 skill 内容

---

## 审查时机

- **Phase 1 基线评估时**：每个 skill 跑一次红灯扫描，命中项以 `runtime_warn=N` 形式写入 results.tsv 的 `note` 列（不新增列、保持向后兼容）
- **Phase 2 优化循环时**：红灯命中数 ≥ 1 的 skill，强制把第一轮优化方向定为 P0「runtime drift 修复」（详见 SKILL.md 优化策略库的 P0 章节），优先于其他维度
- **Phase 3 汇总报告时**：单独一栏「runtime 中立度」展示修复进度（命中数从 X → 0）

---

## 红灯扫描快速命令

```bash
# 在 skill 目录跑这个 grep，输出即红灯命中
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
```

输出非空 = 该 skill 未通过 gate，必须在优化循环里修复。

skilllens-evidence.md 6.5 KB

# SkillLens 实证基线 + darwin-skill 本机验证数据

> SKILL.md 在「评估 Rubric」章节会引用本文件。需要查论文细节、controlled study 数据、HL 实战案例的具体数字时读这里。

---

## SkillLens 论文实证（外部证据）

**论文**：From Raw Experience to Skill Consumption: A Systematic Study of Model-Generated Agent Skills
**作者**：Microsoft Research + 复旦大学 + 上海交大（16 作者）
**arXiv**：2605.23899（2026-05-22，与 SkillOpt 同期发布）
**实验规模**：5 domains（ALFWorld / SpreadsheetBench / SWE-bench-Verified / SEAL-0 / BFCL-v4）× 6 targets × 5 extractors

### 关键发现

1. **75% 案例 skill 有正收益，25% 出现 negative transfer**——即「加 skill 比不加还差」
2. **强 agent 不一定是好 extractor**（Gemini-3.1-FL 在 skill 提取效率上反超 GPT-5.4）
3. **LLM-as-judge 准确率仅 46.4%**——给 LLM judge 两份 skill，让它选哪份更好，**比扔硬币（50%）还差**
4. **meta-skill rubric 把准确率提升到 73.8%**——加入三个维度：
   - **Failure-mechanism encoding**（必须显式编码失败模式）
   - **Actionable specificity**（禁止"考虑/可能"软化措辞）
   - **Risk-action blacklist**（必须有反例清单）
5. 所有 domain 一致 +1.55pp 提升（meta-rubric 不是某个 domain 的特例）

### 对 darwin-skill 的意义

旧 8 维 rubric 全部由 LLM judge 打分 → 系统性乐观偏差 → 本机 results.tsv 早期 40 次 0 revert / 67% dry_run 印证。

v2 9 维 rubric 强化 dim3/dim5 + 新增 dim9 是 SkillLens 验证过的方向。**但即使 73.8%，每 4 次决策仍错 1 次——重要决策必须人审确认。**

---

## 本机 controlled study（2026-05-27）

### 实验设计

- **目标 skill**：huashu-research（170 行，独立度高）
- **V1**：当前 GitHub 仓库最新版（被 darwin-skill 优化过 +33 分的版本）
- **V2 (degraded)**：在 V1 基础上应用 4 类明确质量劣化：
  - **D1 模糊化具体指令**：「必须/立即」→「建议/可以根据情况」
  - **D2 删除关键检查点**：删掉 2 个 🔴 检查点
  - **D3 删掉异常处理表**：整段「## 异常处理」章节删除
  - **D4 插入 AI 腔废话**：在 Step 2、Step 3 插入花叔禁用词 9 个套话
- **5 个独立 judge agent**（general-purpose subagent，无 context 共享）盲测打分
- 一半 judge 先读 V1 后读 V2，另一半反序（去除位置偏差）

### 结果

| Judge | 顺序 | V1 总分 | V2 总分 | Δ | Verdict | Confidence |
|---|---|---|---|---|---|---|
| 1 | V1 → V2 | 89.5 | 41.7 | **+47.8** | V1>V2 | high |
| 2 | V2 → V1 | 90.2 | 46.7 | **+43.5** | V1>V2 | high |
| 3 | V1 → V2 | 89.5 | 37.6 | **+51.9** | V1>V2 | high |
| 4 | V2 → V1 | 89.5 | 48.4 | **+41.1** | V1>V2 | high |
| 5 | V1 → V2 | 89.5 | 41.4 | **+48.1** | V1>V2 | high |
| **均值** | — | **89.6** | **43.2** | **+46.5** | **5/5 V1>V2** | **5/5 high** |

### 维度级共识

| 维度 | V1 均值 | V2 均值 | Δ | 一致性 |
|---|---|---|---|---|
| 1. Frontmatter | 9.0 | 5.6 | -3.4 | 全部识别 |
| 2. 工作流清晰度 | 9.0 | 5.0 | -4.0 | 全部识别 |
| 3. 边界条件覆盖 | 9.2 | 3.4 | -5.8 | **最明显劣化** |
| 4. 检查点设计 | 9.0 | 2.6 | -6.4 | **最明显劣化** |
| 5. 指令具体性 | 9.0 | 3.6 | -5.4 | 全部识别 |
| 6. 资源整合度 | 8.0 | 6.8 | -1.2 | 弱 |
| 7. 整体架构 | 9.0 | 4.6 | -4.4 | 全部识别 |
| 8. 实测表现 | 9.0 | 3.6 | -5.4 | 全部识别 |

### 结论

**rubric 能识别 gross degradation（5/5 high confidence）**，但**这不能证明 fine-grained quality difference 也能识别**——SkillLens 的 46.4% 来自细粒度对比，darwin-skill 在细粒度判别上仍有失效风险。**重要决策仍需人审。**

---

## HL 实战 high-leverage 案例（来自 results.tsv 真实记录）

### HL-1：显性视觉标记是 dim4 的杠杆

**huashu-gpt-image Round 1**：红线 4 标题前加 🔴 CHECKPOINT + 「禁止交付」→「🛑 STOP」
- 改动：4 行
- dim4 变化：6.0 → 9.5（+3.5）
- 单维度 ROI：每行改动 +0.875 分

**huashu-slide-codex r4**：路径优先级章节插入 🔴🔴🔴 默认路径锁定铁律
- dim 总分 85 → 持平但避免了「Codex 自我合理化切 Path3 失败」实测翻车
- 视觉锚是 LLM 解析的关键信号

### HL-2：if-then 三段式 fallback 表

**huashu-gpt-image Round 1**：新增「🛟 失败模式与 fallback 树」章节
- 改动：3 张表 23 条三段式（触发条件 / 一线修复 / 仍失败兜底）
  - 单图失败 9 条
  - 批量生成 9 条
  - 生成执行层 5 条
- dim3 变化：6.5 → 10（满分）

**huashu-weread-advisor edit-r2**：SKILL 加 11 行全局异常表 + 4 行数据展示规范 + 4 工作流各加 5-6 行 workflow 特有异常表
- 共 ~33 个异常场景覆盖
- dim 总分 81.3 → 87.6（+6.3）

### HL-3：维度相关性（dim2/3/4 是相关簇）

**huashu-gpt-image 实测**：
- Round 1 攻 dim3（最低 6.5）→ 改成 10
- 同期 dim2 自动从 7.5 → 9（未单独优化）
- Round 2 试图单独攻 dim2 → 发现已触顶 9，多此一举
- **教训**：找最低维度时同时看相关簇短板

### HL-4：触顶后边际收益递减

**huashu-gpt-image Round 2**：+0.15 marginal
- Round 1: +10.7 分（基线 80.8 → 91.5）
- Round 2: +0.15 分（91.5 → 91.65）
- **触顶信号**：连续 2 轮 Δ < 2 → break，避免过度优化

**对比 darwin-skill 早期**：40 次记录 0 revert，部分是因为没有触顶规则，硬凑 MAX_ROUNDS=3 都 keep 了边际改动。

---

## 历史 results.tsv 优化记录摘要（截至 2026-05-27）

完整记录见 `results.tsv`。

| skill | 起分 | 终分 | Δ | 模式 |
|---|---|---|---|---|
| huashu-research | 40.0 | 73.2 | +33.2 | dry_run |
| huashu-video-check | 72.1 | 80.5 | +8.4 | dry_run |
| harness-optimizer | 78.4 | 86.0 | +7.6 | dry_run |
| freud-skill | 72.5 | 86.0 | +13.5 | dry_run |
| **claude-design** | **74.5** | **91.0** | **+16.5** | **full_test ✅** |
| huashu-design | 62.3 | 86.7 | +24.4 | dry_run |
| huashu-weread-advisor | 76.5 | 91.4 | +14.9 | full_test_informed ✅ |
| huashu-slide-codex | 82.6 | 85+ | +2~ | mixed |
| **huashu-gpt-image** | **80.8** | **91.65** | **+10.85** | **full_test ✅（v2 实战）** |
| **darwin-skill (self-fix)** | **86.05** | **92.05** | **+6.0** | **full_test ✅（自指闭环）** |

**统计**：
- 平均提升：~+13.5 分
- 全部 keep（v1 时代 0 revert 印证 rubric 偏松；v2 引入触顶 break 规则）
- full_test 比例：从 33% 提升到 100%（最近 2 次都是 full_test）

scripts
- screenshot.mjs 2.1 KB · in bundle
templates
- result-card-dark.html 17.4 KB · in bundle
- result-card-white.html 11 KB · in bundle
- result-card.html 15.5 KB · in bundle

NOTICE.md 2 KB

# 来源与许可

- 上游: https://github.com/alchaincyf/darwin-skill (master, 收编于 2026-07-15)
- 许可: MIT（上游 README 的“许可证”章节明确写 MIT，并保留
  “MIT License © 花叔 Huashu”署名；上游仓库收编时无独立 LICENSE 文件）
- 完整许可文本与仓库级归属: `../../LICENSE`、`../../THIRD_PARTY_NOTICES.md`
- 本地修改(仅 2 处,均为移植性修补,SKILL.md 未改一字):
  1. scripts/screenshot.mjs: playwright-core 改为标准解析(原版写死作者机器绝对路径)
  2. scripts/screenshot.mjs: open 命令加 macOS 平台判断(原版非跨平台)
- 定位: 独立工具 skill（同 codebase-context），不属于 N1-N8 流程;
  用途:对本仓库 skills/(含 cm-* 角色技能)做 9 维评分与受控优化,人类守关三层不可跳过

# 本仓库使用注意(v0.9.25-26 实跑沉淀,SKILL.md 原样未改,以下为运行时补丁规则)

1. **baseline 对照组必污染,勿用 A/B 对比**: 被测 skill 已装入会话的环境里,"不带 skill"
   的对照子 agent 会因任务措辞匹配 description 而通过 Skill 工具自行加载它(实测 3/3
   全污染;验证法: grep 子 agent transcript 中的 `"name":"Skill"` 调用)。dim8 改用两类
   证据: ① 执行者逐条报告"skill 没写清、不得不猜的地方",歧义清单收敛度=改进度;
   ② 夹具埋陷阱复测,看上轮违规行为是否被新规则挡住。
2. **9 维 rubric 需叠加本仓库四原则**: 通用 rubric 可能把"实跑教训括号注"判为冗余——
   它们在本仓库是防删护栏,评分时计入 dim5/dim7 加分项,优化时禁止删除。
3. **cm-* skill 是强耦合网络**: 每轮改动后必须跑引用护栏(/cm-check 相关子集:
   孤儿角色、rules 生成方、跨文件配对),PASSED 才算该轮有效——这是 darwin 棘轮
   之外的本仓库附加回滚条件。
4. **工程师类 skill 的 dim9 低分是架构使然**: 纪律按设计在 agents/*.md 层
   ("agent 管纪律,skill 管技术"),勿按 rubric 给其 SKILL.md 补黑名单。

README.md 11.5 KB

<div align="right">

**[English](README_EN.md)** | 中文

</div>

![达尔文.skill](assets/banner.svg)

<p align="center">
  <img src="assets/hero.gif" alt="Darwin Skill Animation" />
  <br/>
  <sub>动画由 <a href="https://github.com/alchaincyf/huashu-design">huashu-design</a> skill 制作</sub>
</p>

<div align="center">

# 达尔文.skill 2.0

**像训练模型一样优化你的 Agent Skills。**

受 [Andrej Karpathy 的 autoresearch](https://github.com/karpathy/autoresearch) 启发，将自主实验循环从模型训练搬到 Skill 优化领域。一个只能向前转的棘轮。

**v2.0** · 更新于 2026-05-28 · 吸收微软研究院 [SkillLens](https://arxiv.org/abs/2605.23899) 与 [SkillOpt](https://arxiv.org/abs/2605.23904) 两篇论文做的系统性升级。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.0-blue.svg)](#whats-new-in-20)
[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-Compatible-blueviolet)](https://skills.sh)
[![Skills](https://img.shields.io/badge/skills.sh-Compatible-green)](https://skills.sh)
[![Microsoft SkillOpt](https://img.shields.io/badge/Microsoft_SkillOpt-Listed_Integration-0078D4?logo=microsoft&logoColor=white)](https://github.com/microsoft/SkillOpt)

```
npx skills add alchaincyf/darwin-skill
```

</div>

---

> [!NOTE]
> **🤝 微软研究院把达尔文列进了 SkillOpt 的官方集成名单。**
> 2026-06-03，微软在 [SkillOpt 仓库](https://github.com/microsoft/SkillOpt) 的更新里写道：
> *「gbrain, gbrain-evals, and **darwin-skill** have all integrated SkillOpt.」*
> 我们吸收了它的 validation-gated 框架，它把达尔文写进了自己的集成名单。这是一次双向的致意。👉 [去 SkillOpt 仓库看看](https://github.com/microsoft/SkillOpt)

---

## What's New in 2.0

2.0 不是缝缝补补，是系统性吸收微软研究院 2026-05-22 两篇论文后的结构性升级。五个变化：

**1. 评分标准 8 维 → 9 维**（吸收 [SkillLens](https://arxiv.org/abs/2605.23899) 实证的 73.8% rubric 药方）

- 原「错误处理」维度升级为 **失败模式编码** (Failure Mechanism Encoding)：不只是「告诉 agent 别犯错」，而是把已知失败路径显式编码进 skill
- 原「明确性」维度升级为 **可执行具体性** (Actionable Specificity)：明文禁止「建议/可以考虑/根据情况/灵活把握/视情况而定」等模糊词
- 新增第九维 **高风险行动黑名单** (High-Risk Action Blacklist)：rm/git reset --hard/force push 等破坏性操作必须在 skill 中显式列禁

**2. 验证机制对齐 SkillOpt 的 validation-gated 设计**

- 多评委独立审查：每轮启动 2 个独立评委
- 评委不复用：下一轮启动全新评委，避免锚定效应
- 早停机制：单轮涨幅 < 1 分自动停手，避免凑分堆冗余
- 干跑模式控制：干跑比例 > 30% 自动告警

**3. Human in the Loop 三层守关**（达尔文区别于 SkillOpt 全自动设计的核心）

- Phase 1 基线评估：自动 + 人工审报告，决定改什么
- Phase 2 单维度优化：🔴 CHECKPOINT 强制暂停，等用户确认
- Phase 2.5 测试提示词跑（可选）
- Phase 3 回归测试：🛑 STOP 涨幅低于阈值强制停手

**4. 反例黑名单 8 条**（明文禁止的反模式）

1. 同一个 AI 又改又评（SkillLens 实证：LLM 自评准确率仅 46.4%）
2. 用 `git reset --hard` 当回滚手段（应用 `git revert`）
3. 为凑分而堆冗余
4. 跳过测试提示词直接评分
5. 一轮内改多个维度
6. 干跑比例 > 30%
7. 静默跳过异常
8. 忽视维度相关簇

**5. 实测验证数据**

- huashu-gpt-image skill：**80.8 → 91.5 → 91.65**（+10.85，6 个独立评委共识）
- darwin-skill 自评：**86.05 → 92.05 → 92.7**

---

## 核心循环

![Core Loop](assets/chart-loop.png)

---

## 为什么做这个

Agent Skill 生态在快速扩张。Claude Code、Codex、OpenClaw、Trae、CodeBuddy 等工具都支持 SKILL.md 格式。当你有 10 个 Skills 时可以手动维护；当你有 60+ 个 Skills 时，你需要一个系统。

传统的 Skill 审查是**纯结构性的**：检查格式对不对、步骤有没有编号、路径能不能访问。但一个格式完美的 Skill，跑出来的效果可能很差。

达尔文.skill 同时评估**结构质量**和**实际效果**，然后只保留真正有改进的修改。

---

## 从 autoresearch 到 Skill Optimizer

这个项目直接受 Karpathy autoresearch 启发。autoresearch 的做法是：写一个 `program.md` 定义目标和约束，让 agent 自主生成和测试代码变更，只保留可测量的改进。

我们把同样的思路搬到了 Skill 优化：

| autoresearch | 达尔文.skill | 为什么这样映射 |
|:---|:---|:---|
| `program.md` | 本 SKILL.md | 定义评估标准和约束规则 |
| `train.py` | 每个待优化的 SKILL.md | 被优化的资产，每次实验只改它 |
| `val_bpb` | 9 维加权总分（满分 100） | 可量化的优化目标 |
| `git ratchet` | keep / revert 机制 | 只保留有改进的 commit |
| `test set` | test-prompts.json | 验证改进是否真的有效 |
| 全自主运行 | **人在回路** | Skill 的好坏比 loss 更微妙，需要人的判断 |

---

## 五条核心原则

| # | 原则 | 说明 |
|:---|:---|:---|
| 01 | **单一可编辑资产** | 每次只改一个 SKILL.md，变量可控，改进可归因 |
| 02 | **双重评估** | 结构评分（静态分析）+ 效果验证（跑测试看输出） |
| 03 | **棘轮机制** | 只保留改进，自动回滚退步，分数只升不降 |
| 04 | **独立评分** | 评分用子 agent，避免「自己改自己评」的偏差（SkillLens 实证 LLM 自评仅 46.4% 准确率） |
| 05 | **人在回路** | 每个 Skill 优化完后暂停，用户确认再继续下一个 |

---

## 9 维度评估体系

总分 100。结构维度靠静态分析，效果维度必须实测。v2.0 新增三个维度直接来自 SkillLens 论文的实证 rubric。

![Evaluation Rubric](assets/chart-rubric.png)

新增的三个维度（SkillLens 73.8% rubric 药方）：

| 维度 | 说明 |
|:---|:---|
| **失败模式编码** | 显式编码已知失败路径，不是简单「别犯错」式叮嘱 |
| **可执行具体性** | 禁用「建议/可以考虑/根据情况/灵活把握/视情况而定」等模糊措辞 |
| **高风险行动黑名单** | rm / git reset --hard / force push 等破坏性操作必须明文列禁 |

> 实测表现权重最高。Skill 写得再漂亮，跑出来效果不好就是零。

---

## 优化循环：5 个阶段

系统在每个阶段内自主运行，但在阶段之间暂停等待人类确认。

![Optimization Lifecycle](assets/chart-phases.png)

**Phase 2 的核心逻辑**（v2.0 强化）：

1. 找出得分最低的维度
2. 针对该维度生成 1 个具体改进方案（一轮只改一个维度，反例黑名单第 5 条）
3. 编辑 SKILL.md，git commit
4. 启动 **2 个独立子 agent** 重新评分（下一轮换全新评委，避免锚定）
5. 新分 > 旧分 → 保留；否则 → `git revert`（禁用 `git reset --hard`，反例黑名单第 2 条）
6. 单轮涨幅 < 1 分 → 自动早停（避免凑分堆冗余）
7. 🔴 CHECKPOINT 暂停，展示 diff + 分数变化，等用户确认

---

## 棘轮机制

分数只能上升。每一轮要么改进 Skill，要么干净地回滚。不会随时间积累局部退化。

![Ratchet Mechanism](assets/chart-ratchet.png)

轮次 2 的 75 分低于当前最优的 78 分，被自动回滚。有效基线始终锁定在 78，后续改进从 78 继续。

---

## 快速开始

```bash
npx skills add alchaincyf/darwin-skill
```

安装后在任何支持 Skill 的 Agent 工具中说「优化所有skills」或「优化某个skill」就行。

无法访问 GitHub 的朋友，可以直接下载 zip 包：[darwin-skill.zip](https://pub-161ae4b5ed0644c4a43b5c6412287e03.r2.dev/skills/darwin-skill.zip)，解压后把 SKILL.md 放到 `~/.claude/skills/darwin-skill/` 目录即可。

---

## 设计灵感

这个项目的设计直接受 **Andrej Karpathy 的 [autoresearch](https://github.com/karpathy/autoresearch)** 启发。

核心机制完全相同：**只保留可测量的改进，其余全部回滚。**

v2.0 在此基础上吸收了微软研究院 2026-05-22 发布的两篇论文：[SkillLens](https://arxiv.org/abs/2605.23899) 提供了实证验证的 rubric 设计，[SkillOpt](https://arxiv.org/abs/2605.23904) 提供了 validation-gated edits 的形式化框架。

---

## References & Credits

v2.0 的设计直接基于以下学术工作。强烈推荐 skill 生态的研究者和工程师阅读：

### SkillLens

> Microsoft Research. *From Raw Experience to Skill Consumption: A Systematic Study of Model-Generated Agent Skills.* arXiv:2605.23899, 2026.

- 论文：https://arxiv.org/abs/2605.23899
- **贡献**：实证验证的 73.8% rubric 药方。达尔文.skill v2.0 的三个新维度（Failure Mechanism Encoding / Actionable Specificity / High-Risk Action Blacklist）直接来自该论文。同时也是「同一个 AI 又改又评」反模式的实证来源——LLM 自评准确率仅 46.4%。

### SkillOpt

> Microsoft Research. *SkillOpt: Executive Strategy for Self-Evolving Agent Skills.* arXiv:2605.23904, 2026.

- 🔗 **代码仓库**：[github.com/microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)（`pip install skillopt`，v0.1.0 已上 PyPI）
- 项目页：https://microsoft.github.io/SkillOpt/
- 论文：https://arxiv.org/abs/2605.23904
- **贡献**：validation-gated edits 的形式化框架。把 skill 当作 frozen 模型的「外部可训练状态」，每次编辑都必须通过独立验证才能保留。达尔文.skill v2.0 的多评委独立审查、评委不复用、早停机制、干跑比例控制都对齐了该框架。
- 🤝 **双向印证**：2026-06-03，SkillOpt 官方仓库把 darwin-skill 写进了集成名单，原文是 *"gbrain, gbrain-evals, and darwin-skill have all integrated SkillOpt."* 它给我们框架，我们给它实战验证。

### autoresearch

> Andrej Karpathy. *autoresearch.* GitHub repository, 2026.

- 代码：https://github.com/karpathy/autoresearch
- **贡献**：达尔文.skill 1.0 的原始灵感来源。核心机制（program.md / train.py / val_bpb / git ratchet / test set）的映射逻辑完全继承自 autoresearch。

**达尔文 vs SkillOpt 的关键区别**：SkillOpt 是全自主系统，达尔文.skill 强调 human-in-the-loop——Skill 的好坏比 validation loss 更微妙，关键阶段（基线评估、单维度优化、回归测试）强制暂停，让人来做最终判断。

---

## 关于作者

| | |
|:---|:---|
| 🌐 官网 | [bookai.top](https://bookai.top) · [huasheng.ai](https://www.huasheng.ai) |
| 𝕏 Twitter | [@AlchainHust](https://x.com/AlchainHust) |
| 📺 B站 | [花叔](https://space.bilibili.com/14097567) |
| ▶️ YouTube | [@Alchain](https://www.youtube.com/@Alchain) |
| 📕 小红书 | [花叔](https://www.xiaohongshu.com/user/profile/5abc6f17e8ac2b109179dfdf) |
| 💬 公众号 | 微信搜「花叔」 |

---

## 许可证

MIT

---

<div align="center">

**[女娲](https://github.com/alchaincyf/nuwa-skill)** 造 Skill。<br>
**达尔文** 让 Skill 进化。<br><br>
*只保留改进，时间就站在你这边。*

<br>

MIT License © [花叔 Huashu](https://github.com/alchaincyf)

</div>

---

<div align="center">
<sub>作者的其他项目 · also by 花叔</sub>

[![FanBox · Coding Agent 的驾驶舱](https://raw.githubusercontent.com/alchaincyf/fanbox/master/assets/promo-banner.jpg)](https://github.com/alchaincyf/fanbox)

</div>

SKILL.md 25.9 KB

---
name: darwin-skill
description: "Darwin Skill 2.0 (达尔文.skill 2.0): autonomous skill optimizer, v2.0 integrates Microsoft Research SkillLens (arXiv 2605.23899) 9-dim rubric + SkillOpt (arXiv 2605.23904) validation-gated design + human-in-the-loop checkpoints. Evaluates SKILL.md files using a 9-dimension rubric (structure + effectiveness + meta-skill blacklists), runs hill-climbing with git version control, spawns independent judge agents for blind evaluation, validates improvements through test prompts with auto-break on diminishing returns, and generates visual result cards. Use when user mentions \"优化skill\", \"skill评分\", \"自动优化\", \"auto optimize\", \"skill质量检查\", \"达尔文\", \"darwin\", \"帮我改改skill\", \"skill怎么样\", \"提升skill质量\", \"skill review\", \"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](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 基线评估时强制跑一次红灯扫描

```bash
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`）。

### 例外（允许的「Claude Code 痕迹」）

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

→ 红灯/绿灯完整对照表 + 例外清单详细规则 + Phase 1/2/3 各阶段审查时机见 [references/runtime-neutrality.md](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 格式

```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](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 | **静默跳过异常** | 遇到 git/tsv 异常时静默继续，破坏 ratchet 完整性 | 异常表 10 条 fallback 必须先告知用户再处理 |
| 8 | **忽视维度相关性单独优化** | dim2/3/4 是相关簇，单独优化 dim2 时常发现已被前轮 dim3 修复推到顶 | 找最低维度时同时看相关簇短板，决定是否同步改 |

**触发场景**：每轮 Phase 2 改动前对照本表一次。任一反模式命中 → 改方案重写。

---

## 约束规则

1. **不改变skill的核心功能和用途** — 只优化"怎么写"和"怎么执行"，不改"做什么"
2. **不引入新依赖** — 不添加skill原本没有的scripts或references文件
3. **每轮只改一个维度** — 避免多个变更导致无法归因
4. **保持文件大小合理** — 优化后SKILL.md不应超过原始大小的150%
5. **尊重花叔风格** — 中文为主、简洁为上
6. **可回滚** — 所有改动在git分支上，用git revert而非reset --hard
7. **评分独立性** — 效果维度必须用子agent或至少干跑验证，不能在同一上下文里「改完直接评」
8. **Runtime 中立性** — skill 必须能在 Claude Code、Codex、Cursor、OpenClaw、Hermes 等任何 skills-compatible runtime 中正常运行。除非 skill 名明确绑定单一 runtime（如 `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的对应关系：
- **program.md** → 本文件（评估rubric和约束规则）
- **train.py** → 每个SKILL.md
- **val_bpb** → 9维加权总分（含实测表现 + meta-skill 反例黑名单）
- **git ratchet** → 只保留有改进的commit
- **test set** → 每个skill的test-prompts.json

区别：增加了人在回路（autoresearch是全自主的，skill优化需要人的判断力），以及双重评估机制（结构+效果），因为skill的「好坏」比loss数值更微妙。

### 学术依据 & Credits

- **SkillLens**（arXiv [2605.23899](https://arxiv.org/abs/2605.23899)）：9 维 rubric 的实证来源（LLM 自评 46.4% → 加 meta-skill 三维度后 73.8%）。
- **SkillOpt**（arXiv [2605.23904](https://arxiv.org/abs/2605.23904)）：validation-gated edits 形式化框架。代码 [github.com/microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)（`pip install skillopt`）、项目页 [microsoft.github.io/SkillOpt](https://microsoft.github.io/SkillOpt/)。🤝 2026-06-03 微软官方仓库已把 darwin-skill 列入集成名单。
- **autoresearch**：[github.com/karpathy/autoresearch](https://github.com/karpathy/autoresearch)，本 skill 1.0 的原始灵感。

---

## 成果卡片生成（Result Card）

每个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` | 暖白纸+深红，衬线字体，双栏编辑风 |

### 生成流程

```
1. 复制 templates/result-card.html 到临时工作文件
2. 用 sed/编辑工具 替换占位数据：
   - data-field="skill-name" → 实际skill名
   - data-field="score-before/after/delta" → 实际分数
   - 9个维度的 dim-bar-before/after width → 实际百分比（若模板仍是旧 8 维布局，加一行 dim9 反例黑名单条目）
   - data-field="improvement-1/2/3" → 实际改进摘要
   - data-field="date" → 当前日期
3. 随机选择风格：hash 设为 swiss/terminal/newspaper 之一
4. 用 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
5. 提示用户查看成果卡片 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实测） |

### 何时生成

- **单skill卡片**：每个skill优化完成后，展示该skill的分数变化
- **总览卡片**：全部优化完成后（Phase 3），展示全局战绩

### 品牌元素

- 顶部：Darwin.skill 品牌标识 + 日期
- 底部：「Train your Skills like you train your models」+ github.com/alchaincyf/darwin-skill

Comments (0)

No comments yet.

Reviews (0)

No reviews yet.

Claude Prompt

Tighten-my-prose editing prompt

Claude Skill

Adversarial code-review skill for Claude

Claude Workflow

Deep-research workflow (fan-out + verify)

Claude Skill

Conventional-commit writer for Claude

darwin-skill

Install

README

达尔文.skill 2.0

What's New in 2.0

核心循环

为什么做这个

从 autoresearch 到 Skill Optimizer

五条核心原则

9 维度评估体系

优化循环：5 个阶段

棘轮机制

快速开始

设计灵感

References & Credits

SkillLens

SkillOpt

autoresearch

关于作者

许可证

Skill manifest

Darwin Skill 2.0

设计哲学

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

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

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

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

评分规则

Rubric 的实证基础

关于「实测表现」维度

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

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

例外（允许的「Claude Code 痕迹」）

自主优化循环

Phase 0: 初始化

Phase 0.5: 测试Prompt设计

Phase 1: 基线评估（Baseline）

Phase 2: 优化循环

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

Phase 3: 汇总报告

results.tsv 格式

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

优化策略库

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

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

P1: 结构性问题

P2: 具体性问题

P3: 可读性问题

异常与边界条件

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

约束规则

使用方式

全量优化（推荐首次使用）

单个优化

仅评估不改

查看历史

设计灵感

学术依据 & Credits

成果卡片生成（Result Card）

卡片模板

生成流程

Comments (0)

Reviews (0)

Related