agentleFS
tbhbtbhb/vale-ai-tells/.claude/skills/merge-pr/SKILL.md

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

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.
  • GoogleSkill

    implement-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

  • SentrySkill

    create-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

  • sahinSkill

    create-issue

    Also in 3 projects that use this

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
  1. Very specific:

    Write the squash message in SQUASH_AGENTMSG

    line 39
  2. Distinctive:

    Run the commit-msg gates

    line 41
  3. Distinctive:

    Stop before any of it where preflight reports a missing precondition, a draft pull request, or a failing check.

    line 45
  4. Very specific:

    Read what preflight printed under == description as published == against the commits it collapses.

    line 69
  5. Distinctive:

    Check the closing references before going on.

    line 119
  6. Distinctive:

    commit-trailers for trailer order

    line 142
  7. Distinctive:

    Follow the answer. Revising sends you back through the review, because the gate compares bytes.

    line 175

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

  1. Confirm the pull request is mergeable
  2. Settle the published description
  3. Write the squash message in SQUASH_AGENTMSG
  4. Review the message with review-squash-message
  5. Run the commit-msg gates
  6. Confirm the message with the operator
  7. 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-msg

The 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:

LabelDescription
Merge itThe subject line, verbatim
Revise the messageRedraft the message, review it again, and come back.
Wait on the checksHand this to watch-pr first, and merge once it reports green.
Stop hereLeave 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

  • gh installed and authenticated
  • a mise run lint-squash-msg task
  • a gitignore entry for SQUASH_AGENTMSG
  • the review-squash-message skill deployed alongside this one

Preflight checks each. Where one is missing, tell the operator rather than improvising a substitute.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.