# Merge One

> Use when a user explicitly wants to land a single PR now via gh: readiness-gated, CI-watched, a merge commit in the repo's style, trunk synced.

- Skill: `tony/merge-one` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add tony/merge-one`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tony/merge-one/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tony (https://skillmd.com/u/tony)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/tony/merge-one

---


# Merge One PR

Merge a single pull request (the one this conversation is about, or the one
the current branch belongs to) via `gh pr merge`. Nothing merges until the
readiness gate passes. Report only what a command in this run verified.

Read `../../references/merge-readiness.md` before touching the PR.

User arguments: $ARGUMENTS

## Procedure

### 1. Identify the PR

Precedence: an explicit argument (number or URL) > the PR this
conversation has been working on > the current branch's PR. If the
candidates disagree, ask via `AskUserQuestion` before proceeding; without a
question tool, halt and list them.

With no argument and no conversation PR, run `git branch --show-current`
and `gh pr view --json number` to find the current branch's PR.

Gather the PR's state. A failure here means no PR exists for the branch or
`gh` is unavailable or unauthenticated: report it and stop. The readiness
gate reuses this read. When the user passed `--repo`, add it to this command
and every other `gh` call, and check the repo scope as the reference
describes.

```console
$ gh pr view <n> --json number,title,url,state,isDraft,baseRefName,headRefOid,mergeable,mergeStateStatus,reviewDecision
```

Trunk is the PR's `baseRefName`.

### 2. Run the readiness gate

Apply the readiness gate from the reference. If the PR is `BEHIND` or
`DIRTY` and the repo scope is `local`, confirm with the user, then follow the
reference's rebase procedure. Without a question tool, halt instead of
rebasing. With scope `remote`, halt: the rebase cannot run here.

### 3. Compose the merge commit message

Check the repo allows the strategy, per the reference's strategy section.
Then follow its merge-commit-message section, which also says when to skip
it (`--rebase`, or a message flag from the user). Write the message per
`../../references/prose-rules.md`. The message carries no `Co-Authored-By`,
no "Generated with" or other tool trailer, and no emoji.

### 4. Merge

Pass the user's `gh pr merge` flags through verbatim, with the strategy flag
and the reference's `--match-head-commit <sha>` pin. Pass the composed message through the
reference's `merge_pr.py merge` command, never inside a shell string. Use
`--admin` only within the reference's policy.

### 5. Sync trunk and stand by

Sync trunk and confirm the merge, per the reference's "After each merge",
including its check that trunk contains the merge commit. Then stop.
When the merge is only queued (`--auto`, or `state` still `OPEN` after the
merge), open with the queued hero and skip the sync.

## Output

Open with a one-line hero (`✓ Merged #N: <title>`,
`✓ Queued #N: <title>` for an `--auto` merge, `⚠ Blocked: <reason>`, or
`⚠ Merged #N: <title>; <trunk fact>` when the PR merged but the
contains-the-merge-commit check failed or the subject was not verified,
so the first line is never a false success),
then exactly these sections. A run that stops before
the merge (including `gh` unavailable: `⚠ Blocked: gh is not authenticated`)
gives the hero and one sentence on what the user must do; no
headings, and never a sentence saying what was not done ("nothing was
merged", "I did not use --admin"). The hero states the cause only.

1. `## Merge readiness`: the gate results, including anything that
   required a rebase or a wait on CI.
2. `## Merge`: the strategy, the merge commit short SHA with its subject
   as read back from the commit, and the PR URL. A queued merge gives the
   strategy and the PR URL (its reply keeps all three sections; see the
   queued example). Name a flag only when the run dropped or added
   one the user did not pass; never the head pin or the user's own flags.
   Say nothing about the title's characters or how the message was passed.
3. `## Trunk`: the post-merge trunk state and the result of the
   contains-the-merge-commit check, or that the sync was skipped and why.
   Report a mismatch as a fact with the short SHAs; give no cause and do
   not narrate how the pull was run.

State a failure as the fact the user needs; never quote the tool's error
text or explain how a check works. Follow the reference's "Report wording".
Write the sections per `../../references/prose-rules.md`, impersonally:
no first person.

Reply in this shape, as plain text outside any code fence, with plain
bullets, no bold (never `- **Label:** ...`), and no local paths:

```text
✓ Merged #31: Retry transient sync failures

## Merge readiness

- Open, not a draft. CI green on the head after a wait on the lint job.
- Behind main by one commit; rebased and force-pushed with the user's approval; previous head 3b1c9e4.

## Merge

- Strategy --merge, no extra flags. Merge commit 4f2a9c1: "sync(fix[client]) Retry transient network errors (#31)".
- https://github.com/acme/widgets/pull/31

## Trunk

- main is at the merge commit; local main fast-forwarded.
```

A queued run (`--auto`) uses the same three sections, with readiness as
in a merged run:

```text
✓ Queued #31: Retry transient sync failures

## Merge readiness

- Open, not a draft. CI green on the head.

## Merge

- Strategy --squash. GitHub merges it once the required checks pass.
- https://github.com/acme/widgets/pull/31

## Trunk

- Sync skipped: the merge has not happened yet.
```

A merged PR whose trunk check failed:

```text
⚠ Merged #42: Retry transient sync failures; local main does not contain merge commit 4f2a9c1.

## Merge readiness

- Open, not a draft. CI green on the head.

## Merge

- Strategy --squash. Merge commit 4f2a9c1; the subject was not verified.
- https://github.com/acme/widgets/pull/42

## Trunk

- Local main is at 9ad03e1, which does not contain 4f2a9c1.
```

A stopped run:

```text
⚠ Blocked: #42 needs an approving review before branch protection allows the merge.

Get the review, or approve --admin.
```

End with an `AskUserQuestion` panel offering next steps (for example:
cut a release from the merged trunk, merge another PR, delete the
local branch, stop here); skip the panel in plan mode. Without a question
tool, end after the sections and say nothing about the missing panel; no
`## Next steps` section.

Offer the release only when the merged trunk is in a releasable state and
the repo carries the version files a release touches. Name the project's
release skill or command if one exists; tagging and pushing stay the user's
explicit act.

