create-skill-autoresearch

使用 Autoresearch Factory 创建 Skill

通过金标准驱动的自动研究、多 Agent 验证和结构化共识，打造可用于生产环境的 Agent Skill。

Factory 通过 5 个阶段协调 4 种 Agent 角色：

阶段	处理内容	Agent 角色
1. 访谈	了解目标、金标准和范围	ORCHESTRATOR
2. 研究	学习领域资料、整理档案、提出评分标准	RESEARCHER（N 个并行）
3. 起草	设计结构、生成 SKILL.md、测量基线	BUILDER
4. 自动研究	根据金标准迭代 Skill（使用 LLM-as-judge，或为流程型 Skill 使用客观的现实指标——见 3.4）	BUILDER + autoresearch skill
5. 验证	预演分析、评审组评分、达成共识、发布或迭代	PANEL（3 个子 Agent）

关键约束：BUILDER 和 PANEL 绝不共享上下文。评审组只接收 Skill 输出、金标准和评分标准，不会受到构建过程的影响。

与 create-skill 的关系

此 Factory 扩展而非取代官方的单轮 Skill 创建工具（Anthropic 的 Skills best-practices 和 skill-creator；Cursor 的 create-skill）。它增加了一次性生成器无法提供的功能：研究档案、金标准基准测试、自主改进循环，以及独立的多 Agent 验证。它生成的 Skill 遵循相同的官方规范——参见 references/skill-authoring-best-practices.md。

配套 Skill

Factory 在运行时协调这些同级 Skill：autoresearch（第 4 阶段的改进循环）、premortem（第 5 阶段的风险审查）和 handoff（跨会话连续性）；第 5 阶段的评审组／共识设计借鉴了 llm-council。在此运行环境中，它们以 vendored 形式存放在 .agents/skills/ 下。如果单独安装此 Skill，也请一并安装这些 Skill。Factory 的工艺层（references/skill-craft-principles.md）提炼自 writing-great-skills（mattpocock/skills，MIT），该 Skill 以 vendored 形式存放在运行环境的 .agents/skills/ 下。安装了 tribunal 后，第 5 阶段会委派任务给它（参见 5.2）。

---

第 1 阶段：访谈

通过结构化提问了解用户的需求。不要臆测——要提问。每次只询问一个主题，并记录回答；具体问题措辞和后续追问见 references/pipeline-phases.md。

1.1 - 1.5 需要了解的内容

主题	询问内容	记录
目标和领域	要解决的问题、所属领域、使用该 Skill 的 Agent，以及“成功”的标准	SKILL_PURPOSE、DOMAIN、TARGET_USER、SUCCESS_CRITERIA
金标准	“优秀成果”的示例——输入／输出对、参考成果、之前解决过的问题、现有质量报告；它们的位置、格式和数量	GOLD_STANDARD_SOURCE、GOLD_STANDARD_FORMAT、GOLD_STANDARD_COUNT
学习资料	文档、现有代码、文字记录、设计文档、参考实现、规范、风格指南	STUDY_MATERIALS
范围和约束	要遵循的惯例、要集成的 Skill、要避免的反模式、目标行数（默认 < 500），以及调用模式——模型调用型（会永久占用上下文）或用户调用型（disable-model-invocation: true）	CONSTRAINTS、INTEGRATION_SKILLS、ANTI_PATTERNS、INVOCATION_MODE
现有 Skill	该领域是否已有 Skill？如果有，它既是学习资料，也是基线——应研究它，依据评分标准进行测评并加以改进，而不是从头开始	EXISTING_SKILL，并将模式设为 upgrade 而非 greenfield

至少需要 3 个金标准。数量不足会带来风险——应提醒用户并提供替代方案：创建合成示例，或寻找更多参考资料。

1.6 确认并创建工作区

在表格中汇总所有参数，并请用户确认。

确认后，在 builds/<skill-name>/ 下创建构建工作区，并划分为三个所有权区域：

• input/ —— 用户放置黄金标准和学习材料的位置，结构不限
• work/ —— 工厂生成的所有内容：manifest.yaml、research/、evaluation/、experiments/、handoffs/
• output/<skill-name>/ —— 已完成的技能（SKILL.md + references/），放在以其命名的目录中，可直接发布

不要要求用户手动编写清单。扫描 input/ 中的所有内容，将每项归类为黄金标准（示例输入/输出对或参考资料）或学习材料，并在 work/manifest.yaml 中编写衍生索引，标注 train/validation/test 标签。向用户展示衍生清单，请其确认或更正。有关接收格式和清单架构，请参阅 references/pipeline-phases.md。

---

第 2 阶段：研究

在编写任何技能代码之前，先彻底研究该领域。

2.1 启动研究子 Agent

按相关性对学习材料分组，然后为每个分组启动一个 explore 子 Agent。分组启发式规则：

• 按来源类型：将现有技能归为一组、黄金标准输出归为另一组、规划文档归为第三组
• 按子主题：如果材料涉及不同领域（例如后端与前端），则按领域拆分
• 最多 5-7 组：超过 7 组会增加综合工作量，但无法带来相称的深度提升
• 至少 2 组：只有一组就无法获得并行处理的优势

每个子 Agent：

1. 深入阅读分配的材料
2. 在 work/research/ 中整理研究笔记
3. 找出与该技能相关的模式、惯例和质量信号

命名方式：work/research/01-<topic>.md、work/research/02-<topic>.md 等。

2.2 综合研究结果

所有研究人员完成后，将研究结果综合整理到 work/research/00-synthesis.md：

• 跨领域模式
• 技能必须遵循的关键惯例
• 区分优质与低劣输出的质量信号
• 潜在的评分维度

2.3 提出评分标准

根据研究结果，起草 work/evaluation/rubric.yaml：

name: <skill-name>-rubric
dimensions:
  - name: <dimension>
    weight: <0.0-1.0>
    scale: "1-10"
    criteria: "<what this dimension measures>"
  # ... 5-10 dimensions
target_score: 0.85
max_iterations: 20
plateau_window: 5

始终包含以下通用维度（根据领域调整权重）：

• correctness：指令在技术上准确且可执行
• completeness：涵盖所有必要章节和边缘情况
• clarity：新手 Agent 无需猜测即可遵循
• consistency：符合现有代码库惯例
• predictability：每次运行都执行相同的流程——完成标准可检查且完备，不设模糊关卡，也没有无操作行（参阅 references/skill-craft-principles.md）

根据研究综合结果添加 3-5 个领域专属维度（总计 5-10 个维度）。

将评分标准提交给用户审阅，并持续迭代，直到获得确认。

模板请参阅 references/rubric-templates.md。

---

第 3 阶段：起草

先设计，再编写。先编写，再衡量。

3.1 设计文档

创建 work/experiments/DESIGN.md，包含：

• 技能名称和描述（遵循 create-skill 惯例）
• 结构决策：章节数量、参考文件拆分方式、渐进式披露方案
• 调用模式、信息层级方案（步骤与参考资料；内联与披露，由分支逻辑决定）以及候选引导词——参阅 references/skill-craft-principles.md
• 与其他技能的集成点
• 关键术语和语气决策

3.2 对设计进行严格审查

编写任何技能代码之前，以对抗性视角质疑设计：

• 哪些因素会导致该技能在实践中失败？
• 结构决策有依据，还是仅凭假设？
• 设计是否符合黄金标准所展示的做法？
• 是否存在更简单的替代方案？

向用户提出疑虑，并持续迭代，直到设计经得起审视。

3.3 生成 SKILL.md 草稿

遵循设计和官方的技能编写规则（参见 references/skill-authoring-best-practices.md），写作前先运行这份预检清单——以下都是硬性约束，不是建议：

• name：不超过 64 个字符，只能包含小写字母、数字和连字符，不得使用保留词 anthropic/claude；采用描述性的 kebab-case 命名，并与其所属集合的命名方式保持一致
• description：不超过 1024 个字符，使用第三人称，同时说明它的功能和适用场景
• 正文少于 500 行；采用渐进式披露（将核心内容放在 SKILL.md 中，详细内容放在 references/ 中）
• 文件引用最多深入一层；任何超过 100 行的参考文件都要包含目录
• 优先使用具体示例而非抽象指令；术语保持一致；路径使用正斜杠
• 描述撰写：开头突出关键词，每个分支只设定一个触发条件，不堆砌同义词； 用户调用的技能应提供一行面向用户的描述（references/skill-craft-principles.md）

将草稿写入 output/<skill-name>/SKILL.md（参考文件放在 output/<skill-name>/references/ 中）。

3.4 构建评估脚本

创建 work/evaluation/evaluate.sh，使其能够：

1. 接收黄金标准测试用例路径作为参数
2. 从测试用例中提取输入
3. 使用该输入调用技能——由于技能是 Markdown 指令（而非可执行文件），这意味着要将 SKILL.md 作为系统提示词、将测试用例输入作为用户消息，调用大模型。使用 curl 调用兼容 OpenAI 的 API，或使用特定语言的 SDK。捕获大模型的输出。
4. 使用 LLM-as-judge 将输出与黄金标准参考答案进行比较
5. 向 stdout 输出 METRIC <dimension>=<score> 行
6. 输出 METRIC overall_score=<weighted_average> 作为主要指标

完整的参考实现请参阅 agent-skills-harness 仓库中的 self-test/evaluation/evaluate.sh。

overall_score 用于指导第 4 阶段；它不是交付证据。 它衡量输出相对于黄金标准的绝对质量，不包含与裸模型的比较，因此无法回答“这个技能是否有帮助”。要回答这个问题，需要进行同模型提升基准测试——让同一个模型在相同任务上分别使用和不使用该技能；此测试应在发布前完成，并如实报告负面结果。根据 overall_score 判断技能是否有效，是最常见的错误做法，会让人误以为一个有效的技能毫无用处。标准、实验组、样本量和重试一致性规则，请参阅：references/benchmark-standard.md。

LLM 裁判应当：

• 使用结构化 JSON 输出各维度的评分
• 独立评估每个维度（避免光环效应）
• 对极端评分要求提供证据（逐字引用）
• 尽可能使用与构建者不同的模型系列

确定性评估与 LLM 裁判评估：并非每个维度都需要 LLM 裁判。尽可能优先使用确定性检查：

• 行数、frontmatter 验证、链接完整性 → shell/grep 检查
• 模式覆盖（输出是否提及 X？）→ 正则匹配
• 结构符合性 → 程序化验证

仅对需要主观判断的维度（清晰度、质量匹配度、内容筛选）使用 LLM-as-judge。在 evaluate.sh 中混合两种方式：确定性检查直接输出 METRIC 行，LLM 裁判负责其余部分。如果没有可用的 LLM API，则回退到仅使用确定性评分，并记录警告。

流程型 / Agent 型技能（适用时优先采用）：有些技能不会一次性生成产物，而是指导 Agent 在真实产物上执行多步骤任务（迁移框架版本、重构模块、搭建基础设施）。对于这类技能，上述单次调用测试框架并不适用：应通过在真实产物上执行任务，并使用客观的现实指标进行评估，以产物自身的真实结果替代裁判。完整方法——包括基准捕获、重置后由全新 Agent 执行的编排，以及为何每次运行都使用全新 Agent——请参阅 references/benchmark-standard.md。

多裁判评估（预算允许时推荐）：

• 使用 2-3 个不同的大模型，对同一输出进行裁判评估
• 对各裁判的各维度评分取平均值，以获得更稳健的信号
• 跟踪各裁判之间的评分差异——某个维度的差异较大，说明评估标准可能含糊不清
• 在 work/evaluation/judges.yaml 中配置裁判：

  judges:
    - model: "<model-1>"
      weight: 1.0
    - model: "<model-2>"
      weight: 1.0
  aggregation: "mean"
  

可以选择创建 work/evaluation/evaluate-checks.sh，用于执行正确性门禁。

3.5 测量基准

使用初始草稿，对测试用例运行 evaluate.sh。 记录基准分数。这是实验 0。

向用户报告：

已建立基准：overall_score = [value] 各维度：[各维度评分明细]

---

第 4 阶段：自动研究

调用 autoresearch skill，根据评估标准迭代技能草稿。

4.1 配置 Autoresearch

向 autoresearch 技能提供以下参数。所有路径均相对于构建工作区根目录（builds/<skill-name>/），该目录是 autoresearch 的工作目录。活动会话期间，autoresearch 会话文件（.md、.jsonl、.tsv、run.log）会创建在工作区根目录；会话结束或交接时，这些文件会归档到 work/experiments/。

• 目标：提升 <skill-name> 的质量，衡量指标为 overall_score（由 LLM 根据黄金标准进行评判，或针对流程类技能使用客观的真实世界指标——参见 3.4）
• 指标命令：./work/evaluation/evaluate.sh（相对于工作区根目录）
• 主要指标：overall_score
• 方向：higher_is_better
• 范围内文件：output/<skill-name>/SKILL.md、output/<skill-name>/references/*
• 范围外文件：input/、work/
• 约束：必须遵循官方技能编写规则（少于 500 行，frontmatter 格式——参见 3.3）
• 预算：取自 rubric 配置中的 max_iterations（默认值为 20）
• 检查项：如果 work/evaluation/evaluate-checks.sh 存在，则在工作区根目录创建 autoresearch.checks.sh 并在其中调用该脚本（autoresearch 技能要求使用此名称）

4.2 数据划分

如果黄金标准数量 >= 10：

• 70% 训练集：在每次 autoresearch 实验中使用
• 20% 验证集：自适应检查，用于检测过拟合（见下文）
• 10% 测试集：完全留出，直到第 5 阶段验证时才使用

如果黄金标准数量为 3-9：

• 留一法轮换：每次实验都使用除一个以外的所有样本进行评估，并轮换留出的样本

在 work/evaluation/data-split.yaml 中记录划分情况。

大型数据集的成本注意事项（100 个以上黄金标准）：每次由 LLM 进行评判都会产生实际费用。如果每次实验使用 70 个训练样本，且每次调用费用约为 $0.50，则每次实验约需 $35。可采用抽样策略降低成本：每次实验从训练样本中随机抽取一部分（例如 10-15 个）进行评估，并轮换样本。仅在验证保留的实验或到达阶段节点时，才运行完整训练集。

过拟合检测：自适应地使用验证集运行 evaluate.sh——每次实验保留后、出现平台期后（判断性能上限是真实存在还是仅针对训练集），以及训练分数提升超过 0.05 时。如果训练分数提升而验证分数下降超过 0.05，则提醒用户近期更改可能过拟合，并提供以下选项：将更改推广到更多情况、回退到最后一个验证结果稳定的提交，或放宽已变得过窄的评分标准。将验证检查记录到 autoresearch.jsonl，类型设为 "type": "validation_check"。

留一法的过拟合检测（黄金标准少于 10 个）：由于没有固定的验证集，应跟踪每个样本的方差——如果均值提升的同时方差扩大，说明技能可能在某些样本上进行专门优化，却牺牲了其他样本。当任一单独样本的分数下降超过 1.0 分，而其他样本有所提升时，应发出提示。

4.3 运行自主研究

自主研究技能负责处理循环：

• THINK-EDIT-COMMIT-RUN-MEASURE-DECIDE-LOG 循环（先提交的 git 模型）
• 用于测量的 METRIC 协议
• 用于结构化记忆的 ASI 字段
• 平台期检测
• 将结果记录到 autoresearch.jsonl 和 results.tsv

工厂会将以下内容添加到自主研究想法待办清单（autoresearch.ideas.md）：

• 研究综合得出的想法
• 评分标准中各维度的改进策略
• 在黄金标准中观察到、但尚未体现在技能中的模式
• 来自 references/skill-craft-principles.md 的打磨步骤：首词搜寻、清理无操作／重复／沉积内容、重新平衡披露内容

是否结束循环由工厂决定，而不是循环本身。 自主研究技能将平台期视为建议，并会在预算尚有剩余时继续运行，因此，如果任务无法达到 target_score，就会耗尽全部预算，并永远报告“未满足退出标准”。请覆盖这一行为：

• 达到置信度要求的平台期即为终点。 如果平台期处于评审方差范围内（在 1-10 分制中约为 0.2-0.3，低于此范围的提升无法测量），就应停止，并将迄今为止的最佳结果带入第 5 阶段。
• 低于目标是结论，而非失败——第 5.4 阶段会对其评分（达到或超过 target_score - 0.10 时为“带条件发布”）。以同样方式遵守 state.yaml 中的 baseline_lock，并将真实目标记录在想法待办清单中。
• 切勿为追求无法达到的数字而要求反复重跑：报告上限，指出限制因素（目标过高，或提升低于评审方差），然后继续。

4.4 监控与交接

如果自主研究会话超出上下文限制或实验预算：

1. 调用交接技能，生成 work/handoffs/HANDOFF-<session>.md
2. 使用结构化恢复状态编写 work/handoffs/state.yaml——包括阶段、会话计数器、最佳分数和提交、已运行的实验、剩余预算、验证分数、主要顾虑、受阻维度，以及 baseline_lock（完整架构见 references/pipeline-phases.md）
3. 下一次会话读取 state.yaml，从正确阶段恢复

4.5 恢复协议

当 work/handoffs/state.yaml 存在时：读取其中的当前阶段，读取最新的 work/handoffs/HANDOFF-*.md 以了解上下文，并从记录的阶段恢复（在 interview 阶段重新确认参数；如果 research 阶段的档案不完整，则进行综合；如果 draft 阶段草稿已存在，则测量基线；在 autoresearch 阶段读取 autoresearch.jsonl 中的 ASI 历史记录，并使用剩余预算继续；如果 verify 阶段上次的结论是 ITERATE，则重新运行评审组），然后增加会话编号。各阶段详情见 references/pipeline-phases.md。

---

第 5 阶段：验证

由未参与构建的 Agent 进行独立验证。构建者与评审组之间的上下文隔离至关重要——它可以避免构建过程带来的偏见。

5.1 事前分析

对技能制品调用事前分析技能。将识别出的风险作为额外测试场景纳入评审组评估，并按要求将五种打磨失败模式（过早完成、重复、沉积、臃肿、无操作）作为探查项。

5.2 面板评估

并行启动 3 个独立的验证子 Agent。每个子 Agent 仅接收以下内容：

• 技能的 SKILL.md 和参考资料
• 黄金标准
• 评分标准
• 事前分析的风险

他们不会收到：研究笔记、实验日志、构建者上下文或 ASI。

面板角色：

角色	关注重点	倾向
Verifier-A（质量）	正确性、完整性、清晰度、是否符合规范	中立
Verifier-B（实用性）	实际可用性、边缘情况、开发者体验	中立
Devil's Advocate	失效模式（包括五种 craft 失效模式）、隐藏假设、缺失的约束	明确持对抗立场

每位面板成员都要独立为每个评分维度打分，并提供：

• 分数（按评分标准的量表）
• 置信度（0.0-1.0）
• 证据（工件中的原文引述）

条件允许时，为面板使用不同的模型系列（例如，如果构建者使用了某个模型，则为验证者使用其他模型）。

每个角色配备一个 Agent——这是机制要求，并非形式上的安排。 一个 Agent 在同一上下文中模拟整个面板，评分只能达到它独自评分的水平（实测为 0.62，而独立 Agent 为 0.75）：共享上下文意味着共享盲点。ORCHESTRATOR 负责调度和裁决；它不参与评分。没有并行 Agent 时，应在全新上下文的会话中分别运行每个角色，并将结果标记为“单一上下文（无独立性）”。在进行共识计算前，逐一对照工件检查每条会影响裁决的引文；找不到原文的引文，其对应发现应作废。

面板提示词模板见 references/pipeline-phases.md。

如果有 tribunal 技能可用，请将第 5 阶段委托给它——这一模式经过泛化，并经过独立基准测试。将 BUILDER 的输出作为工件，并将第 2.3 阶段的评分标准（在第 3 阶段草稿前冻结）作为评估标准；其协调者不得是构建该技能的 Agent。否则，运行内置面板——独立安装不得依赖第二个技能。

5.3 共识协议

收集完全部 3 份评分后：

1. 检查一致性：每个维度上的所有分数相差不超过 1 分 → 计算加权平均分，结束
2. 综合讨论（任一维度的分差 >= 2，或 DA 在某个维度上打 1 分）：每位成员针对有争议的维度撰写理由（最多 500 个词）；理由会匿名并同时分享；成员可以附上书面理由后修改分数，否则若要维持原分，必须反驳对立意见中最有力的论点
3. 裁决：分数收敛到相差不超过 1 分 → 计算加权平均分；2/3 多数 → 采纳多数意见，并将少数意见记录为 work/experiments/craft-decisions.md 中的少数派报告；僵局 → 上报用户
4. DA 升级：若 DA 认为存在多数意见忽略的关键问题，可写入 ESCALATE: <reason>，将此问题提交给用户，而不是通过平均分将其淡化

完整协议、反模式和研究依据见 references/consensus-protocol.md。

5.4 发布或迭代

最终评分	操作
>= target_score AND no dimension blocked	发布 -- 将技能复制到最终位置
>= target_score - 0.10	附带注意事项发布 -- 记录顾虑，继续推进
< target_score - 0.10	迭代 -- 将评审组反馈交给 autoresearch
多数评审者给任一维度的评分 < 3/10	阻止 -- 先解决阻止发布的问题

如果选择迭代：

1. 提取评审组每位成员提出的主要顾虑
2. 提取 Devil's Advocate 提出的失败场景
3. 将具体的改进假设添加到 autoresearch.ideas.md
4. 将评审组评分及理由记录在 work/experiments/craft-decisions.md
5. 带着结构化反馈返回阶段 4

选择发布后，在构建根目录中写入 BENCHMARK.md（包含评审组的最终评分和裁定），然后遵循 references/publishing.md — 发布是注册清单，而不是复制文件；版本与注册表条目不一致会导致安装错误内容。通过提升基准测试证明该技能值得保留：references/benchmark-standard.md。

---

输出结构

每次构建都存放在一个独立的文件夹 builds/<skill-name>/ 中，包含三个区域：

builds/<skill-name>/
  input/                  # HUMAN: gold standards + study materials (any structure)
  work/                   # FACTORY: process artifacts (not shipped)
    manifest.yaml         #   derived gold-standard index    <- yours to correct
    research/             #   study notes and dossier
    evaluation/           #   rubric.yaml (exit criteria), evaluate.sh, judges.yaml, data-split.yaml
    experiments/          #   results.tsv, autoresearch.jsonl, run.log, DESIGN.md, craft-decisions.md
    handoffs/             #   cross-session context (state.yaml, HANDOFF-*.md)
  output/                 # FACTORY: the finished, publish-ready skill
    <skill-name>/         #   the skill in its own named dir
      SKILL.md
      README.md           #   optional, ships on install: what it does, method, results
      references/         #   if needed
      scripts/            #   if needed (NOT evaluation scripts)
      assets/             #   if needed
  BENCHMARK.md            # FACTORY: final panel scores + verdict (Phase 5)

work/ 是生成的内容，但有四个文件需要由人工在阶段边界处修正：manifest.yaml、 evaluation/rubric.yaml（退出标准）、evaluation/judges.yaml、evaluation/data-split.yaml。 切勿在其中任何文件写入凭据 — work/ 通常会提交到真实项目仓库中。

只有 output/<skill-name>/ 会被发布；其提升基准测试应放在技能目录之外的 benchmarks/<skill-name>/。发布方式：references/publishing.md。

---

交接规则

出现以下任一情况时，编写交接文档：

• 上下文窗口即将达到限制（轮次较多）
• 当前会话的实验预算已用尽
• 阶段转换（研究 → 草稿、草稿 → autoresearch 等）
• 用户明确提出要求

每次交接都要生成：

1. work/handoffs/state.yaml -- 用于自动恢复的结构化状态
2. work/handoffs/HANDOFF-<label>.md -- 便于人工阅读的详细上下文

恢复时：读取 state.yaml，确定当前阶段，加载相关上下文，然后继续。