github-pr-manager

name	github-pr-manager
description	Create, view, and merge GitHub pull requests with validation. Use when creating PRs from branches, checking PR status, or merging approved PRs with cleanup.
allowed-tools	["Bash(git branch:*)","Bash(git push:*)","Bash(gh pr:*)","Bash(gh auth status)","Bash(gh auth login)"]

GitHub PR Manager

Instructions

When to Invoke This Skill

• Creating a pull request after implementing changes
• Checking status of an existing PR (mergeable, checks, reviews)
• Merging an approved PR
• Validating PR state before operations

Capabilities

1. Create Pull Request

   • Generate PR from current branch
   • Create descriptive title and body
   • Link to related issues
   • Add appropriate labels

2. View PR Status

   • Check if PR is open/closed/merged
   • Verify mergeable state
   • Review CI check status
   • Check review approvals

3. Merge Pull Request

   • Squash merge with single commit
   • Validate before merging
   • Branch cleanup handled externally

Standard Workflows

Creating a PR

1. Verify Current Branch

   git branch --show-current
   

   Ensure you're on a feature branch, not main/master

2. Push Branch (if not already pushed)

   git push -u origin HEAD
   

3. Create PR

   gh pr create --title "<type>: <description>" --body "$(cat <<'EOF'
   ## Summary
   Resolves #<issue_number>
   
   <Brief description of changes>
   
   ## Changes Made
   - <List key changes>
   
   ## Testing
   - <How to test these changes>
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"
   

Checking PR Status

1. Fetch PR Information

   gh pr view <pr_number> --json state,mergeable,statusCheckRollup,reviewDecision
   

2. Interpret Results

   • state: "OPEN", "CLOSED", "MERGED"
   • mergeable: "MERGEABLE", "CONFLICTING", "UNKNOWN"
   • reviewDecision: "APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"

Merging a PR

1. Validate PR State

   gh pr view <pr_number> --json headRefName,state,mergeable
   

   • Verify state is "OPEN"
   • Verify mergeable is "MERGEABLE"
   • Extract branch name for cleanup

2. Perform Squash Merge

   gh pr merge <pr_number> --squash
   

   This will:

   • Squash all commits into one
   • Merge to main/master

   Important: Do NOT use --delete-branch flag and do NOT switch back to main. Branch cleanup and worktree disposal are handled by the orchestrator after the PR is merged.

Error Handling

Authentication Issues:

• Run: gh auth status
• If not authenticated: gh auth login

PR Not Mergeable:

• Check for conflicts: Inform user to resolve merge conflicts
• Check for failing CI: Wait for checks to pass
• Check for required reviews: Request reviews from team

Worktree Environment:

• Workers operate in isolated git worktrees
• Do NOT attempt to delete branches or switch to main after merging
• Worktree cleanup is handled by the orchestrator after PR merge
• Focus only on the merge operation itself

PR Title and Body Standards

Title Format:

<type>: <brief description>

Types: feat, fix, chore, docs, refactor, test, perf

Body Format:

## Summary
Resolves #<issue>

<1-2 sentence description>

## Changes Made
- <Bullet list of key changes>

## Testing
- <How changes were tested>
- <Manual test steps if needed>

## Screenshots (if UI changes)
<Optional screenshots>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Examples

Example 1: Create PR from feature branch

User: "Create a PR for this feature"
Action:
1. Verify on feature branch
2. Push if needed
3. Create PR with structured body linking to issue
Output: PR URL and number

Example 2: Check PR status before merging

User: "Is PR #123 ready to merge?"
Action:
1. Fetch PR status
2. Check mergeable state, CI status, reviews
Output: "PR #123 is ready to merge" or list blockers

Example 3: Merge approved PR

User: "Merge PR #123"
Action:
1. Validate PR state (gh pr view 123 --json headRefName,state,mergeable)
2. Squash merge (gh pr merge 123 --squash)
Output: "PR #123 merged successfully. Worktree cleanup will be handled by orchestrator."