pr

name

pr

description

Create or update a GitHub Pull Request from the current branch. Reads all commits since the base branch, auto-generates a structured PR title and body (Summary / Changes / Test Plan sections), infers labels from commit types, and shows everything for approval before running gh pr create. Handles push if needed and detects existing PRs. Global and project-agnostic. Trigger when the user says "create a PR", "open a pull request", "make a PR", "$pr", "submit PR", or "push and open a PR".

GitHub Pull Request — creation skill

Creates (or updates) a GitHub PR from the current branch using gh pr create. Reads the full commit range, generates a structured body, and always shows the complete proposal for user approval before touching GitHub. Never creates a PR silently.

Accepted flags (parsed from the user's invocation text)

Flag	Effect
--draft	Open as a draft PR instead of ready for review
--base <branch>	Override the target base branch (default: repo default branch)
--reviewer @handle	Assign one or more reviewers (repeat for multiple)
--label <name>	Add a label in addition to any auto-inferred ones
--closes <N>	Append Closes #N to the PR body
--refs <N>	Append Refs #N to the PR body
--web	Open the PR in the browser after creation
--british	British English spelling in title and body (default: American English)

If the user provides a free-text hint (e.g. $pr fix the auth regression), use it as a strong signal for the title and Summary — do not ignore it.

Procedure

1. Parse flags and hint

Extract all flags above and any free-text hint from the user's invocation.

2. Gather context (run in parallel)

• git rev-parse --abbrev-ref HEAD — current branch name.
• gh repo view --json defaultBranchRef -q .defaultBranchRef.name — repo default branch.
• git log <base>...HEAD --oneline — all commits included in this PR.
• git diff <base>...HEAD --stat — files and line counts changed.
• git diff <base>...HEAD --name-only — file list for scope/label inference.
• gh pr list --head <branch> --json number,url,title — detect any existing PR for this branch.
• Check for .github/pull_request_template.md — use it as the body structure if present.

Where <base> is the --base flag value, or the repo default branch if not specified.

3. Existing PR guard

• If a PR already exists for this branch: show its number, title, and URL.
• Ask the user whether to edit the existing PR (gh pr edit) or abort.
• If editing: skip steps 4–8 and go straight to proposing updated title/body, then run gh pr edit <number> --title "..." --body "...".

4. Branch guard

• If the current branch is the same as the base branch (e.g. opening a PR from main to main): warn and ask for confirmation before proceeding.

5. Push check

• Run git rev-parse --abbrev-ref @{u} to detect whether the branch has a remote upstream.
• If no upstream: state that a push is required for GitHub to accept the PR. Ask for confirmation, then run git push -u origin <branch>.
• If upstream exists but the local branch is ahead: run git push (standard, non-force).

6. Infer labels from commit types

Map the commit types present in the range to GitHub label names:

Commit type	Suggested label
feat	enhancement
fix	bug
docs	documentation
chore / ci / build	(no label)
perf	performance
refactor	refactor
test	testing
--breaking flag or ! in any commit	breaking change

Combine with any --label flags from the user. Propose the full label list and let the user accept, change, or drop any.

7. Compose the PR title

• Single commit in range → derive title directly from that commit's subject line.
• Multiple commits → synthesize a concise subject that captures the overall change.
• Follow Conventional Commits format for the title: <type>(<scope>): <description>.
• ≤72 characters. Imperative mood, lowercase after the colon.
• Apply --british if flagged.

8. Compose the PR body

If .github/pull_request_template.md exists, fill its sections rather than using the default structure below.

Otherwise use these fixed sections:

## Summary
<bullet points: what changed and why — the motivation, not the mechanics>

## Changes
<bullet list of files/modules touched with a one-line description each>

## Test plan
<markdown checklist: concrete steps to verify the change works and hasn't broken anything>

Append at the bottom:

• Closes #N / Refs #N footers if --closes or --refs were passed.
• A provider-neutral generated-with attribution line only when the user or repo convention asks for one (standard for AI-assisted PRs; omit only if the user explicitly asks).

Draw content from the full commit range (git log) and diff stat — summarize ALL commits, not just the most recent.

9. Show the full proposal and wait for approval

Present in one block:

• Title
• Base branch → Head branch
• Draft: yes / no
• Labels: list
• Reviewers: list (or none)
• Body: full text

Ask the user to approve, edit specific sections, or cancel. Do not proceed until approved.

10. Create the PR

Build the gh pr create command from the approved proposal:

gh pr create \
  --title "<title>" \
  --body "$(cat <<'EOF'
<body>
EOF
)" \
  [--base <branch>] \
  [--draft] \
  [--reviewer <handle>] \
  [--label <name>] \
  [--web]

If label names don't exist in the repo yet, gh will error — catch this and offer to create the missing labels or skip them.

11. Report

• Print the PR URL.
• If --web was passed, confirm the browser was opened.
• If push was required (step 5), confirm the remote branch is now set.

Guardrails

• Never create or edit a PR without user approval of the full title + body proposal.
• Never force-push — only git push or git push -u origin <branch>.
• Detect existing PRs before creating; never open a duplicate silently.
• Warn before pushing if the branch has no upstream; require confirmation.
• Summarize ALL commits in the range, not just the latest one.
• Keep the title ≤72 characters.
• If gh is not authenticated or not installed, say so clearly and stop.
• Never invent file names, commit messages, or issue numbers — derive everything from actual git and gh output.
• If the repo has no default branch detectable via gh, fall back to asking the user.