PR Creator
Create well-structured draft pull requests by analyzing the diff, generating a conventional-commit title and structured description, suggesting reviewers from CODEOWNERS, and executing
— all with a confirmation step before anything is submitted.
Prerequisites
- Git repository with a remote origin
- GitHub CLI () installed and authenticated
- For GitLab: CLI; for Bitbucket: CLI (see Platform Adaptation section at the end)
Workflow
Follow these steps in order. Do not skip the preview step.
Step 1: Gather context
Run these commands to understand the current state:
bash
# Confirm repo and ownership
git config --get remote.origin.url
# Detect current branch
git rev-parse --abbrev-ref HEAD
Then ask the user: "What branch should this PR target?"
Do not assume
,
, or any default. Wait for the user's answer before proceeding.
Step 2: Analyze the diff
First, verify the current branch has been pushed to the remote:
bash
git ls-remote --heads origin <current_branch>
If the branch doesn't exist on the remote, push it first:
bash
git push -u origin <current_branch>
Then run the diff:
bash
git diff origin/<target_branch>...origin/<current_branch> | cat
If the diff exceeds roughly 1000 lines, warn the user:
"This PR touches over 1000 lines of changes. Large PRs are harder to review effectively. Would you like to proceed anyway, or would you prefer to split this into smaller PRs?"
Wait for confirmation before continuing. If the user wants to split, help them plan the split — but that's outside this skill's scope.
Step 3: Generate the PR title
Analyze the diff to determine:
-
Type — Pick the most appropriate conventional commit type based on what the diff actually does:
- — new functionality
- — bug fix
- — maintenance, dependency updates
- — documentation only
- — formatting, whitespace, no logic change
- — restructuring without behavior change
- — adding or updating tests
- — performance improvement
- — CI/CD config changes
- — build system or external dependency changes
-
Scope (optional) — If the changes clearly belong to a single module, component, or domain (e.g.,
,
,
), include it in parentheses. If the changes span multiple areas or no clear scope emerges, omit it.
-
Description — A concise lowercase summary of what changed. Wrap code identifiers, function names, file names, and technical keywords in backticks.
Examples:
feat(pricing): adjust formula to include volume discounts
fix: resolve null pointer in
- axios
refactor(auth): extract token validation into middleware
Step 4: Generate the PR description
Structure the description with these three sections:
markdown
## Summary
A 2-3 sentence high-level overview of what this PR does and why.
## Key Changes
- Specific change 1 with relevant detail
- Specific change 2 with relevant detail
- (list as many as needed to cover the meaningful changes)
## Impact
- Who or what is affected by these changes
- Any migration steps, breaking changes, or deployment considerations
- Testing notes if relevant
Write the description based on what the diff actually shows. Be specific — reference file names, functions, and behaviors rather than being vague.
Step 5: Suggest reviewers
Check if a CODEOWNERS file exists:
bash
cat .github/CODEOWNERS 2>/dev/null || cat CODEOWNERS 2>/dev/null || echo "No CODEOWNERS file found"
- If CODEOWNERS exists: Match changed file paths against CODEOWNERS patterns to identify suggested reviewers. Present them to the user and ask: "Based on CODEOWNERS, I'd suggest these reviewers: , . Would you like to add or change any?"
- If no CODEOWNERS: Ask the user directly: "Please provide at least one reviewer for this PR (GitHub usernames)."
At least one reviewer is required. Do not proceed without one.
Step 6: Detect labels
Check if the repo uses labels:
If labels exist, suggest relevant ones based on the PR type and diff content. For example:
- type → look for or label
- type → look for or label
- Breaking changes in the diff → look for label
Only suggest labels that actually exist in the repo. If no labels exist or none are relevant, skip this step silently.
Step 7: Preview and confirm
Present the complete PR to the user for review before executing anything:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 PR Preview
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title: <generated title>
Target: <target_branch>
Source: <current_branch>
Reviewers: <reviewer list>
Labels: <label list or "none">
Status: Draft
Description:
<generated description>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Ask: "Does this look good? I'll create the draft PR once you confirm. Let me know if you'd like to change anything."
If the user requests changes, apply them and show the preview again. Do not proceed until the user confirms.
Step 8: Create the PR
Once confirmed, execute:
bash
gh pr create \
--base "<target_branch>" \
--head "<current_branch>" \
--title "<title>" \
--body "<description>" \
--draft \
--reviewer "<reviewer1>,<reviewer2>" \
--label "<label1>,<label2>"
Omit
if no labels were selected. Use comma-separated usernames for
(e.g.,
). For team reviewers, use a separate
flag (e.g.,
--reviewer myorg/team-name
).
After successful creation, share the PR URL with the user.
If the command fails, show the error and help the user troubleshoot (common issues:
not authenticated, branch not pushed to remote, reviewer username doesn't exist).
Platform Adaptation
This skill defaults to GitHub CLI (
). If the remote URL indicates a different platform, mention the equivalent commands:
bash
glab mr create \
--target-branch "<target>" \
--title "<title>" \
--description "<description>" \
--draft \
--reviewer "<reviewers>"
Bitbucket: The
CLI or Bitbucket API can be used, but workflows vary. Suggest the user consult their team's tooling.
The title format, description structure, and review workflow remain the same regardless of platform.