/create

name: pull-request:create
description: |
  Create a pull request, merge request, or change request with proper formatting and content guidelines.
  Invoke when the user wants to create, open, or submit a PR, MR, or CR, including after committing changes.

argument-hint: "[--draft] [--auto] [--watch] [--base <ref>] [--label <name>] [--dry-run]"
allowed-tools:
  - mcp__github
  - Agent
  - Skill(pull-request:babysit)
  - Skill(pull-request:follow-up)
  - Skill(github:stack)
  - "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

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/contributing.ts`

Title

• Check the log in the context above to determine the repo's commit style:
• **subject** (default): `${subject}: ${summary}` (e.g., `api: add timeout to request`)
• **conventional**: `${type}: ${summary}` (e.g., `fix: add timeout to request`)
• Keep under 50 characters, max 100
• Use imperative mood, lowercase except proper nouns

Body

Lead with intent: why this change, the decisions a reviewer can't reconstruct from the diff, and how you know it works. Don't restate what the diff, git, or the status checks already carry. Mine the session for the substance that never reached the code (rejected alternatives, overturned theories, what you observed testing, scope added or dropped) and state each as a self-contained decision, not as a delta against a plan the reviewer never saw.

• Open with a bare verb ("Adds", "Fixes", "Removes") when the change is self-evident, or with the problem when it needs justifying. Don't restate the title.
• Default to prose. A small PR is a tight paragraph with no headers. Add `##` sections only when length earns them. Length tracks substance, not diff size.
• Reference the motivating issue at the end of the opening (`Closes #N`, `Fixes #N`, or bare `#N` if not closing). Wrap code identifiers in backticks, but leave bare anything the platform auto-links: commit SHAs and issue/MR refs (`#N`, `!N`, `owner/repo#N`). Backticks kill the link.

Before drafting anything past a one-paragraph body, load [`sections.md`](sections.md): the substance catalog by change type, audience tiers, density and heading rules, evidence grounding, and slop to cut. Load the `writing` skill for the full set of tropes to avoid.

Outline First

For a large change (several concepts or many files) or any open-source PR, settle the structure before writing prose: draft the section headings with one-line bullets naming what belongs under each, show the outline to the user, and stop for their sign-off before expanding it. A small personal change skips this and gets written in one pass.

Template

When the context above shows a detected PR template, follow its structure instead of the default body format. Load [`template.md`](template.md) for how to preserve sections and map skill-generated content into them. With no template detected, use the default Body format above.

Issue Handling

Reference a motivating issue in the PR body only (`Closes #123`). Never modify the issue itself: no comments, labels, milestones, or assignees.

Reviewers

Corporate and internal repos only. On OSS (a public repo you don't own) the maintainer triages, so skip this and add no noise. Suggest reviewers, never assign; the user always chooses. Load [`reviewers.md`](reviewers.md) for the visibility gate, the ranking script, and username resolution.

Arguments

Parse `$ARGUMENTS` for these flags. With none, create a normal PR/MR that is ready for review and does not auto-merge.

• `--draft`: open the PR/MR as a draft. Default: ready for review.
• `--auto`: after creating, enable auto-merge so it merges once checks pass and required approvals land. Default: off.
• `--watch`: after creating, spawn `pull-request:babysit` to actively shepherd the PR/MR (fix trivial red CI, drive the merge). When a bot review should gate the merge (asked to wait for a reviewer, or a review bot is configured on the repo), add `--reviews` so babysit hands the wait to `follow-up --auto`; a needless `--reviews` costs only one no-op hand-off. Distinct from `--auto`, which only flips on the platform's passive auto-merge. Default: off.
• `--base <ref>`: parent branch for a stack layer. See [Stacking](#stacking). Default: the repo's default branch.
• `--label <name>`: apply a label, repeatable. Where a repo gates its hosted review bot on a label, this is how a review gets requested (see follow-up's `reviewers.md`). Confirm the label exists before creating, because a review bot evaluates the PR when it opens and an unknown label fails the create outright (see [Labels](#labels)). Default: none.
• `--dry-run` (alias `--body-only`): produce the body without creating anything. See [Dry Run](#dry-run). Default: off.

Dry Run

Determine the title and body from the context above as usual, write the body to `tmp/pr-body-<branch>.md`, then print the title and body to the user and stop. Do not stage, commit, push, or run `gh pr create` / `glab mr create`. Use this to preview or evaluate the body in isolation.

Workflow

If `--dry-run` (or `--body-only`) is set, follow [Dry Run](#dry-run) instead of the steps below.

1. **Branch validation**: If the context above shows you're on a default branch (main/master), stop and ask the user to switch to a feature branch first. 1. Stage changes if not already staged: `git add .` 1. Commit if there are no commits yet on the branch. Follow the same format for the commit message as for the pull request title (conventional or subject-oriented based on repo standard): `git commit -m "..."`