merge-pr
Skill118 starsChanged 37 days agoMITView on GitHub
Squash merge a pull request. The commit message comes from this workflow rather than from GitHub, whose own version concatenates every commit on the branch into text no linter ever reads. A briefing script prints the published description, every commit the squash collapses, and the diffstat, then leaves a SQUASH_AGENTMSG skeleton whose body the caller writes. Review, the commit-msg gates, and an operator confirmation all run before the merge. Use this whenever the user asks to merge or land a pull request, including one nobody here authored such as a dependency bump.
18 other projects use a version of this.
Adopted by
Most recently taken up by
- kratocz/skillstheir own version, first seen Nov 15, 2026
- kdy1/kdy1-scriptstheir own version, first seen Nov 15, 2026
- developerz-ai/open-mmorpgtheir own version, first seen Nov 10, 2026
- mihai-dinculescu/tapotheir own version, first seen Nov 9, 2026
- ddnexus/pagytheir own version, first seen Nov 9, 2026
- ShareX/ShareXtheir own version, first seen Nov 8, 2026
Used with
Projects with it also use implement-issue, create-pr and 1 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
GoogleSkillimplement-issue
Implement a Site Kit GitHub issue end-to-end from its implementation brief. Use when the user asks to implement, build, or work on a GitHub issue / feature by number (e.g. "implement issue #12345", "build the feature in issue 12345", "follow the implementation brief for #12345") in the google/site-kit-wp repo.
Also in 3 projects that use this
SentrySkillcreate-pr
Create pull requests following Sentry conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review. Follows Sentry's code review guidelines.
Also in 7 projects that use this
sahinSkillcreate-issue
Also in 3 projects that use this
Other versions18 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 18
- ShareX/ShareX★ 41ksame name
- cube-js/cube★ 21ksame name
- ddnexus/pagy★ 5ksame name
- mihai-dinculescu/tapo★ 877same name
- bazel-contrib/rules_python★ 695same name
- kkokosa/dotLLM★ 528same name
- r3bl-org/r3bl-open-core★ 486same name
- TermiX-official/cryptoclaw★ 100same name
- kdy1/kdy1-scripts★ 34same name
- neul-labs/openclawMU★ 33same name
8 more not listed
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 repository32 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- analyze-sessionSkill
- codex-analyze-sessionSkill
- codex-commitSkill
- codex-fix-proseSkill
- codex-fix-prSkill
- codex-merge-prSkill
- codex-prSkill
- codex-rebaseSkill
- codex-resolve-rebase-conflictsSkill
- codex-review-commit-messageSkill
- codex-review-pr-descriptionSkill
- codex-review-prose-fixSkill
- codex-review-squash-messageSkill
- codex-watch-prSkill
- codex-write-pr-descriptionSkill
- codex-write-prose-fixSkill
- commitSkill
- fix-proseSkill
- fix-prSkill
- prSkill
- rebaseSkill
- releaseSkill
- resolve-rebase-conflictsSkill
- review-commit-messageSkill
- review-pr-descriptionSkill
- review-prose-fixSkill
- review-squash-messageSkill
- watch-prSkill
- write-pr-descriptionSkill
- write-prose-fixSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 18 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 39
Write the squash message in SQUASH_AGENTMSG
- Distinctive: line 41
Run the commit-msg gates
- Distinctive: line 45
Stop before any of it where preflight reports a missing precondition, a draft pull request, or a failing check.
- Very specific: line 69
Read what preflight printed under == description as published == against the commits it collapses.
- Distinctive: line 119
Check the closing references before going on.
- Distinctive: line 142
commit-trailers for trailer order
- Distinctive: line 175
Follow the answer. Revising sends you back through the review, because the gate compares bytes.
“Common” is measured: kept by at least 6 in 10 of the 18 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 a pull request
Work the steps in order. A pair of hooks runs alongside them and refuses the shortcut: a direct gh pr merge, and any merge whose message the reviewer hasn't seen in its current form.
Left alone, GitHub writes the squash message by concatenating every commit on the branch. That text has never passed a commit-msg hook, and it arrives on the default branch where the rest of the toolchain assumes those hooks ran. The toolchain never lints it after the merge, either. This workflow writes the message itself and puts it through the same checks a commit must pass.
Preflight
!bash ${CLAUDE_SKILL_DIR}/scripts/preflight.sh ${ARGUMENTS}
Step 0: the checklist
Track these steps with the session's task-list tools where the session provides them. Newer harnesses leave those tools out by default, and a session without them works the list in order as written.
- Confirm the pull request is mergeable
- Settle the published description
- Write the squash message in SQUASH_AGENTMSG
- Review the message with review-squash-message
- Run the commit-msg gates
- Confirm the message with the operator
- Merge and clean up
Stop before any of it where preflight reports a missing precondition, a draft pull request, or a failing check. Say what's wrong and hand back.
Step 1: confirm the pull request is mergeable
Preflight printed the state, the check rollup, and the review decision. Merging needs an open pull request that nobody marked as a draft, with every check green.
A failing check goes to fix-pr, and a running one goes to watch-pr. Neither belongs here, and the merge script refuses both anyway.
A mergeStateStatus of BEHIND or DIRTY is the third case. The branch needs the base underneath it before anything merges, so run the rebase skill and push the result. Don't reach for GitHub's own update button: it merges the base into the branch, which leaves a merge commit this workflow never wrote a message for.
Where the repository requires a review decision, respect it. CHANGES_REQUESTED means the merge waits, whatever the checks say.
Step 2: settle the description first
The description is on GitHub at this point, and often nothing sits on disk. Fetch it back before revising it:
bash .claude/skills/merge-pr/scripts/populate-description.sh <number>That rebuilds PR_AGENTDESC.md from what the pull request currently says, reassembling the frontmatter from the properties set on the pull request. It refuses to overwrite an existing draft without --force, because a pr workflow further up the stack may have one in flight.
Merging is the last moment the description can change, and you write the squash message from it, so a wrong description propagates that error into history.
Read what preflight printed under == description as published == against the commits it collapses. Where it no longer describes the branch, invoke write-pr-description with the repository root and a note on what drifted, then review-pr-description, then republish with bash .claude/skills/pr/scripts/create-pr.sh.
Most merges skip this. A description that still fits doesn't need a pass, and a pull request nobody here authored has none of this machinery behind it, so take its description as it stands.
Step 3: write the squash message
bash .claude/skills/merge-pr/scripts/squash-message.sh <number>That prints a briefing and writes a skeleton, but it doesn't convert the description into a message, because no rewriting rule produces one. The commit that merges here is the one a whole branch leaves behind, so writing it means reading every commit on the branch and working out what a reader years from now still needs.
Your briefing carries the description as published, every commit message the squash collapses in full, the diffstat, and the trailers on those commits. Read it before writing a word. Commit bodies matter most. Each one already argued for itself once, and this is the last place that argument still appears. Run the command on its own and read the whole thing. Piping it through head or tail keeps the trailing skeleton and drops those bodies, which nothing else in this workflow prints, and the script caps nothing on purpose, so a cap you add is one nobody downstream can see you added.
Its skeleton goes to SQUASH_AGENTMSG at the repository root, a file a gitignore entry keeps out of history. Subject and footer come filled in, and the body is empty until you write it.
Subject
The script sets <pull request title> (#<number>). Keep the reference, because squash-merge.sh reads it back to confirm the draft belongs to this pull request. Fix the rest where the title described one commit rather than the branch. A squash leaves one commit behind. Its subject has to describe what the whole stack did.
Body
The description was Markdown, written for a reviewer with the diff open beside it. This is plain text, and whoever reads it three years from now has neither.
Take from the description:
- Summary and Why, which state the reason the branch exists
- Risk, but only where it describes a rollback the reader wouldn't guess
Leave behind:
- Verification, entirely. It reported what a reviewer needed at the time, and the moment the suite changes it describes a run nobody can repeat.
- Risk that only says the change could be wrong.
Then read the result back against the commits. Trust the commits over it. Authors publish descriptions early while branches keep growing, and the commits record what landed rather than what someone expected to land. Where a commit body gives a reason the description never stated, that reason belongs in the message. Otherwise it goes at the merge, with the commit that held it.
Avoid:
- Restating the diff. A reader who wants the what reads the diff.
- Walking the stack. A branch of eight commits becomes one account rather than eight paragraphs.
- Counting. No file, line, test, or commit counts.
- Provenance filler. Nothing about requests, review rounds, sessions, prompts, models, or tools.
- Markdown, meaning fenced blocks, headings, emphasis, links, or tables. Backticks around a literal identifier are fine.
Hard wrap the body at 72 characters and the trailers at 100.
Footer
The script fills this in. Closes lines come from the description's Related section, and the trailers come from the commits themselves, ordered with attribution first and sign-off last.
Check the closing references before going on. Related lists whatever the author put there, so a number that refers to a pull request or a document rather than an issue this branch closes comes out of the footer.
Step 4: review the message
Invoke the review-squash-message skill, passing the repository root as its argument. It runs as an independent agent that hasn't watched you work, and it reads the message against every commit the squash collapses. Its first question is the one you can no longer ask yourself by this point: whether the message left out anything that mattered in those commits.
This step is mandatory, and the merge script enforces it. A clean verdict signs the exact bytes of the draft, a finding erases any earlier signature, and editing the draft afterward voids it the same way.
Fix everything it returns. Push back only where it's demonstrably wrong about the commits, and say why.
A finding cites one instance rather than the fault itself. Fix the instance, then read the rest of the message for the same fault, because a reviewer that found one instance finds the next one on the next round.
Step 5: run the commit-msg gates
mise run lint-squash-msgThe same four hooks a commit must pass:
- vale under the commit scope, which catches AI tells through
ai-tells-commits - cspell with the commit dictionary
- commitlint for the Conventional Commits shape
- commit-trailers for trailer order
Resolve every finding. Edited the draft to clear them? Then step 4 runs again, because the gate compares bytes rather than intentions.
Step 6: confirm with the operator
AskUserQuestion truncates its options. The operator has to read the message in your message text rather than in the widget. Print this first, verbatim:
Merging: #<number> <title>
Into: <base branch>
Commits: <count> collapsing into one
<the entire SQUASH_AGENTMSG contents, verbatim>Preflight answered this under == pre-approval ==. Where it reported merge: GRANTED, the operator answered this question for the whole session in advance, through mise run preapprove merge. Print the preceding block so the operator still sees the message, state the grant this merge goes under, and move to step 7 without calling AskUserQuestion.
The grant answers one question, merge under this message. Ask anyway where any of these holds:
- the review returned a finding nobody acted on
- the checks aren't green
- this pull request isn't the one the session set out to merge, which covers a dependency bump nobody here authored unless the operator named it
Where preflight reported merge: not granted, call AskUserQuestion with question set to Squash merge with this message?, header set to Merge, multiSelect set to false, and these four options in order:
| Label | Description |
Merge it | The subject line, verbatim |
Revise the message | Redraft the message, review it again, and come back. |
Wait on the checks | Hand this to watch-pr first, and merge once it reports green. |
Stop here | Leave the pull request, the draft, and the branch untouched. |
Follow the answer. Revising sends you back through the review, because the gate compares bytes.
Step 7: merge and clean up
bash .claude/skills/merge-pr/scripts/squash-merge.sh <number>That script re-runs every gate before it touches anything. It checks that the message references this pull request, that the signature matches the bytes on disk, that the linters pass, and that the pull request is open, ready, and green. Then it merges, removes SQUASH_AGENTMSG and PR_AGENTDESC.md along with their signatures, and deletes the merged branch.
Cleanup falls to the script that watched the merge succeed, because there's no post-merge hook to run it from.
Report the merged commit. Where this worktree stands on the branch that merged, the script says so rather than deleting the branch out from under the session. The operator decides whether to switch or drop the worktree.
Preconditions
ghinstalled and authenticated- a
mise run lint-squash-msgtask - a gitignore entry for
SQUASH_AGENTMSG - the
review-squash-messageskill deployed alongside this one
Preflight checks each. Where one is missing, tell the operator rather than improvising a substitute.
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.

