/generate-pr

name: generate-pr
description: 'Generate a complete pull request when the user asks to create/open a PR, fill the PR template, or mentions "/generate-pr". Fills every section of .github/pull_request_template.md from the branch diff and commits, ticking only the boxes the evidence supports. Discovers the repository''s own branch flow rather than assuming one; aborts if a secret is in the diff; updates the open PR for the branch instead of opening a duplicate.'
license: MIT
allowed-tools: Bash, Read, Write
argument-hint: "[target branch]"

Generate a Pull Request

When this skill runs

**Only when the operator invokes it** — `/generate-pr`, or an explicit request to open or fill a PR in their own words. A pull request exists for one purpose: promoting the working branch to the branch that releases.

A PR is never opened on an agent's own initiative — not to trigger CI, not to summarise a branch, not because the work looks finished. Reading PR state to answer a question (`gh pr list`) is ordinary; creating one is not. Pushing to the working branch is a separate act under its own rule (the `git-commit` skill) and never implies a PR.

Overview

Produce a fully-filled pull request — every applicable section of `.github/pull_request_template.md`, every checkbox the **evidence** supports — and open or update the PR.

Portability

Every command here is POSIX shell and runs on macOS, Linux, WSL2 and Git Bash — no GNU-only flags, so BSD userland on macOS behaves identically. On native Windows without [Git for Windows](https://git-scm.com/downloads/win), Claude Code runs commands through PowerShell, which cannot execute them; translate them or install Git for Windows.

`git` is required. `gh` is optional — without it, or unauthenticated, the skill writes the finished body to `out/pr-body.md` and prints the command to run, which is also how you test it without opening a real PR. `jq` is optional and every use below has a fallback, because neither macOS nor Windows ships it.

Branch policy — read it, do not assume it

Repositories differ: trunk-based, a long-lived integration branch, short-lived feature branches, Git Flow. Establish this repository's flow before opening anything, from what the repository actually says:

git rev-parse --abbrev-ref HEAD                                  # where you are
git branch -a --format='%(refname:short)'                        # what exists
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null    # the remote's default branch
grep -rniE 'branch|pull request' CLAUDE.md CONTRIBUTING.md .github/*.md 2>/dev/null | head

The target defaults to the remote's default branch, and `$1` overrides it. If the current branch **is** the target, there is nothing to promote — stop and say so. Where the repository documents a flow, follow it; where it documents none and the branch is an ordinary working branch, the default branch is the target. Creating a branch is outside this skill.

**Deterministic facts versus written prose.** You are the one writing; there is no separate model call. The split is:

• **Deterministic ("what is true"):** what changed, which type/area boxes to tick, which refs actually

appear, whether a secret leaked. Gathered from `git`/`gh` — never guessed.

• **Voice (you):** the Summary, the Changes bullets, the verification narrative — prose grounded *only*

in the deterministic facts.

**Never invent.** A reference, statistic, ticket id, or sign-off that is not in the diff/commits does not go in the PR. Under-filling a box is recoverable; a fabricated claim is not. When a fact has no evidence, write `n/a`.

Arguments & modes

• `$1` (optional) — target branch. Defaults to the remote's default branch, resolved below.
• `DRY_RUN=1` (env) — emit the body to `out/pr-body.md` and print the `gh` command instead of touching

GitHub. Also the automatic fallback when `gh` is missing/unauthenticated. This is how you **test** the skill without spamming real PRs.

---

Step 0 — Preconditions (deterministic)

CURRENT=$(git rev-parse --abbrev-ref HEAD)

# Target: the argument, else the remote's default branch, else main.
DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
[ -n "$DEFAULT" ] || DEFAULT=main
TARGET_BRANCH="${1:-$DEFAULT}"

[ "$CURRENT" = "$TARGET_BRANCH" ] && {
  echo "On $CURRENT, which is the target — there is nothing here to promote."; exit 1; }

# Resolve the COMPARISON ref. Prefer the remote-tracking branch — see below for why.
# A repo with no remote is purely local, so the local branch is the only truth available.
if git remote get-url origin >/dev/null 2>&1; then
  git fetch origin --quiet
  TARGET="origin/$TARGET_BRANCH"
else
  TARGET="$TARGET_BRANCH"
fi

# The target must exist.
git rev-parse --verify --quiet "$TARGET" >/dev/null || {
  echo "No '$TARGET' here — branches: $(git branch -a --format='%(refname:short)' | tr '\n' ' ')"
  echo "Create it, or pass the intended target as the argument."
  exit 1
}

**Compare against `origin/<target>`, never the local branch.** Nothing advances a local target branch you never check out — `git pull` on the working branch moves the remote-tracking ref `origin/<target>` and leaves the local branch wherever it was last checked out. Diffing against it produces a PR body describing commits that are already on the target, and the mistake is invisible because the numbers look plausible. Local default-branch refs are routinely dozens of commits behind their remotes while the deployed branch is perfectly current. The same trap in the other direction is the deploy-consequence rule: **a git ref is not a deployment** — `origin/<target>` is what a connected host builds from; the local branch is a bookmark this clone happens to hold.

# Inputs (three-dot: changes on HEAD since it diverged from TARGET).
git diff --stat "$TARGET...HEAD"
git diff --name-only "$TARGET...HEAD"
git log "$TARGET..HEAD" --format='%s%n%b