merge

merge skill 概覽

merge skill 的用途

merge skill 是一個 AgentHub workflow skill，用於在多代理程式碼工作階段結束後，將勝出的 agent 結果合併到 Git 的基底分支。它是為 /hub:merge 指令設計的，專注於一件實務工作：合併被選出的 winner、保留落選嘗試以便後續檢視、清理 session worktrees，並寫出合併後摘要。

最適合的 Git Workflows

如果你的 repository 採用 AgentHub 模式，也就是使用 session IDs、agent branches、evaluation rankings，以及 temporary worktrees，這個 merge skill 會很適合。它特別適合在 /hub:eval 之後使用：當你已經知道哪個 agent 產出最佳解法，並且想要一套可重複的 Git Workflow，而不是手動 checkout branches、merge、tag losers、delete worktrees。

與一般 merge prompt 的差異

一般 prompt 可能只會說「merge the best branch」，但這個 skill 編碼了一套明確的操作慣例：除非提供 --agent，否則使用排名最高的 agent；使用 --no-ff 合併；用 hub/archive/... tags 封存未勝出的 branches；刪除它們的 branch refs；並產生 .agenthub/board/results/merge-summary.md。這樣的結構能降低清理階段的歧義，而多代理 Git sessions 往往就是在清理時變得混亂。

安裝前的採用注意事項

這個 skill 假設你的專案已經有 AgentHub 風格的 branches，例如 hub/{session-id}/{agent-id}/attempt-1，並且有能識別 winner 的 evaluation output。如果你的團隊沒有使用 AgentHub，這份 merge guide 仍可作為結構化清理的參考模型，但在安全使用前需要先調整。

如何使用 merge skill

merge 安裝與優先檢查的檔案

使用以下指令從 GitHub skill repository 安裝 skill：

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

接著檢查來源檔案：

engineering/agenthub/skills/merge/SKILL.md

從 skill directory preview 來看，這個 skill 似乎是自包含於 SKILL.md；skill 目錄中沒有可見的 companion rules/、resources/ 或 scripts/ folders。由於 upstream instructions 提到 session_manager.py，在依賴自動清理之前，請先確認該 script 在你的本機 AgentHub setup 中實際位於何處。

基本 merge 使用方式

常見呼叫方式如下：

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

當目標是最近一次已 evaluation 的 session 時，使用 /hub:merge。如果存在多個 AgentHub sessions，請提供 session ID。只有在你有意覆寫排名最高的 /hub:eval 結果時才加上 --agent，例如人工 review 發現最高分解法漏掉了安全性、相容性或產品需求。

skill 需要的輸入

若要可靠地使用 merge，agent 需要：

• 目標 base branch，通常是你想把勝出成果落入的分支。
• AgentHub session ID，除非 latest session 明確無歧義。
• winner，來源可以是最新 evaluation ranking，或由 --agent 指定。
• 符合預期格式的現有 branch refs：hub/{session-id}/{agent-id}/attempt-1。
• 執行 Git operations 的權限，包括建立 merge commits、tags，以及刪除 branches。

更好的 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，確認沒有夾帶不相關的本機變更，並檢視 winning diff。merge 之後，檢查 merge commit message，確認 archive tags 已建立，並驗證 .agenthub/board/results/merge-summary.md 是否正確反映 session、task 與 winner。若出現 conflicts，就依一般 Git conflicts 流程處理；這個 skill 提供的是工作流程結構，不能取代 code review。

merge skill 常見問題

merge 只適用於 AgentHub 嗎？

實務上是。merge skill 是圍繞 AgentHub 的命名、evaluation 與 cleanup conventions 撰寫的。它可以啟發其他多分支實驗的手動 Git Workflow，但若要直接使用，會預期存在 AgentHub session branches 與 result metadata。

merge 會自動選出最佳程式碼嗎？

它會選擇你用 --agent 指定的 agent；如果沒有指定，則選擇最近一次 /hub:eval 中排名最高的 agent。也就是說，merge 品質取決於先前 evaluation 的品質。如果你的 evaluation criteria 不完整，合併前請先人工 review winner。

落選 branches 會怎麼處理？

預期 workflow 會用 Git tag 封存每個落選 agent branch，例如 hub/archive/{session-id}/{agent-id}，接著刪除 branch ref。這樣可以讓 commits 仍可被追溯，同時減少 branch 雜訊。有 retention policies 的團隊，在採用此 skill 前應先確認 archive tag naming 是否符合規範。

什麼情況不該使用這個 skill？

如果 branch names 不符合 AgentHub convention、base branch 不明確、winner 尚未 review，或你的 repository 禁止自動刪除 branches，就不要使用 merge。如果你的流程只接受 squash-only merges，除非你先調整 merge command，否則也不適合，因為這個 skill 的預設模式使用 git merge --no-ff。

如何改進 merge skill

用更清楚的脈絡改善 merge 結果

merge skill 在 request 包含 session ID、winner、base branch，以及任何 policy constraints 時效果最好。例如：「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」更好，因為它把選擇、目的地、清理與安全規則分開說清楚。

常見失敗模式與風險

主要風險包括 latest sessions 不明確、evaluation results 缺失、working tree 不乾淨、branch refs 不符合預期格式，以及 cleanup commands 依賴此 skill directory 以外的檔案。另一個重要風險是 winner 技術上通過，卻不符合產品需求。請把 /hub:eval 視為選擇依據，而不是 final review 的替代品。

依 repository policy 調整 merge

如果你的團隊要求 squash merges、signed commits、protected branches、pull requests、CI gates，或保留 remote branches，請在 production 使用前先編輯 workflow。最可能需要客製的地方包括 merge strategy、archive tag format、branch deletion 是否僅限 local，以及 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 guide 轉化成可稽核的 Git Workflow，並有助於在 session 被遺忘前抓出不完整的 cleanup。