merge-conflict-resolution
Skill174 starsChanged 2 months agoMITView on GitHub
Resolve git merge/rebase conflicts safely without losing intended changes.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- anur4ag/pr-completiontheir own version, first seen Sep 14, 2026
- alexgrebeshok-coder/dirigent-skillstheir own version, first seen Jul 12, 2026
- kimtth/agent-skill-100-lines-or-lesstheir own version, first seen Jun 26, 2026
- mlopscommunity/Coding-Agents-Conference-skillstheir own version, first seen Mar 4, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- mlopscommunity/Coding-Agents-Conference-skills★ 38same name
- anur4ag/pr-completion★ 4same name
- kimtth/agent-skill-100-lines-or-less★ 2same name
- alexgrebeshok-coder/dirigent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-runtimeSkill
- arc42-documentationSkill
- authoring-rolesSkill
- context-packSkill
- create-agent-skillSkill
- create-pr-azdoSkill
- create-pr-githubSkill
- detect-diagram-crossingsSkill
- flowchart_layout_optimizerSkill
- generate-demo-artifactsSkill
- generate-release-screenshotsSkill
- git-rebase-mainSkill
- merge-conflict-resolutionSkill
- next-issue-numberSkill
- pre-pr-checklistSkill
- retrospective-evidenceSkill
- run-dotnet-testsSkill
- run-uatSkill
- run-workflowSkill
- update-test-snapshotsSkill
- update-workflow-diagramSkill
- view-pr-githubSkill
- watch-uat-azdo-prSkill
- watch-uat-github-prSkill
- website-accessibility-checkSkill
- website-create-examplesSkill
- website-devtoolsSkill
- website-quality-checkSkill
- website-visual-assetsSkill
- agent-runtimeSkill
- arc42-documentationSkill
- authoring-rolesSkill
- context-packSkill
- create-agent-skillSkill
- create-pr-azdoSkill
- create-pr-githubSkill
- detect-diagram-crossingsSkill
- flowchart_layout_optimizerSkill
- generate-demo-artifactsSkill
- generate-release-screenshotsSkill
- git-rebase-mainSkill
- next-issue-numberSkill
- pre-pr-checklistSkill
- retrospective-evidenceSkill
- run-dotnet-testsSkill
- run-uatSkill
- run-workflowSkill
- update-test-snapshotsSkill
- update-workflow-diagramSkill
- view-pr-githubSkill
- watch-uat-azdo-prSkill
- watch-uat-github-prSkill
- website-accessibility-checkSkill
- website-create-examplesSkill
- website-devtoolsSkill
- website-quality-checkSkill
- website-visual-assetsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. 0 are common, 20 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
20
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
If the intent of either change is unclear, ask the user questions until it is clear.
- Very specific: line 34
Verify that no conflict markers remain (<<<<<<<, =======, >>>>>>>).
- Distinctive: line 35
Verify that git status shows no unmerged paths.
- Distinctive: line 42
Commit a conflict resolution without reviewing the resulting diff.
- Very specific: line 46
If the conflict touches source-of-truth docs (e.g., docs/spec.md, docs/architecture.md) and the correct content is not unambiguous from the …
- Distinctive: line 48
If the two change intents are contradictory (both cannot be true at the same time), you must ask the user to choose a direction.
- Distinctive: line 52
Before you modify any conflicted file, produce an explicit analysis in chat using this template:
- Distinctive: line 74
If you cannot confidently state the intent for both changes, stop and ask.
- Distinctive: line 78
If you are in doubt about the intent of a change, ask questions until you understand it.
- Distinctive: line 90
Use git to confirm the conflict state and list conflicted files:
- Very specific: line 152
Prefer your harness's file-search tool over a shell grep to search for <<<<<<<, =======, and >>>>>>>
- Distinctive: line 157
After conflicts are resolved, validate correctness based on file type:
- Distinctive: line 160
Ensure the resulting documentation captures the intent of both changes and no relevant information is lost.
- Distinctive: line 161
Ensure the docs do not contain contradictory statements introduced by the merge.
- Distinctive: line 162
Check for common merge-regressions:
- Distinctive: line 166
If there are contradictions, resolve them explicitly or ask the user which statement is correct.
- Distinctive: line 169
Ensure all tests pass.
- Distinctive: line 170
Ensure the intended new features or behavior changes of both changes still work.
- Distinctive: line 171
If tests exist for the changed area, run those first.
- Distinctive: line 175
If this is a merge:
- Distinctive: line 182
If this is a rebase:
- Distinctive: line 191
When you create a commit that resolves conflicts, the commit message must describe:
- Distinctive: line 214
If you get stuck, prefer asking for guidance over guessing.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Merge Conflict Resolution
Purpose
Prevent accidental loss of intended changes when a git merge or rebase hits conflicts (e.g., documentation regressions like the docs/architecture.md incident referenced in Feature 024).
This skill is intended for any agent that can commit changes.
Core Principle
A conflict is not a “choose ours/theirs” problem — it’s an intent reconciliation problem.
You must understand the intent of both changes before resolving anything. The correct resolution depends on intent, not on which side is main.
Often the right answer is “keep the intent of both changes”, which may require a manual edit that combines or restructures content.
Sometimes, intent is genuinely contradictory and cannot be resolved automatically. In that case, ask the user how to proceed.
Hard Rules
Must
- Analyze both sides first:
- Identify what each side is trying to achieve (intent).
- Identify which parts are compatible (can be merged) vs contradictory (need a decision).
- If the intent of either change is unclear, ask the user questions until it is clear. Do not guess.
- Resolve conflicts by editing the conflicted file(s) (not by blindly choosing one side).
- After resolution:
- Verify that no conflict markers remain (
<<<<<<<,=======,>>>>>>>). - Verify that
git statusshows no unmerged paths. - Validate that the resolved content preserves the intent of both changes (or reflects an explicit user decision when intent conflicts).
- Verify that no conflict markers remain (
Must Not
- Blindly run
git checkout --ours <file>/git checkout --theirs <file>without validating intent. - “Resolve” by deleting sections just to make conflicts disappear.
- Commit a conflict resolution without reviewing the resulting diff.
When to Ask the Maintainer
If the conflict touches source-of-truth docs (e.g., docs/spec.md, docs/architecture.md) and the correct content is not unambiguous from the current task context, you must ask the maintainer which version to keep/merge before committing.
If the two change intents are contradictory (both cannot be true at the same time), you must ask the user to choose a direction. Do not attempt to “average” or invent a new intent.
Required Analysis (Before Editing)
Before you modify any conflicted file, produce an explicit analysis in chat using this template:
Conflict analysis
Change A intent:
- <what this change is trying to achieve>
Change B intent:
- <what this change is trying to achieve>
Compatibility:
- Compatible / Partially compatible / Contradictory
- Notes: <why>
Proposed resolution:
- <how you will preserve the intent of both changes>
Open questions (must answer before proceeding):
- <question 1>If you cannot confidently state the intent for both changes, stop and ask.
Clarifying Questions (When Intent Is Unclear)
If you are in doubt about the intent of a change, ask questions until you understand it. Useful prompts:
- “Which behavior/statement should be true after this merge?”
- “Is this change a refactor (no behavior change) or a behavior change?”
- “Do we need to keep both changes, or should one override the other?”
- “If both changes cannot be kept, which one is more important and why?”
- “Is there a spec/issue/PR description that defines the intended outcome?”
Workflow (Recommended)
0. Confirm you are actually in a conflict
Use git to confirm the conflict state and list conflicted files:
git status
git diff --name-only --diff-filter=U1. Identify conflicted files
git status
# or (machine-friendly)
git diff --name-only --diff-filter=U2. Understand “ours” vs “theirs”
- During a merge:
- “ours” = current branch (where you ran
git merge ...) - “theirs” = the branch you’re merging in
- “ours” = current branch (where you ran
- During a rebase:
- “ours” / “theirs” semantics are different — prefer reading the conflict markers and using diffs rather than relying on naming.
3. Inspect what each side changed
For each conflicted file:
# See conflict hunks and surrounding context
sed -n '1,200p' <file>
# Compare current index stages (2=ours, 3=theirs) if available
# (These commands are safe even if a stage is missing.)
git show :2:<file> 2>/dev/null | head -50 || true
git show :3:<file> 2>/dev/null | head -50 || trueWhile inspecting, explicitly determine intent:
- What was added/removed/renamed, and why?
- Is one side a refactor and the other a feature? If yes, the resolution often needs both.
- Are there invariants that must remain true (docs accuracy, API behavior, tests)?
4. Resolve conflicts intentionally
- Edit the file to combine the correct parts from both sides.
- Remove conflict markers.
- Preserve required sections (especially for documentation).
5. Verify resolution quality
# Review what you’re about to commit
git diff
# Ensure git sees conflicts as resolved
git statusAlso do a repo-wide check that no conflict markers remain. Prefer tooling that searches files directly (no scripts required), for example:
- VS Code Search panel: search for
<<<<<<<,=======, and>>>>>>> - Prefer your harness's file-search tool over a shell grep to search for
<<<<<<<,=======, and>>>>>>> - Optional fallback (terminal):
git grep -n '^<<<<<<< ' || true(repeat for the other markers)
6. Validate the meaning, not just the markers
After conflicts are resolved, validate correctness based on file type:
- Documentation changes:
- Ensure the resulting documentation captures the intent of both changes and no relevant information is lost.
- Ensure the docs do not contain contradictory statements introduced by the merge.
- Check for common merge-regressions:
- Deleted or duplicated headings/sections
- Outdated statements reintroduced
- Partial merges where one side’s detail vanished
- If there are contradictions, resolve them explicitly or ask the user which statement is correct.
- Code changes:
- Ensure all tests pass.
- Ensure the intended new features or behavior changes of both changes still work.
- If tests exist for the changed area, run those first; then broaden if needed.
7. Continue or conclude
If this is a merge:
git add <file>... git commitIf this is a rebase:
git add <file>... git rebase --continue
Commit Message Requirement (For Merge Conflict Resolutions)
When you create a commit that resolves conflicts, the commit message must describe:
- Which files had conflicts (high level)
- How the conflict was resolved (e.g., “combined both intents”, “kept X and adapted Y to match”, “user chose A over B”)
- Why this resolution preserves the intended behavior/documentation
Template:
<type>: resolve merge conflicts
Conflicts:
- <file/group>: <what conflicted>
Resolution:
- <how you preserved intent of both changes OR what decision was made>
Why:
- <why this is correct>Notes
- If you get stuck, prefer asking for guidance over guessing. A wrong conflict resolution can silently ship broken docs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

