create-pr

name	create-pr
description	Create GitHub pull requests — picks the most token-efficient available method (gh CLI, GitHub MCP, or git push), and sources the PR body from an existing spec/plan instead of re-analyzing the diff
metadata	{"phase":"commit","input":"branch with commits pushed to remote; optionally a spec/plan path","output":"created PR URL (or a compare URL to finish in the browser)","dependencies":"git; and one of: gh CLI, a GitHub MCP server, or a GitHub remote"}

Create GitHub Pull Request

Open a pull request for the current branch, using whichever creation method is available — preferring the cheapest, most automated one.

When to trigger

Use this skill when the user:

• asks to create a new PR, open a pull request, or submit code for review
• says "create PR", "new PR", or "submit for review" after work is committed and pushed

Prerequisites

• Commits on a branch that is pushed to the remote
• The branch follows the branch convention from # WORKSPACE (default: feat-{short-description} or feat-{adw_id}-{short-description})
• At least one creation method available (see Step 1)

---

Step 1 — Choose the PR method

Detect what's available and pick the first method that works, in this order. Each later method exists only as a fallback for when the earlier one is missing.

1. gh CLI — check command -v gh and gh auth status. Preferred: cheapest and fully automated.
2. GitHub MCP — a configured GitHub MCP server exposing a create-pull-request tool. Use only if gh is unavailable. Gated — see below.
3. git push + compare URL — always available if there's a GitHub remote. Pushes the branch and gives the user a link to finish in the browser. Not fully automated.

Cost / capability comparison

Method	Token cost	Automated?	Notes
gh CLI	lowest (~1 line back: the PR URL)	✅ fully	Filters the response for you. Preferred.
GitHub MCP	highest (tool schemas loaded into context + full PR JSON returned)	✅ fully	Only cheap if the server is already loaded for other work and the response is field-filtered.
git push + compare URL	lowest raw, but incomplete	❌ user clicks the link	No API object returned; the PR isn't actually opened until the human confirms in the browser.

State which method you selected and why (e.g. "gh not found → falling back to MCP").

MCP gate — pause and ask

If the selected method is GitHub MCP, do not invoke it silently. MCP is the most token-expensive path (schema overhead plus full API-object responses). Pause, tell the user MCP is the only automated option available, and ask for confirmation before creating the PR. If they decline, fall back to git push + compare URL.

---

Step 2 — Source the PR content

Before analyzing the diff, get the PR's substance from work that already exists — reading a plan is far cheaper than re-analyzing a full diff. Use this precedence:

1. Conversation context — if this session already ran feature or implement, the spec path and a description of the work are already in context. Use them; skip the rest.
2. Spec/plan file in specs_dir — resolve specs_dir from # WORKSPACE (default: docs/specs/). Find the spec for this branch:
   • Match the branch's adw_id (from feat-{adw_id}-{name}) against the spec filename ({timestamp}-feature-{adw_id}-{name}.md).
   • If there's no adw_id, use the most recently modified spec in specs_dir.
   • Derive: title (feature name → conventional-commit format), Summary (its overview/goal), Changes (its completed phases / checked boxes), Related Issue (adw_id or issue number).
3. Fallback — only if there's no context and no spec: analyze git log and git diff.

Checked-off boxes in the spec map directly to the PR's Changes and Testing sections.

The PR body structure and a complete example live in templates/pr-body.md. If the project has its own .github/PULL_REQUEST_TEMPLATE.md, follow that instead.

---

Step 3 — Pre-flight checks

Run pre-commit checks

If the project defines a pre-commit / lint / format command in # WORKSPACE (e.g. a pre_commit_cmd key or an equivalent task runner), run it now. Skip if none.

Verify branch state

1. Not on the main/default branch — never open a PR from it:

   git branch --show-current   # should NOT be the default branch
   

2. Branch follows the naming convention — the branch rule from # WORKSPACE.
3. Consider squashing related commits for cleaner history:

   git reset --soft HEAD~N && git commit -m "feat(component): description"
   

Push the branch

git push -u origin HEAD

---

Step 4 — Create the PR

Build the title in conventional-commit format (see below) and the body from Step 2, then create the PR using the method chosen in Step 1.

PR title format

<type>(<scope>): <description>

Types: feat · fix · docs · refactor · test · chore · perf Scope is typically the component name (e.g. cli, sdk, api, models).

Examples:

• feat(cli): add support for custom output formats
• fix(api): handle timeout errors gracefully
• docs(sdk): update authentication examples

Method A — gh CLI (preferred)

gh pr create --title "<title>" --body "<body>"

Common variants:

gh pr create --draft --title "WIP: <title>"          # draft / work-in-progress
gh pr create --label "area:cli" --label "topic:security"   # labels
gh pr create --base "release-1.0"                    # target a non-default branch

Use Closes #<issue-number> in the body to auto-close the linked issue on merge.

Method B — GitHub MCP (only after the Step 1 gate)

After the user confirms, call the server's create-pull-request tool with head = current branch, base = default branch, plus the title and body. Filter the response to just the PR URL/number — do not echo the full API object.

Method C — git push + compare URL (universal fallback)

git alone cannot open a PR, but it can hand the user a link:

git push -u origin HEAD
# Then give the user the compare URL to finish in the browser:
# https://github.com/OWNER/REPO/compare/<branch>?expand=1

The push output usually already prints a "Create a pull request" link — surface it. Provide the PR's description and The PR body structure

---

After creating

gh and MCP output the PR URL and number. Display it as a markdown link so it's clickable:

Created PR [#123](https://github.com/OWNER/REPO/pull/123)

Monitor CI (optional)

If the user wants to wait for green CI before requesting review:

gh run watch                                          # latest run for the branch
# or:
RUN_ID=$(gh run list --branch "$(git branch --show-current)" --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch "$RUN_ID"

Useful gh pr create options

Option	Description
--title, -t	PR title (conventional commit format)
--body, -b	PR description
--reviewer, -r	Request review from user
--draft	Create as draft (WIP)
--label, -l	Add label (repeatable)
--base, -B	Target branch (default: repo default)
--head, -H	Source branch (default: current)
--web	Open in browser after creation