/create

name: pull-request:create
description: |
  Create a pull request, merge request, or change request (PR, MR, CR).
  Use when the user asks to open one, including right after committing changes.

argument-hint: "[--draft] [--no-auto] [--base <ref>] [--label <name>] [--no-review] [--[no-]review-body]"
allowed-tools:
  - mcp__github
  - Agent
  - Skill(pull-request:follow-up)
  - Skill(github:stack)
  - Skill(gitlab:merge-request)
  - Skill(gitlab:api)
  - Skill(github:attach)
  - Skill(review:human)
  - "Bash(git add:*)"
  - "Bash(git commit:*)"
  - "Bash(git push:*)"
  - "Bash(git remote get-url:*)"
  - "Bash(gh pr:*)"
  - "Bash(gh stack:*)"
  - "Bash(glab mr:*)"
  - "Bash(bun ${CLAUDE_PLUGIN_ROOT}/scripts/*)"

Create Pull Request

Give the reviewer what the diff cannot: why the change exists, the decisions behind it, and how you know it works. Open the PR in the state the repo's workflow expects, so review starts without the user first fixing the title, the body, the base, or the labels.

The commit log, PR template, CONTRIBUTING notes, and review-bot config in the context below record conventions this document does not anticipate. Follow them over the defaults here.

Context

• Remote URL: !`git remote get-url origin`
• Review bot: !`bun ${CLAUDE_PLUGIN_ROOT}/scripts/detect-bot.ts`
• PR Template: !`bun ${CLAUDE_PLUGIN_ROOT}/scripts/pr-template.ts`

!`bun ${CLAUDE_PLUGIN_ROOT}/scripts/git-context.ts`

!`bun ${CLAUDE_PLUGIN_ROOT}/scripts/sem-context.ts`

!`bun ${CLAUDE_PLUGIN_ROOT}/scripts/contributing.ts`

Arguments

Parse `$ARGUMENTS` for these flags. With no flags, open a PR/MR ready for review, and set auto-merge on a repo you own.

• `--draft`: open the PR/MR as a draft. Default: ready for review.
• `--no-auto`: skip auto-merge. Default: auto-merge on a repo you own, off on a third-party repo and off under `--draft`.
• `--base <ref>`: parent branch to target. Default: the repo's default branch. A branch whose parent is another topic branch is a stack layer, identified only by this flag or by the user. The upstream ref tracks the branch's own remote copy, so it cannot identify the parent.
• `--label <name>`: apply a label, repeatable. Default: none.
• `--no-review`: skip the hosted review request. Default: on a repo that gates its hosted bot on a label, request the review when the diff clears the metered-review gate and no local pass ran.
• `--[no-]review-body`: put the drafted body in front of the user before creating. Default: on when the Remote URL above names an owner other than you, off on your own repos.

Title

Match the repo's commit style, read from the log in the context above:

• **subject** (default): `${subject}: ${summary}`, as in `api: add timeout to request`.
• **conventional**: `${type}: ${summary}`, as in `fix: add timeout to request`.

Name the primary change. If the title needs a serial comma, it is naming several changes: name the shared theme or the largest change, and put the rest in the body.

• Keep it under 50 characters. Cut scope rather than truncating words.
• Use the imperative mood.
• Lowercase every word except proper nouns.

Body

Lead with intent: why the change exists, the decisions a reviewer cannot reconstruct from the diff, and how you know it works. Leave out what the diff, the git log, and the status checks already show.

• Review the session for content that never reached the code: rejected alternatives, scope changes, test observations. State each as a decision that stands on its own, rather than as a delta from a plan the reviewer never saw.
• Use the `Entities` block in the context above to judge what the change did, and write the intent behind those entries. Never reproduce the list.
• Open with a bare verb ("Adds", "Fixes", "Removes") when the change is self-evident, or with the problem when it needs justifying. Write an opening that adds to the title rather than restating it.
• Reference the motivating issue at the end of the opening: `Closes #N`, `Fixes #N`, or a bare `#N` when the PR doesn't close it. Leave the issue itself untouched: no comments, labels, milestones, or assignees.
• Wrap code identifiers in backticks. Leave bare anything the platform auto-links: commit SHAs and issue or MR refs (`#N`, `!N`, `owner/repo#N`). Backticked refs don't auto-link.
• Default to prose. Write a small PR as one paragraph with no headings. Add `##` sections once the body carries enough substance to need them, judged by substance rather than by diff size.
• Write one line per paragraph and one line per list item. The body soft-wraps when it renders.

Load the `writing` skill and cut the tropes it lists.

Past one paragraph, load [`references/sections.md`](references/sections.md) and apply every rule in it: audience tiers, session content, density, headings, evidence, optional sections, and slop.

When the context above shows a detected PR template, follow the template's structure instead of the default body format and load [`references/template.md`](references/template.md) to map content into its sections.

Workflow

1. **Branch check**: when the context above shows the current branch is a default branch (main or master), stop and ask the user to switch to a feature branch. 1. Stage any unstaged changes: `git add .` 1. When the branch carries no commits yet, commit in the same format as the PR title. 1. **Local bot review**: the Review bot line above reports repo config, CLI presence, and any cooldown. On a config hit with no cooldown, apply the gate in follow-up's SKILL.md to decide whether the diff needs a metered review, and run `pull-request:follow-up --local` before pushing when it does. With no config, decide from the hosted signals in follow-up's `local.md`. Skip the review when a local bot pass already ran on this branch this session (`/ship` runs one), when the gate says skip, when the provider is paused, when detection finds nothing, or when the user declines. 1. Push the branch: `git push -u origin HEAD` 1. Resolve