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'