darwin-skill

Darwin Skill 2.0

v2.1 · 2026-06-10 — keep/revert ラチェットを「絶対スコアの delta」から「paired 同一 judge による比較 + 奇数 N の多数決」に変更しました（絶対スコアの ±8 の judge ノイズが、保守的な編集による実際の改善を埋もれさせ、false-revert の原因になっていました。within-judge 比較により、尺度の違いによる汚染を解消します）。絶対スコアは triage のみに降格しました。 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. 編集可能な資産は1つだけ — 毎回変更するのは1つの SKILL.md のみです
2. 二重評価 — 構造評価（静的分析）+ 効果検証（テストを実行して出力を確認）
3. ラチェット機構 — 改善のみを保持し、後退は自動的にロールバックします
4. 独立した評価 — 評価には子エージェントを使い、「自分で変更して自分で評価する」ことによる偏りを避けます
5. 人間参加型 — 各 skill の最適化後に一時停止し、ユーザーの確認を得てから続行します

純粋な構造レビューとの違い：SKILL.md の書き方が適切かどうかだけでなく、変更後の実際の実行結果が改善したかどうかも確認します。

---

評価 Rubric（9次元、合計100点）

設計根拠：SkillLens 論文（arXiv 2605.23899）の実証結果に基づきます。LLM-as-judge による skill 品質評価の正確度はわずか46.4%（ほぼランダム）ですが、meta-skill の3次元を加えると73.8%に向上します。この rubric では dim3／dim5 の評価基準を強化し、dim9「反例とブラックリスト」を追加して、重みの合計を100に調整しています。目的：評価を実際の品質により敏感にし、LLM judge の楽観的な偏りを減らします。

構造次元（59点）— 静的分析

#	次元	重み	評価基準
1	Frontmatter の品質	7	name が適切であること、description に何をするか＋いつ使うか＋トリガー語が含まれること、≤1024文字、末尾に「柔軟に適用／状況に応じて判断」などの中身のない文言を付けないこと
2	ワークフローの明確さ	12	手順が明確で実行可能、番号付きで、各手順の入力／出力が明確であること
3	失敗パターンの記述	12	失敗パターンを明示的に記述すること（「X が失敗した場合 → Y」のような明確な分岐を書くこと）。フォールバック経路とエラー復旧があること。肯定的な手順だけを書き、失敗時の分岐を書かない場合は3点以上減点（SkillLens meta-skill の次元）
4	チェックポイントの設計	6	重要な判断の前にユーザー確認があり、自律的な逸脱を防ぐこと。チェックポイントは明示的に示すこと（🔴／STOP／CHECKPOINT）。「もし…なら推奨します…」という言い回しだけでは該当しません
5	実行可能な具体性	18	曖昧さがなく、具体的なパラメーター／形式／例があり、そのまま実行できること。「推奨します／検討できます／状況に応じて／柔軟に対応／状況次第」などの曖昧な表現は禁止——3か所以上ある場合は3点以上減点（SkillLens actionable specificity の次元）
6	リソースの統合度	4	references／scripts／assets の参照が正しく、パスにアクセスできること

効果次元（35点）— 実測が必要

#	次元	重み	評価基準
7	全体アーキテクチャ	12	構造の階層が明確で、冗長や漏れがなく、花叔のエコシステムと一致していること。冗長な段落／AI らしい冗長な文言（「要するに／言い換えると／まず、次に、総合すると」など、花叔が禁止する言葉）が1か所あるごとに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点です
• ⚠️ 絶対合計点は triage（「どれが最も弱いか、どれから変更するか」の大まかな順位付け）にのみ使い、keep/revert の判断には決して使いません。実測では、変更していない同じ文章でも judge を変えて評価すると、合計点が ±8 変動する場合があります（🔴 の文字を3つ加えただけの skill が、単独評価で −8.5 点になりましたが、これは judge の尺度が変わったためであり、実際に後退したわけではありません）。keep/revert はすべて Phase 2 の paired 比較で判断します。
  • 理由：LLM judge の評価はサンプリングであり、測定ではありません——スコアは「文章 × その judge がその時点で選んだ基準」によって決まり、文章の属性ではありません。絶対合計点を使うのは、校正されていない2台の体重計でダイエット前後を測るようなものです。差の大部分は体重計の違いによるものです。paired 比較では、同じ体重計で前後を測るため、誤差が差し引かれて相殺されます。pairwise preference が absolute scoring より優れているというのは、LLM judge で知られている結論です（RLHF が絶対スコアではなく pairwise を使うのも同じ理由です）。

Rubric の実証的な根拠

rubric の設計は SkillLens 論文（arXiv 2605.23899） と ローカルでの controlled study に基づいています。

• SkillLens では、LLM-as-judge の正確度はわずか46.4%（ほぼランダム）で、meta-skill の3次元を加えると73.8%に上昇しました
• ローカル環境で huashu-research に対して4種類の劣化を行い、5つの独立した judge がブラインド評価したところ、全員が V1 > V2 と判断し、Δ の平均は +46.5（5/5 が高い信頼度）でした

結論：rubric は大幅な劣化を検出できますが、細かな品質差の評価には依然として信頼性がありません。重要な判断では必ず人間がレビューしてください。

→ 詳細な論文の根拠、5つの judge による全データ、HL の実践事例の数値は references/skilllens-evidence.md を参照してください。

「実測結果」次元について

純粋な構造評価との最大の違いです。評価方法：

1. 各 skill に対し、典型的なユーザー prompt を2〜3個設計します（境界ケースではなく、最も一般的な使用シナリオを選びます）
2. 子エージェントを使って実行します。skill を使う場合と使わない場合（ベースライン）の両方で実行します
3. 以下の観点から出力品質を比較して評価します：
   • 出力はユーザーの意図を満たしていますか？
   • skill を使わないベースラインと比べて、品質は明確に向上していますか？
   • skill が原因の悪影響（冗長すぎる、脱線する、不自然な形式）がありませんか？

子 agent を利用できない場合（タイムアウト／リソース制限）は、「ドライラン検証」に切り替えます。skill を読み終えた後、典型的な prompt を実行する流れをシミュレートし、その手順が妥当かどうかを判断します。results.tsv に dry_run と明記してください。dry_run の割合が30%を超える場合は、評価が無効であるという警告を出します（ローカルでの controlled study に基づくものです。dim8 の実測次元は重みが23%であり、full_test の検証がない場合、スコアは信頼できません）。

---

Runtime 互換性レビュー（ゲート項目、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

输出非空 = 红灯命中，但须先读命中行上下文排除假阳性（grep 命令本身/反例引用/讲解该规则的元陈述=假阳性，记 runtime_scan=false_positive 不改；判别表见 references/runtime-neutrality.md）→ 确认是真红灯（指令性用法）才强制把 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）— triage 用途

本阶段绝对分数是 triage 排名（决定先改谁），不是 keep/revert 基准。judge 对 gross 差异会一致（「哪支最弱」可信），对 fine-grained delta 不可信（±8 噪音）。keep/revert 在 Phase 2 用 paired 比较。

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: 诊断
    找出加权短板最大的维度：weighted_gap = weight × (10 - score) / 10，结构或效果都算
    # /10 与「总分 = Σ(维度分 × 权重) / 10」同标度：weighted_gap 就是该维度还能贡献的总分数
    # 为什么不用「原始分最低」：低权重维度会制造进步幻觉——issue #18 实战中
    # dim9（权重6，gap 5.3）原始分最低被优先修，而 dim8（权重23）加权短板最大（11.5）却 4 轮未动
    # 加权短板相近（差距 ≤ 1.0，同上述标度）时，回退为原始分升序
    # HL-3 警告：dim2/dim3/dim4 是相关簇，修一个时另两个常跟着涨
    # → 不要因为 dim3 短板最大就单独修，要看整簇短板再决定是否同步改

    # Step 2: 提出改进方案
    针对该维度，生成1个具体改进方案：
      - 改什么（具体段落/行）
      - 为什么改（对应rubric哪条）
      - 预期提升多少分

    # Step 3: 执行改进
    编辑 SKILL.md
    git add + commit（message: "optimize {skill}: {改进摘要}"）

    # Step 4: Paired 重新评估（取代绝对重打分——绝对分数 judge 噪音 ±8、淹没保守编辑的 +3~8 真实增益）
    spawn N=3 独立 judge，每个【同一次 call 内】读两版：
      - 改前版：git show HEAD:<skill-path>/SKILL.md（上一个 kept commit）
      - 改后版：working tree 当前 SKILL.md
    照 9 维 rubric 当【比较准则】（不是各打绝对分），回 {better | worse | tie} + margin{clear|slight} + 一句理由。
    关键：同一 judge 在一次 call 内比两版 → 它那把不准的尺对两版【等量作用、在比较时抵销】(within-judge cancellation)，
    这正是 paired 优于绝对的机制。N 取奇数（默认 3；close call 升 5）。

    # Step 5: 共识决策（多数决，取代「新总分 > 旧总分」）
    cur = 投 better 的 judge 数；wor = 投 worse 的；
    if cur >= wor:  # 多数说改后 ≥ 改前（含 tie）
      status = "keep"
      # HL-4 见好就收：连续 2 轮多数 judge 判 margin=slight 或 tie → break 进 Phase 3
    else:           # 多数说 worse —— 这才是真退步（已扣掉换尺噪音）
      status = "revert"
      git revert HEAD（创建新commit回滚，不用 reset --hard）
      记录到 results.tsv（note 记 vote 比数 + 一句 worse 理由）
      break
    # 单评绝对分数出现「负 delta」≠ revert 信号；必须经 paired 多数判 worse 才 revert（否则在丢真实增益）

    # 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 列：paired（同 judge 比改前/改后，keep/revert 权威依据）｜full_test（子agent 跑 prompt）｜dry_run（模拟推演、仅供参考）。 paired 行：new_score 栏记 vote 比数（如 3-0 better），note 记一句裁断理由。例：

2026-06-10T06:30	paired	some-skill	（绝对 87.3→78.8 = judge 噪音）	3-0 better	paired 推翻单评假退步	paired

文件位置：.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 回で revert が 0 回だったことから得た教訓と、Judge G/H の自己評価で明らかになったアンチパターンです。各項目はすべて実際に経験した落とし穴です。

#	アンチパターン	避けるべき理由	代替策
1	同じコンテキストで自己評価して自己修正する	修正直後に同じ Claude session で採点すると、「自分がたった今直したのだから、きっと良くなった」という楽観バイアスが生じます（SkillLens の実証では LLM-as-judge の精度はわずか 46.4%）	必ず独立した子エージェントを起動します。keep/revert はペア比較（同じ judge が一度に修正前と修正後を読む）による奇数 N の多数決で決め、絶対スコアの delta は使いません（絶対スコアは judge 間で ±8 のノイズがあり、比較できません）
1b	絶対スコアの delta を keep/revert の基準にする	絶対合計スコアは測定値ではなくサンプリング結果です。baseline judge と rescore judge では「ものさし」が異なり、差の大部分は実際の品質変化ではなく、ものさしの違いです（実測では、マーカーだけを追加した skill を単独評価したところ −8.5 で、すべてものさしの違いでした）	絶対スコアは優先順位付けにのみ使います。keep/revert はペア多数決で判断し、judge 内の差分相殺によってものさしの違いによる汚染を取り除きます
2	ロールバックに git reset --hard を使う	未コミットの作業ツリーの変更が失われ、CI の履歴が途切れます	git revert HEAD で逆向きの commit を作成し、追跡可能な履歴を維持します
3	スコアを稼ぐために冗長な内容を加える	上限に達した後も無理に変更を続けると、「LLM に詳細だと思わせるために無駄な文章や段落を追加する」ことになりがちで、実際の品質は変わりません	上限到達の兆候（Δ<2 点が 2 ラウンド連続）を確認したら、Phase 3 に進み、良いところで切り上げます
4	test-prompts を用意せずに直接採点する	test-prompts のない dim8 は根拠のない採点であり、重み 23% の評価が捏造になってしまいます	Phase 0.5 で 2～3 個の prompts の設計を必須にします。ユーザーが提示しない場合は、デフォルトで 3 個を作成して確認を求めます
5	1 ラウンドで複数の次元を変更する	複数の変数が同時に変わるため、スコアの上下を具体的な変更に帰属できません	1 ラウンドにつき 1 つの次元のみ変更します。関連クラスター（dim2/3/4）では、1 つを変更した際にほかの 2 つも上がるかを確認します
6	dry_run の割合が 30% を超える	dim8 の実測次元が形骸化し、スコアが実態より高くなります（初期の 40 回の記録では dry_run が 67%、revert は 0 回でした）	実際の full_test を少なくとも 1 回行うことを必須にします。dry_run が多い最適化には、results.tsv で明示的に ⚠️ を付けます
7	異常を黙って無視する	git/tsv の異常が発生した際に黙って続行すると、ratchet の完全性が損なわれます	異常時の表にある 10 件の fallback は、処理前に必ずユーザーへ通知します
8	次元間の相関を無視して個別に最適化する	dim2/3/4 は関連クラスターです。dim2 を単独で最適化しようとすると、前のラウンドで dim3 を修正した際に、すでに上限まで押し上げられていたと判明することがよくあります	加重後の最大のボトルネック次元を探す際、関連クラスターのボトルネックも同時に確認し、まとめて変更するかどうかを判断します

実行タイミング：各ラウンドの Phase 2 で変更する前に、本表を一度確認します。アンチパターンに 1 つでも該当したら、計画を練り直します。

---

制約ルール

1. skill の中核機能と用途を変えない — 最適化するのは「どう書くか」と「どう実行するか」のみで、「何をするか」は変えません
2. 新しい依存関係を追加しない — skill に元からない scripts や references ファイルを追加しません
3. 1 ラウンドにつき 1 つの次元のみ変更する — 複数の変更によって原因を特定できなくなるのを防ぎます
4. ファイルサイズを適切に保つ — 最適化後の SKILL.md は、元のサイズの 150% を超えないようにします
5. 花叔のスタイルを尊重する — 中国語を中心に、簡潔さを重視します
6. ロールバック可能にする — すべての変更を git ブランチ上で行い、reset --hard ではなく git revert を使います
7. 評価の独立性を保つ — 効果の次元は必ず子エージェントまたは最低限でも dry-run で検証し、同じコンテキストで「変更後すぐに評価」してはいけません
8. ランタイム中立性 — skill は Claude Code、Codex、Cursor、OpenClaw、Hermes など、skills-compatible なあらゆるランタイムで正常に動作する必要があります。skill 名が単一のランタイムに明示的に結び付いている場合（例：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 → ⚠️ ここが 1.0 における概念上の誤りの原因です：autoresearch の val_bpb は決定論的な loss（再実行しても同じ値）ですが、darwin では LLM-judge のスコア（ランダムサンプリング）に適用しながら、「絶対値の大小」を基準にした ratchet をそのまま使っています。再現性のない数値を再現性があるものとして扱っています。修正：9 次元の rubric はペア比較の基準として使い、絶対 metric としては使いません
• git ratchet → 「絶対合計スコアが高い」commit ではなく、ペア多数決で「修正後 ≥ 修正前」と判定された commit を維持します
• test set → 各 skill の test-prompts.json

違い：人が介在する仕組みを追加しています（autoresearch は完全自律型ですが、skill の最適化には人の判断力が必要です）。また、skill の「良し悪し」は loss の数値よりも微妙なため、二重評価の仕組み（構造＋効果）も追加しています。

学術的根拠と謝辞

• SkillLens（arXiv 2605.23899）：9 次元 rubric の実証的な出典です（LLM の自己評価は 46.4% → meta-skill の 3 次元を加えると 73.8%）。
• SkillOpt（arXiv 2605.23904）：validation-gated edits の形式化フレームワークです。コードは github.com/microsoft/SkillOpt（pip install skillopt）、プロジェクトページは microsoft.github.io/SkillOpt です。🤝 2026-06-03 に Microsoft の公式リポジトリが darwin-skill を統合対象に追加しました。
• autoresearch：github.com/karpathy/autoresearch。本 skill の 1.0 における元のインスピレーションです。

---

成果カードの生成（Result Card）

各 skill の最適化完了後（または全体の集計後）に、視覚的な成果カードを自動生成し、スクリーンショットを PNG として保存します。

カードのテンプレート

テンプレートの場所：templates/result-card.html

3 種類のスタイルから、毎回ランダムに 1 つ選択します。

スタイル	CSS クラス	URL hash	見た目の特徴
Warm Swiss	.theme-swiss	#swiss	暖色系の白い背景＋テラコッタオレンジ、Inter フォント、すっきりしたグリッド
Dark Terminal	.theme-terminal	#terminal	ほぼ黒の背景＋蛍光グリーン、等幅フォント、走査線
Newspaper	.theme-newspaper	#newspaper	暖色系の白い紙＋深紅、セリフフォント、2 段組のエディトリアル風

生成手順

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

## 版本自检（静默）

本节给 AI agent：每次使用本 skill 前，先做一个不联网的判断——读本 skill 目录（SKILL.md 所在目录）下的 `.last-update-check` 文件（内容为一行日期 YYYY-MM-DD）。文件存在且距今不足 30 天，跳过本节直接干活，不向用户提任何更新相关的话。

到期或文件不存在时，且仅在此时：

1. 本目录不是 git 克隆（无 `.git` 或无 origin）→ 写入今天日期后跳过本节
2. 对比版本：`git -C <本目录> rev-parse HEAD` 与 `git -C <本目录> ls-remote origin HEAD`
3. 无论结果如何，把今天日期写入 `.last-update-check`
4. 两者一致 → 什么都不说；确认落后 → 先完成用户当前任务，结束后附一句「本 skill 有新版本，可用 `git -C <本目录> pull --ff-only` 更新」。是否更新由用户决定，不要主动执行更新