skill-autorevise 模板说明

这份 README 是按你的要求额外加的，用来说明：如何参考 skill-autorevise，给一个新 skill 接入 auto-research / skill-opt 优化闭环。

你要参考的核心思路

skill-autorevise 本身不是每个 skill 都复制一份的“引擎包”。

正确用法是：

• 全局只保留一份引擎：~/.claude/skills/skill-autorevise/
• 每个具体 skill 自己放一套 .skill-opt/ 本地模板

也就是：

• 引擎在这里：
  • ~/.claude/skills/skill-autorevise/
• 新 skill 的本地实验目录长这样：
  • <skill-name>/.skill-opt/

最小模板结构

一个新的 skill，最小可用结构建议是：

<skill-name>/
├── SKILL.md
└── .skill-opt/
    ├── skill-opt.config.json
    ├── evals/
    │   ├── validation.json
    │   └── test.json
    ├── fail_revise.md
    ├── skill-opt-results.tsv
    ├── reviewer-log.jsonl
    └── eval-log.jsonl

如果这个 skill 复杂一些，还可以再加：

<skill-name>/
├── SKILL.md
├── scripts/
├── references/
└── .skill-opt/
    ├── run_eval.py
    ├── tests/
    ├── autoresearch/
    ├── evals/
    ├── fail_revise.md
    ├── skill-opt-results.tsv
    ├── reviewer-log.jsonl
    ├── eval-log.jsonl
    └── skill-opt.config.json

现成模板在哪

我已经把一个 starter 模板放在：

~/.claude/skills/skill-autorevise/templates/skill-opt-starter/

里面包含：

templates/skill-opt-starter/
├── SKILL.md.example
└── .skill-opt/
    ├── skill-opt.config.json
    ├── evals/
    │   ├── validation.json
    │   └── test.json
    ├── fail_revise.md
    ├── skill-opt-results.tsv
    ├── reviewer-log.jsonl
    └── eval-log.jsonl

怎么用这个模板

假设你要新建一个 skill：my-skill

1）先建 skill 目录

cd /Users/ccccciooi/.openclaw/workspace/skills
mkdir -p my-skill

2）复制模板

cp ~/.claude/skills/skill-autorevise/templates/skill-opt-starter/SKILL.md.example ./my-skill/SKILL.md
mkdir -p ./my-skill/.skill-opt/evals
cp ~/.claude/skills/skill-autorevise/templates/skill-opt-starter/.skill-opt/skill-opt.config.json ./my-skill/.skill-opt/skill-opt.config.json
cp ~/.claude/skills/skill-autorevise/templates/skill-opt-starter/.skill-opt/evals/validation.json ./my-skill/.skill-opt/evals/validation.json
cp ~/.claude/skills/skill-autorevise/templates/skill-opt-starter/.skill-opt/evals/test.json ./my-skill/.skill-opt/evals/test.json
cp ~/.claude/skills/skill-autorevise/templates/skill-opt-starter/.skill-opt/fail_revise.md ./my-skill/.skill-opt/fail_revise.md
cp ~/.claude/skills/skill-autorevise/templates/skill-opt-starter/.skill-opt/skill-opt-results.tsv ./my-skill/.skill-opt/skill-opt-results.tsv
touch ./my-skill/.skill-opt/reviewer-log.jsonl
touch ./my-skill/.skill-opt/eval-log.jsonl

3）把占位符换掉

模板里有这些占位符：

• __SKILL_NAME__
• __SKILL_TITLE__
• __SKILL_WHEN_TO_USE__
• __SKILL_VALIDATION_HINT__
• __SKILL_TEST_HINT__

你需要按自己的 skill 改掉。

config 要怎么改

默认模板里的 git 规则是：

• 工作分支：dev
• push 模式：manual
• commit message：#{name}# {change_summary}
• reviewer 默认权重：20%

也就是：

• 所有 skill 默认都在 dev 分支工作
• commit 内容会带 skill 名标签
• 如果启用 reviewer 审批但没有额外指定权重，默认按 20% 计入总分

一个典型配置长这样：

{
  "name": "my-skill",
  "target_path": "my-skill/SKILL.md",
  "eval_root": "my-skill",
  "datasets": {
    "validation": "my-skill/.skill-opt/evals/validation.json",
    "test": "my-skill/.skill-opt/evals/test.json"
  },
  "history": {
    "fail_log_path": "my-skill/.skill-opt/fail_revise.md",
    "results_path": "my-skill/.skill-opt/skill-opt-results.tsv",
    "reviewer_log_path": "my-skill/.skill-opt/reviewer-log.jsonl",
    "evaluation_log_path": "my-skill/.skill-opt/eval-log.jsonl",
    "max_failed_revisions": 8
  },
  "scoring": {
    "min_improvement_delta": 0.25,
    "fail_on_blocking": true,
    "require_test_for_push": true
  },
  "reviewer": {
    "weight": 0.2
  },
  "git": {
    "push_mode": "manual",
    "remote": "origin",
    "branch_template": "dev",
    "commit_on_improve": true,
    "commit_message_template": "#{name}# {change_summary}"
  },
  "loop": {
    "max_iterations": 5
  }
}

Reviewer 审批（可选）

如果你不想只靠 validation/test 数据集打分，还可以启用一个 reviewer 子 agent 来做“评审家”审查。

推荐做法：

1. 让 Claude 启动一个 reviewer 子 agent
2. reviewer 读取 baseline / candidate 的 SKILL.md、diff、validation/test 分数、fail_revise.md
3. reviewer 输出：
   • judgement（baseline_better / roughly_equal / candidate_better）
   • summary
4. 脚本按固定规则把相对判断映射成 reviewer 分数：
   • baseline_better → baseline=100, candidate=95
   • roughly_equal → baseline=100, candidate=100
   • candidate_better → baseline=95, candidate=100
5. 主流程按下面公式计算总分：

total = validation * (1 - reviewer_weight) + reviewer_score * reviewer_weight

如果启用 reviewer 但没有指定权重，默认使用 20%。

只要一轮运行声称“启用了 reviewer”，主 agent 就必须：

1. 先完成当前 candidate 的本地 validation/test 评分
2. 再使用 Task tool 启动 reviewer 子 agent
3. 等待 reviewer Task 完成并回调 JSON
4. 阅读 reviewer 的评分和建议
5. 最后再把 reviewer 结果传给 run_cycle.py

推荐优先走 一条命令版 Claude CLI reviewer 流程：

1）默认优先用一条命令串完整流程

python ~/.claude/skills/skill-autorevise/scripts/run_full_reviewer_cycle.py \
  --config <config-path> \
  --change-summary "<简短变更摘要>"

这个脚本会自动：

• 先调用 prepare_reviewer_task.py 生成 reviewer request
• 再调用 run_reviewer_via_claude_cli.py
• 用 claude -p + --agents + --agent reviewer + --json-schema 跑独立 reviewer 会话
• 把结果保存到：
  • reviewer-cli-envelope-latest.json
  • reviewer-cli-result-latest.json
  • reviewer-cli-stderr-latest.txt
• 然后自动调用 finalize_reviewer_cycle.py 收口

如果你只想先看 reviewer 判断和映射后的分数、不想收口：

python ~/.claude/skills/skill-autorevise/scripts/run_full_reviewer_cycle.py \
  --config <config-path> \
  --change-summary "<简短变更摘要>" \
  --review-only

如果你想让 reviewer 跑真实审查，但只 dry-run 收口：

python ~/.claude/skills/skill-autorevise/scripts/run_full_reviewer_cycle.py \
  --config <config-path> \
  --change-summary "<简短变更摘要>" \
  --dry-run

2）需要调试时，再拆成两步

先生成 reviewer request：

python ~/.claude/skills/skill-autorevise/scripts/prepare_reviewer_task.py \
  --config <config-path> \
  --change-summary "<简短变更摘要>"

再直接用 Claude Code CLI 跑 reviewer 并自动收口：

python ~/.claude/skills/skill-autorevise/scripts/run_reviewer_via_claude_cli.py \
  --request <reviewer-request-json-path>

3）仅当本地 Claude CLI reviewer 不可用时，才退回 Task tool 流程

这时可以继续使用：

• reviewer_launcher.py
• Task tool
• finalize_reviewer_cycle.py

如果必须手动传 reviewer 参数，至少也要显式传：

--reviewer-required \
--reviewer-score-baseline <baseline_score> \
--reviewer-score-candidate <candidate_score> \
--reviewer-summary "<summary>"

否则脚本会直接报错，不再默默按“未启用 reviewer”处理。

完整等待/回调协议见：

~/.claude/skills/skill-autorevise/references/reviewer-subagent-protocol.md

落盘策略采用方案 C：

• skill-opt-results.tsv：继续只放短摘要
• fail_revise.md：继续只放失败原因和简要 reviewer 信息
• reviewer-log.jsonl：保存 reviewer 的完整结构化记录（每轮一条 JSON）
• eval-log.jsonl：保存每轮 validation/test 的完整结构化评测结果（包含 case/check 明细），避免流程变黑盒

详细 rubric 见：

~/.claude/skills/skill-autorevise/references/reviewer-rubric.md

什么情况下需要额外写 run_eval.py

不需要写的情况

如果你的 skill 主要优化的是：

• SKILL.md 的触发描述
• 文档结构
• 关键词 / 示例 / 注意事项

那直接用现成的：

• score.py
• validation.json
• test.json

就够了。

需要写的情况

如果你的 skill 还要评估：

• scripts/ 是否存在
• references/ 是否存在
• shell syntax
• 更复杂的 smoke test / 集成检查

那就给该 skill 自己再补：

.skill-opt/run_eval.py
.skill-opt/tests/
.skill-opt/autoresearch/

screenshot 就是这种更复杂的例子。

参考哪个现成 skill 最快

• 简单文本型 skill：参考 websearch
• 复杂带脚本/集成型 skill：参考 screenshot

它们现在都在：

/Users/ccccciooi/.openclaw/workspace/skills/

最后一句

如果你以后要给一个新 skill 接 auto-research，最实用的路径是：

1. 从这个 README 提到的 starter 模板复制 .skill-opt/
2. 参考 websearch 补最小配置
3. 如果 skill 更复杂，再参考 screenshot 补 run_eval.py