PR Creator

Create well-structured, reviewer-friendly pull requests following best practices.

CRITICAL: This skill MUST always result in a PR being created. Do NOT stop early, do NOT ask the user to run another command first. Handle all prerequisites (committing, branching, pushing) inline and proceed to gh pr create.

Workflow

Step 1: Pre-flight Checks

Run these checks before anything else:

1. Verify GitHub CLI authentication — run gh api user --jq '.login' to confirm the CLI is authenticated. If this fails, tell the user to run gh auth login first and stop.
2. Determine the base branch — default to main. If the user specifies a different base, use that. Capture as $BASE_BRANCH.

Step 2: Commit Uncommitted Changes

Run git status to check for uncommitted changes. If there are uncommitted changes, commit them directly — do NOT delegate to another skill or tell the user to commit first.

1. Stage changes — run git add <files> for relevant modified/untracked files. Do not stage .env or gitignored files.
2. Lint and format — if Python files are staged, run:

   ruff check --fix <files> && ruff format <files>

   Re-stage any modified files.
3. Commit — write a conventional commit message based on the staged diff:

   git commit -m "<type>: <description>"

   If precommit hooks modify files, re-stage with git add -u and retry (up to 3 times).

Step 3: Ensure Feature Branch

1. Check current branch — run git branch --show-current.
2. If on $BASE_BRANCH, create a feature branch:
   • Analyze the commits/changes to pick a descriptive name (e.g., feat/add-auth, fix/login-bug)
   • Run git checkout -b <branch-name>
3. If on a different branch, check whether the branch has PR-worthy commits vs $BASE_BRANCH:
   • Run git log $BASE_BRANCH..HEAD --oneline
   • If there are commits, use the current branch as-is
   • If there are NO commits (branch is at same point as base), this means something went wrong — investigate and fix

Step 4: Sync with Base Branch

1. Fetch latest — run git fetch origin $BASE_BRANCH
2. Check for divergence — run git log HEAD..origin/$BASE_BRANCH --oneline
3. Rebase if needed — if the base branch has new commits: a. Run git rebase origin/$BASE_BRANCH b. If conflicts arise, surface them to the user — show both sides and ask which to keep. Do not silently resolve. c. After resolving, git add <file> and git rebase --continue

Step 5: Push

Push the branch to remote:

git push -u origin HEAD

If the push is rejected (e.g., diverged history after rebase), use git push --force-with-lease -u origin HEAD.

Step 6: Analyze Changes and Draft PR

1. Analyze — run these in parallel:
   • git log $BASE_BRANCH..HEAD --oneline — all commits
   • git diff $BASE_BRANCH...HEAD --stat — files changed summary
   • git diff $BASE_BRANCH...HEAD — full diff
2. Check PR size — if >500 lines changed, warn the user but continue.
3. Draft title — under 70 characters, conventional prefix (feat:, fix:, refactor:, docs:, chore:).
4. Draft body using this template:

## Summary
<1-5 bullet points explaining what changed and WHY>

## Changes
<Categorized list of what was modified — group by area/concern>

## Diagrams
<OPTIONAL — include Mermaid diagrams when visual aids clarify workflow or architecture changes>

## Test Plan
<How the changes were verified — manual testing steps, automated tests run, curl commands, etc.>

Guidelines:

• Explain why, not just what
• For WIP PRs, use the --draft flag instead of [WIP] prefix
• Include Mermaid diagrams when they clarify workflows or architecture
• Do NOT include any "Generated with Claude Code" footer or bot attribution
• Do NOT include Co-Authored-By lines

Step 7: Create the PR

Write body to a temp file and create the PR:

cat > /tmp/pr_body.md <<'EOF'
## Summary
...

## Changes
...

## Test Plan
...
EOF
gh pr create --title "the pr title" --base $BASE_BRANCH --body-file /tmp/pr_body.md

Optional flags:

• WIP/draft: add --draft
• Reviewers: add --reviewer <handle>
• Assignees: add --assignee <handle>

Do NOT add:

• --author flag (gh uses the authenticated user automatically)
• Any Co-Authored-By trailer
• Any "Generated with Claude Code" footer

Step 8: Report

• Return the PR URL so the user can review it
• If gh pr create fails, diagnose the error and retry with fixes

Best Practices

Commit History: If the commit history is messy, suggest rebasing to clean it up before creating the PR.

Feedback Requests: If the user mentions wanting specific feedback, add a "Feedback Requested" section to the body.

Screenshots: For frontend changes, remind the user to add screenshots or recordings to the PR after creation.