pr-creator

name	pr-creator
version	1.0.0
description	Creates GitHub pull requests with comprehensive descriptions by analyzing git history and code changes
allowed-tools	AskUserQuestion, Bash, Glob, Grep, Read, TodoWrite
model	sonnet

Context

• Project: !git rev-parse --show-toplevel 2>/dev/null || echo "NOT_IN_GIT_REPO"
• Current branch: !git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "NO_BRANCH"
• Base branch: !git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"
• Uncommitted changes: !git status --porcelain 2>/dev/null | wc -l | xargs
• Remote status: !git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "NOT_PUSHED"
• Commits ahead: !git rev-list --count @{u}..HEAD 2>/dev/null || echo "0"

Create GitHub Pull Request

Usage: /pr-creator - Create draft PR (default) | /pr-creator open - Create regular PR

Expert software engineer creating high-quality PR descriptions that facilitate efficient code review.

Pre-flight Checks

Validate environment:

1. Check "Project" - if "NOT_IN_GIT_REPO", stop and inform user
2. Check "Current branch" - if "NO_BRANCH", stop and inform user
3. Check "Uncommitted changes" - if > 0, warn user and ask to continue

Stage 1: Analyze & Generate Draft

Step 1: Detect Mode & PR Type

Mode: Check $1 equals "open" → regular PR, else draft PR

Classify PR type via git log origin/{base}..HEAD --format="%s":

• Feature: feat:, add, implement, create, new functionality
• Fix: fix:, bug, resolve, patch
• Refactor: refactor:, restructure, clean up
• Docs: docs:, changes to *.md
• Test: test:, test file changes
• Chore: chore:, maintenance, deps, config

Step 2: Gather Information

Inspect changes:

git log origin/{base}..HEAD
git diff origin/{base}...HEAD --stat
git diff origin/{base}...HEAD
gh issue list --limit 20  # Search for related open issues

Look for: External reference IDs in commits/branch name (GitHub issues, Jira tickets, Sentry issues, PagerDuty incidents) | Related open issues via gh issue list | Breaking changes | New dependencies | Security changes (auth, validation) | Performance implications

Step 3: Generate Draft Description

Use structure from references/templates.md. Key principles:

• 6-12 lines maximum
• Three sections: Opening (1-2 sentences), Context (1-3 sentences), Implementation (2-4 bullets)
• Professional but conversational tone
• Specific technical terms, no marketing language; backtick-wrap code identifiers (env vars, functions, paths, endpoints)
• Plain bullets (-), no bold/headers in body; no hard line wraps in prose paragraphs; no   or non-breaking spaces — regular spaces only
• Issue refs at end with proper keywords; all external references as clickable markdown links (see references/templates.md)
• Never include a "Test Plan" or "Testing" section -- leave test planning to humans
• Never append Claude-Session: links or agent attribution footers

See references/templates.md for detailed structure and examples.

Step 4: Verify & Create

Check for PLAN files:

git log origin/{base}..HEAD --name-only --pretty=format: | grep -q "^PLAN" || git ls-files | grep -q "^PLAN"

If found: STOP - PLAN files are dev docs that shouldn't be in PRs. Provide remediation: Remove PLAN files and amend/rebase OR Create clean branch without PLAN files

Ensure branch pushed:

# If Remote status = "NOT_PUSHED":
git push -u origin HEAD

Create PR

Title must use conventional commit format: <type>(<optional-scope>): <imperative verb> <specific change> (50-70 chars). Use the PR type detected in Step 1. Same accuracy rules as Commit Messages in AGENTS.md.

Create (use HEREDOC for formatting):

Draft (default):

gh pr create --title "Title" --base {base} --draft --body "$(cat <<'EOF'
[Full description]
EOF
)"

Regular (open override):

gh pr create --title "Title" --base {base} --body "$(cat <<'EOF'
[Full description]
EOF
)"

Display PR URL upon success.

Critical Requirements

Accuracy: Inspect actual commits via git | Review code changes via diff | Don't rely solely on commit messages | Verify issue refs exist | Derive URLs for external references from context (never hardcode base URLs)

Structure: Follow 3-section format (opening, context, implementation) | 6-12 lines maximum | Proper issue ref formatting

Branch Management: Verify branch pushed before PR | Use git push -u origin HEAD if needed | Confirm base branch correct | Block PRs with PLAN files

Formatting: Always use HEREDOC in gh pr create --body | Ensure proper line breaks/bullets | Blank line before issue refs

PR Maintenance: This skill covers PR creation only. After pushing additional commits to an existing PR, follow the PR Maintenance rule in AGENTS.md: rewrite the description from scratch as a snapshot of what the branch changes vs. main.

Goal: Create PR descriptions making code review efficient and thorough, providing reviewers all context to understand and evaluate changes quickly.