Resolving Merge Conflicts —— Skills for Resolving Git Merge Conflicts

Skill Overview

Resolving Merge Conflicts is a skill that enables an AI agent to take over an in-progress merge or rebase conflict: it first examines the repository status and conflicted files, then traces the source and original intent of each change, resolves conflicts block by block while preserving both sides’ objectives whenever possible, and finally runs the project checks, stages the changes, and commits them to truly complete the merge.

Applicable Scenarios

1. Conflicts when merging branches in a collaborative project: Both branches have modified the same set of files, and git merge is stuck in a conflicted state. Someone needs to understand both sides’ changes and decide how to combine them, rather than arbitrarily choosing one side.

2. Resolving conflicts before merging a PR: After pulling the main branch, the PR branch is found to conflict with it. The goal is to integrate your changes without breaking the main branch’s behavior, while explaining the trade-offs when both sides cannot be preserved simultaneously.

3. Rebasing a long-lived branch onto the main branch: A rebase may produce conflicts across multiple commits. The skill requires resolving each commit’s conflicts one by one and continuously running --continue until the entire rebase is complete, rather than stopping halfway through.

Core Functions

1. Check the status before modifying code: Inspect the Git history and conflicted files to determine whether the repository is currently in a merge or rebase, which files are conflicted, and which commits are involved. This prevents starting to edit files without first understanding the situation.

2. Trace the original intent behind conflicts: Identify the primary source of each conflict by reading commit messages, reviewing the PR, and checking the original issue or ticket. Understand why each side made its change before deciding how to resolve the conflict.

3. Resolve conflicts block by block while preserving both sides’ goals: Preserve both sides’ intentions whenever they can coexist. When they are genuinely mutually exclusive, choose the side aligned with the objective of the current merge and document the trade-off. The skill explicitly prohibits inventing new behavior and explicitly prohibits using --abort: conflicts must always be resolved, not bypassed.

4. Complete the process after passing automated checks: Identify the project’s built-in check workflow (typically type checking → tests → formatting), fix anything broken by the merge, then stage all changes and commit them. If this is a rebase, continue until all commits have been successfully rebased.

Frequently Asked Questions

Can I simply run git merge --abort to give up while resolving conflicts?

No. This skill makes “always resolve, never abort” a hard requirement. Abandoning a merge merely postpones the conflict for the next person and loses the context that has already been clarified. The correct approach is to understand both sides’ intentions and resolve the conflicts.

How do I continue after resolving a conflict during a rebase?

Unlike a merge, a rebase may produce conflicts for every commit being rebased. After resolving the conflicts for the current round and running the checks, you must continue according to the rebase workflow with git rebase --continue, then repeat the process for any conflicts in subsequent commits until the entire rebase is complete—not treat the task as finished after resolving just one conflict.

How can I tell who made each change and why?

The skill requires going back to primary sources: inspect the commit messages, the corresponding PR, and the original issue or ticket. Only after understanding the original intent of each side can you determine whether the changes can coexist or whether one must be chosen over the other.

What should I do when both sides’ changes are reasonable but cannot both be preserved?

First, try to preserve both sides’ intentions. Only when they are genuinely incompatible should you choose the side aligned with the established objective of the current merge, and clearly record the trade-off. The skill does not allow inventing logic that did not previously exist merely to “make the conflict disappear.”

Which checks should be run after resolving conflicts?

The skill first identifies the project’s own automated check workflow, typically type checking, tests, and formatting. Anything broken by the merge must be fixed, and the changes should be staged and committed only after the checks pass.

Which tools does it apply to?

This is a skill file for AI programming agents (in the form of SKILL.md) that takes effect in programming assistants supporting a skill mechanism, such as Claude Code. It governs how the agent handles conflicts and does not depend on any particular language or framework. It can be used with any project that uses Git.

Could it miss a conflict when there are many?

The first step of the skill is to list all conflicted files, and the third step requires resolving each hunk individually. The final stage also runs checks as a safeguard. Compared with “fixing a few conflicts and committing,” this workflow is much less likely to leave unresolved conflict markers behind.