merge

Overview of merge skill

What the merge skill is for

The merge skill is an AgentHub workflow skill for landing the winning agent result into a Git base branch after a multi-agent coding session. It is designed for the /hub:merge command and focuses on one practical job: merge the selected winner, preserve losing attempts for later inspection, clean up session worktrees, and write a post-merge summary.

Best fit for Git Workflows

Use this merge skill when your repository follows the AgentHub pattern of session IDs, agent branches, evaluation rankings, and temporary worktrees. It is most useful after /hub:eval, when you already know which agent produced the best solution and want a repeatable Git Workflow instead of manually checking out branches, merging, tagging losers, and deleting worktrees.

What makes it different from a generic merge prompt

A generic prompt might say “merge the best branch,” but this skill encodes a specific operational convention: use the top-ranked agent unless --agent is provided, merge with --no-ff, archive non-winning branches with hub/archive/... tags, delete their branch refs, and generate .agenthub/board/results/merge-summary.md. That structure reduces ambiguity during cleanup, which is often where multi-agent Git sessions become messy.

Adoption notes before install

The skill assumes your project already has AgentHub-style branches such as hub/{session-id}/{agent-id}/attempt-1 and evaluation output that can identify a winner. If your team does not use AgentHub, the merge guide is still readable as a model for structured cleanup, but it will need adaptation before safe use.

How to Use merge skill

merge install and files to inspect first

Install the skill from the GitHub skill repository with:

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

Then inspect the source at:

engineering/agenthub/skills/merge/SKILL.md

This skill appears to be self-contained in SKILL.md; there are no visible companion rules/, resources/, or scripts/ folders in the skill directory preview. Because the upstream instructions reference session_manager.py, verify where that script exists in your local AgentHub setup before relying on automated cleanup.

Basic merge usage

Typical calls are:

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

Use /hub:merge when the latest evaluated session is the target. Provide a session ID when multiple AgentHub sessions exist. Add --agent only when you intentionally override the top-ranked /hub:eval result, such as when the highest score missed a security, compatibility, or product requirement that human review caught.

Inputs the skill needs

For reliable merge usage, the agent needs:

• The target base branch, usually the branch you want the winning work landed into.
• The AgentHub session ID, unless the latest session is unambiguous.
• A winner, either from the latest evaluation ranking or from --agent.
• Existing branch refs in the expected format: hub/{session-id}/{agent-id}/attempt-1.
• Permission to run Git operations that create merge commits, tags, and branch deletions.

A stronger prompt is: “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.” This gives the skill enough operational context to avoid guessing.

Practical workflow before and after running

Before calling merge, run git status, confirm you are not carrying unrelated local changes, and review the winning diff. After the merge, check the merge commit message, confirm archive tags were created, and verify .agenthub/board/results/merge-summary.md reflects the session, task, and winner. If conflicts appear, resolve them as normal Git conflicts; the skill provides workflow structure, not a substitute for code review.

merge skill FAQ

Is merge only for AgentHub?

Yes, in practice. The merge skill is written around AgentHub naming, evaluation, and cleanup conventions. It can inspire a manual Git Workflow for other multi-branch experiments, but direct use expects AgentHub session branches and result metadata.

Does merge choose the best code automatically?

It chooses the --agent you specify, or otherwise the top-ranked agent from the most recent /hub:eval. That means the quality of the merge depends on the quality of the prior evaluation. If your evaluation criteria were incomplete, review the winner manually before merging.

What happens to losing branches?

The intended workflow archives each losing agent branch with a Git tag such as hub/archive/{session-id}/{agent-id} and then deletes the branch ref. This keeps the commits reachable while reducing branch clutter. Teams with retention policies should confirm archive tag naming before adopting the skill.

When should I not use this skill?

Do not use merge if branch names do not follow the AgentHub convention, if the base branch is uncertain, if the winner has not been reviewed, or if your repository forbids automated branch deletion. It is also a poor fit for squash-only workflows unless you adapt the merge command, because the skill’s default pattern uses git merge --no-ff.

How to Improve merge skill

Improve merge results with clearer context

The merge skill works best when your request includes the session ID, winner, base branch, and any policy constraints. For example: “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.” This is better than “merge the winner” because it separates selection, destination, cleanup, and safety rules.

Common failure modes to watch

The main risks are ambiguous latest sessions, missing evaluation results, dirty working trees, branch refs that do not match the expected pattern, and cleanup commands that depend on files outside this skill directory. Another important risk is merging a technically passing but product-wrong winner. Treat /hub:eval as selection input, not a replacement for final review.

Adapt merge for your repository policy

If your team requires squash merges, signed commits, protected branches, pull requests, CI gates, or remote branch retention, edit the workflow before using it in production. The most likely customization points are the merge strategy, the archive tag format, whether branch deletion is local-only, and what fields are required in merge-summary.md.

Iterate after the first run

After the first output, ask the agent to verify rather than continue blindly: “Show the merge commit, list archive tags for this session, confirm no AgentHub worktrees remain, and summarize any conflicts or skipped cleanup.” This turns the merge guide into an auditable Git Workflow and helps catch partial cleanup before the session is forgotten.