| name | create-pr |
| description | Create a pull request for the current changes. Use when asked to "make a PR", "open a pull request", "push and PR", or otherwise publish in-progress work for review. Ensures changes are on a non-`main` branch, commits are made and pushed, and the PR targets `upstream/main` when an `upstream` remote exists, otherwise `origin/main`. |
| license | MIT |
| compatibility | Requires git; remote creation uses an available GitHub integration or authenticated gh, with a browser fallback. |
| metadata | {"portability":"portable","applicability":"git-github","binding":"optional-overlay","risk":"remote-write","maturity":"canary","requires":"none","related":"pre-pr-self-review, address-pr-feedback"} |
Create a pull request
If overlay.md exists beside this file, read it before acting; it contains
repository-specific bindings. This core remains usable without it.
Follow these steps in order. Stop and ask the user if any check is ambiguous;
do not force-push, rewrite history, or delete branches without explicit
confirmation.
Approval scope. A request to "open / make / create a PR" authorizes the
work of preparing one. It does not authorize the commit or the push.
The Approval checkpoint inside step 3 (Commit changes) is the gate:
staging happens before it, git commit and everything after happen only
once the user supplies an explicit publishing verb - commit, push,
ship it, or equivalent. See your repo's agent guidance (the "Working with
the user on changes" rules in AGENTS.md) for the canonical rule and the
recurring not-approval phrasings.
Before running this workflow, walk through the pre-pr-self-review checklist -
it catches the test, allocation, overflow-arithmetic, and TFM-phrasing mistakes
that repeatedly cost a review round-trip. If the change polyfills a .NET API for
.NET Framework, a polyfill-dotnet-api skill (where the repo provides one)
defines the design rules the self-review then validates against.
1. Inspect repository state
Run these (read-only) checks first:
git remote -v - determine whether an upstream remote exists.git rev-parse --abbrev-ref HEAD - current branch name.git status --porcelain - uncommitted changes.git log --oneline @{u}.. 2>$null (if upstream is set) - unpushed commits.
Decide the PR base:
- If a remote literally named
upstream exists, the PR base is
upstream/main (i.e. --repo points at the upstream repo, base branch
main).
- Otherwise the PR base is
origin/main (the fork itself, base main).
2. Ensure work is on a feature branch
- If the current branch is
main, do not commit on main. Create a new
branch from the current HEAD with a short, descriptive, kebab-case name
derived from the change (e.g. fix-span-enumerate-lines,
add-create-pr-skill).
- Confirm the branch name with an available structured-question capability
before creating it. Offer the suggested kebab-case name and a way to enter a
different name. If the host has no structured question tool, ask in chat.
Known client adapters are in host-adapters.md.
- Use
git switch -c <branch> to move uncommitted changes onto the new
branch.
- If already on a non-
main branch, keep using it.
3. Commit changes
- If
git status shows uncommitted changes that belong in the PR, stage them
with git add (prefer explicit paths over git add -A unless the user
asked for everything).
- Write a concise commit message: short imperative subject (≤ 72 chars), and
a body only if the change needs explanation. Match the style of recent
commits (
git log --oneline -20).
- Do not amend or rebase published commits without explicit user approval.
- Do not pass
--no-verify; let hooks run.
Approval checkpoint
Stop here. Show the user the staged diff (or summarize it) and the
proposed commit message. Wait for the user to explicitly say commit,
push, or ship it (or one of the other verbs listed in your repo's
agent guidance "Working with the user on changes" rules) before running
git commit. If the user already used one of those verbs in the message
that triggered this skill, proceed without asking again. Do not infer
approval from the original "open a PR" request.
4. Push the branch
Pre-push conflict check
Before pushing (or re-pushing), confirm the branch still merges cleanly into
its base (<base> = origin/main, or upstream/main when that remote exists)
so conflicts surface locally instead of on the PR:
-
git fetch <remote> main, then git rev-list --left-right --count <base>...HEAD.
Left count 0 means up to date - skip to push.
-
If behind, dry-run the merge without touching the tree:
git merge-tree $(git merge-base HEAD <base>) HEAD <base> | Select-String 'CONFLICT|<<<<<<<'
-
Clean: prefer rebasing onto <base> so the PR diff is current.
-
Conflicts: rebase (git rebase <base>, $env:GIT_EDITOR='true'), resolve,
git add by path, git rebase --continue, then re-run the build and the
test suite in Release (base may have moved/renamed code you depend on).
-
A rebase rewrites commits, so the next push needs --force-with-lease - a
force-push that requires explicit user approval per the publish-boundary rule.
Push
- Fresh branch (no rebase):
git push -u origin <branch>.
- After rebasing an already-pushed branch (explicit approval only):
git push --force-with-lease origin <branch>.
- Never
git push --force or --force-with-lease without explicit user
confirmation.
5. Open the PR
Prefer an available GitHub integration that can create a pull request and
return its number/URL. Fall back to the GitHub CLI (gh) when no integration is
available, and only fall back to a browser compare URL if neither is available.
Known client adapters are in host-adapters.md.
Determine the target with the rule from step 1.
Option A - GitHub integration (preferred)
Call the host's pull-request creation capability with:
title, body (see PR title/body guidance below),head = the feature branch name (no owner prefix),base = main,- For an upstream-targeted PR, set
repo to { owner: <upstreamOwner>, name: <repo> } and headOwner to the fork owner.
- For an origin-only PR, omit
repo and headOwner (they default correctly).
Option B - GitHub CLI fallback
PR title and body
- Title: same style as the commit subject; reference the area touched.
- Body: brief summary of what changed and why, bullet list of notable
changes, and any test/validation notes (e.g. "ran the test suite"). Link
related issues with
Fixes #N when appropriate.
- If the user has not supplied a title/body, propose one and confirm before
creating.
Option C - Browser fallback
If neither the VS Code tool nor gh is available, print the compare URL:
- Upstream:
https://github.com/<upstreamOwner>/<repo>/compare/main...<forkOwner>:<branch>?expand=1
- Origin only:
https://github.com/<originOwner>/<repo>/compare/main...<branch>?expand=1
6. Report back
Tell the user:
- The branch name and where it was pushed.
- The base the PR targets (
upstream/main or origin/main).
- The PR URL (from
gh pr create output) or the compare URL fallback.
7. Watch for an automated reviewer
Some repos auto-review PRs (e.g. GitHub Copilot), posting a review a minute or
two after the PR opens or after each push; others let you request one.
- Tell the user a review may land shortly; offer to fetch and investigate it
when it does. Don't poll - act when the user reports comments, or check once.
- If nothing auto-reviews, offer to request a reviewer - a remote action, only
with the user's go-ahead.
Opening the PR ends this skill. Handling whatever the reviewer posts - resolving
threads, re-requesting review - is the address-pr-feedback workflow, under the
same commit/push publish gate.
Guardrails
- Never commit directly to
main, even if the user is currently on it -
always branch first.
- Never delete branches, force-push, or rewrite history as part of this
workflow.
- If the working tree has unrelated changes, ask the user which files belong
in the PR before staging.
Host adapters
- host-adapters.md - exact structured-question and GitHub
integration names for tested clients, plus the host-neutral fallbacks.
