Open / update a pull request

This folder is the whole skill — enough to open a PR in any repo. Do not require the repo's AGENTS.md to operate. If you already know repo extras (ticket-as-scope, extra body sections, branch pattern, a PR template), apply them on top of this skill — never instead of Why and Benefits.

Read references/description.md before writing title or body.

Drive GitHub through the local authenticated gh CLI. Prefix gh with GH_PAGER=cat. Never merge. Never force-push unless the user asked. Always end the reply with the PR URL on its own last line.

When to open (and when not to)

Only run this skill when the user asked to open, create, update, or refresh a PR.

Situation	Action
User did not ask to open or update a PR	Do nothing. Do not create "while you're here".
Default branch, clean tree, no unique commits	Stop. Do not open an empty PR.
Default branch, has work to ship	Always create a new branch first (step 1). Never commit or push on the default branch.
Feature branch, unique commits, no PR for this head	Push (if needed) and create one PR (step 3).
Feature branch, a PR already exists for this head	Update that PR (step 4). Never gh pr create.
gh pr view / list shows a PR whose headRefName ≠ current branch	Stop. Do not edit the wrong PR.
Work is unfinished / user said WIP	Open or convert to draft. Title may use a [WIP] prefix.
Diff contains secrets, credentials, or .env files	Stop and tell the user. Do not open.
Two unrelated problems on the same branch	Flag the mixed scope. Do not silently describe them as one change. Do not split the branch unless asked.

One head → one PR. Updating means rewriting title and body for the whole branch, not appending "also…".

0. Context (always, in parallel)

git status -sb
git branch --show-current
git log --oneline -8
git diff && git diff --cached
git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || true
GH_PAGER=cat gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
command -v gh && GH_PAGER=cat gh auth status

Default branch: the gh value, else main, else master.

If gh is missing or unauthenticated: still author title + body to a temp file, then give the user the exact git push and gh pr create --body-file commands. Do not invent a web-API fallback.

Decide:

• type: feat | fix | docs | chore | refactor | perf | test | build | ci (or another Conventional Commits type that fits). Use ! for a breaking change.
• scope: a ticket id if the user, branch, or commits have one (ABC-123); otherwise the area the diff belongs to. Omit (scope) when none is honest.
• summary: short imperative phrase (the what, not the why).

Title, under 72 characters:

<type>(<scope>): <imperative summary>

If the branch already has a conventional subject that still describes the whole branch, reuse it. Do not title the PR after the last commit alone.

1. Branch

On the default branch

Create a new branch before any commit, push, or gh pr:

git checkout -b <type>/<scope>-<slug>

If the repo documents a branch pattern, use that instead. <slug> is 2–4 lowercase words from the change. Uncommitted work comes along.

If the work is not yet committed and the user asked for a PR, commit it on the new branch (conventional subject; body = why). Commit only files that belong to this change; ask if the dirty tree is mixed.

Already on a feature branch

Stay on it. Do not fork another branch. Do not create a second PR.

2. Existing PR?

GH_PAGER=cat gh pr list --head "$(git branch --show-current)" --json number,title,url,body,headRefName

• Empty → create (step 3).
• One row, headRefName matches current branch → update (step 4).
• Anything else → stop.

3. Create (no PR yet)

git push -u origin HEAD

Draft the body from references/description.md. Write it to a temp markdown file (avoids shell escaping). If .github/PULL_REQUEST_TEMPLATE* (or docs/pull_request_template.md) exists, fill that structure and still include Why and Benefits.

GH_PAGER=cat gh pr create --base "<default-branch>" --head "$(git branch --show-current)" \
  --title "<type>(<scope>): <imperative summary>" \
  --body-file <tmp.md>

Add --draft when the work is unfinished. Delete the temp file after. If a hook or CI gate blocks create, fix the reported failure and retry. Do not skip hooks.

4. Update (PR already exists)

Re-read git log <default-branch>...HEAD and the full diff since the branch diverged — not just the latest commit. If the branch has unpushed commits, git push first (no --force unless asked). Rewrite title and body so they describe the branch as it is now.

GH_PAGER=cat gh pr edit <number> --title "<conventional title>" --body-file <tmp.md>

Only pass --title when the current title is wrong. Do not append "also updated…". Replace the description.

5. Report

Say whether the PR was created or updated, plus one line on what changed. Wait for review. Do not merge, do not request reviewers, do not comment, unless the user asked.

Always end the reply with the PR URL on its own last line. No extra sentence after it.

GH_PAGER=cat gh pr view --json url --jq '.url'