merge

merge skill 概览

merge skill 适合做什么

merge skill 是一个 AgentHub 工作流 skill，用于在多 agent 编码会话结束后，把胜出的 agent 结果合并到 Git 基础分支。它为 /hub:merge 命令设计，聚焦一个非常实际的任务：合并被选中的胜出结果，保留未胜出尝试以便之后检查，清理会话 worktree，并写入合并后的总结。

最适合的 Git Workflow 场景

当你的仓库采用 AgentHub 模式，也就是使用 session ID、agent 分支、评估排名和临时 worktree 时，适合使用这个 merge skill。它最常用于 /hub:eval 之后：此时你已经知道哪个 agent 产出了最佳方案，并且希望用可重复的 Git Workflow 完成后续操作，而不是手动 checkout 分支、执行合并、给未胜出分支打 tag、再删除 worktree。

它和通用 merge prompt 有什么不同

通用 prompt 可能只会说“合并最佳分支”，但这个 skill 固化了一套明确的操作约定：除非提供了 --agent，否则使用排名第一的 agent；用 --no-ff 合并；用 hub/archive/... tag 归档未胜出的分支；删除它们的 branch ref；并生成 .agenthub/board/results/merge-summary.md。这套结构能减少清理阶段的歧义，而多 agent Git 会话最容易混乱的地方往往正是清理环节。

安装前的采用注意事项

这个 skill 假设你的项目已经有 AgentHub 风格的分支，例如 hub/{session-id}/{agent-id}/attempt-1，并且有能识别胜出者的评估输出。如果你的团队并不使用 AgentHub，这份 merge 指南仍然可以作为结构化清理流程的参考，但在安全使用前需要先做适配。

如何使用 merge skill

merge 安装方式和优先检查的文件

使用下面的命令从 GitHub skill 仓库安装：

npx skills add alirezarezvani/claude-skills --skill merge

然后检查源文件：

engineering/agenthub/skills/merge/SKILL.md

从 skill 目录预览来看，这个 skill 似乎自包含在 SKILL.md 中；没有看到配套的 rules/、resources/ 或 scripts/ 文件夹。由于上游说明提到了 session_manager.py，在依赖自动清理之前，请先确认该脚本在你本地 AgentHub 环境中的实际位置。

merge 的基本用法

常见调用方式如下：

/hub:merge
/hub:merge 20260317-143022
/hub:merge 20260317-143022 --agent agent-2

当目标是最近一次已评估的 session 时，使用 /hub:merge。如果存在多个 AgentHub session，请提供 session ID。只有在你有意覆盖排名第一的 /hub:eval 结果时，才添加 --agent；例如最高分方案遗漏了安全性、兼容性或产品需求，而这些问题被人工 review 发现了。

这个 skill 需要哪些输入

为了让 merge 使用更可靠，agent 需要：

• 目标基础分支，通常是你希望把胜出结果合入的分支。
• AgentHub session ID，除非最近一次 session 毫无歧义。
• 胜出者，可以来自最新评估排名，也可以来自 --agent。
• 符合预期格式的现有 branch ref：hub/{session-id}/{agent-id}/attempt-1。
• 执行 Git 操作的权限，包括创建 merge commit、tag 和删除分支。

更好的 prompt 是：“Run /hub:merge 20260317-143022 --agent agent-2 into main. Before merging, confirm the working tree is clean, show the winning branch ref, tag losing branches for archive, and write the merge summary.” 这会给 skill 足够的操作上下文，避免它自行猜测。

运行前后的实用工作流

调用 merge 之前，先运行 git status，确认没有夹带无关的本地修改，并 review 胜出分支的 diff。合并之后，检查 merge commit message，确认 archive tag 已创建，并验证 .agenthub/board/results/merge-summary.md 记录了 session、task 和 winner。如果出现冲突，就按常规 Git 冲突处理方式解决；这个 skill 提供的是工作流结构，并不能替代代码 review。

merge skill 常见问题

merge 只能用于 AgentHub 吗？

实际使用中，是的。merge skill 是围绕 AgentHub 的命名、评估和清理约定编写的。它可以启发你为其他多分支实验设计手动 Git Workflow，但直接使用时会期望存在 AgentHub session 分支和结果元数据。

merge 会自动选择最好的代码吗？

它会选择你通过 --agent 指定的 agent；如果没有指定，则选择最近一次 /hub:eval 中排名最高的 agent。这意味着 merge 质量取决于之前评估的质量。如果你的评估标准不完整，请在合并前人工 review 胜出方案。

未胜出的分支会怎样处理？

预期工作流会为每个未胜出的 agent 分支创建 Git tag 进行归档，例如 hub/archive/{session-id}/{agent-id}，然后删除 branch ref。这样可以让 commit 仍然可达，同时减少分支列表的杂乱。对保留策略有要求的团队，应在采用该 skill 前确认 archive tag 的命名方式。

什么时候不应该使用这个 skill？

如果分支名不符合 AgentHub 约定、基础分支不明确、胜出方案尚未 review，或者你的仓库禁止自动删除分支，就不要使用 merge。如果你的团队只允许 squash merge，它也不太适合，除非你先调整 merge 命令，因为这个 skill 的默认模式使用 git merge --no-ff。

如何改进 merge skill

通过更清晰的上下文提升 merge 结果

merge skill 在请求中包含 session ID、胜出者、基础分支和任何策略约束时效果最好。例如：“Merge session 20260317-143022, winner agent-2, into develop; keep losing branches archived with tags, do not delete remote branches, and stop if tests fail.” 这比“merge the winner”更好，因为它把选择、目标分支、清理方式和安全规则明确区分开来。

需要留意的常见失败模式

主要风险包括：最近一次 session 不明确、缺少评估结果、working tree 不干净、branch ref 不符合预期格式，以及清理命令依赖这个 skill 目录之外的文件。另一个重要风险是，合并了一个技术上通过但产品上不正确的胜出方案。请把 /hub:eval 视为选择输入，而不是最终 review 的替代品。

根据你的仓库策略适配 merge

如果你的团队要求 squash merge、签名 commit、受保护分支、pull request、CI gate 或远程分支保留，请在生产环境使用前修改工作流。最可能需要定制的点包括 merge 策略、archive tag 格式、分支删除是否仅限本地，以及 merge-summary.md 中必须包含哪些字段。

第一次运行后继续迭代

第一次输出后，让 agent 先验证，而不是盲目继续：“Show the merge commit, list archive tags for this session, confirm no AgentHub worktrees remain, and summarize any conflicts or skipped cleanup.” 这样可以把 merge 指南变成可审计的 Git Workflow，并帮助你在 session 被遗忘之前发现未完成的清理工作。