Create PR Skill

This skill creates well-structured GitHub pull requests with meaningful descriptions.

Prerequisites

• gh CLI installed: Verify with gh --version
• Authenticated: Run gh auth status to check
• Pushed branch: Current branch must be pushed to remote
• Clean commits: All commits should follow conventional commits format

PR Scope

• MUST: Review ALL commits in the branch since divergence from base
• MUST: Understand the complete scope of changes, not just the latest commit
• NEVER: Create PR based only on the most recent commit
• NEVER: Create PR without understanding the full context

PR Title Format

Follow the Conventional Commits format (same as commit messages):

<type>[optional scope]: <subject>

Guidelines

• Use the dominant type from commits in the branch
• Keep it concise and descriptive (maximum 72 characters)
• If multiple features, use the main feature or use feat with broader scope
• Examples:
  • feat(auth): add OAuth2 authentication flow
  • fix(api): resolve race condition in user updates
  • refactor(db): migrate to connection pooling

PR Description Format

Check for PR Template First

Before creating the PR description, check if a PR template exists:

# Common locations for PR templates
.github/PULL_REQUEST_TEMPLATE.md
.github/pull_request_template.md
.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
docs/PULL_REQUEST_TEMPLATE.md

If template exists: Follow the template structure and fill in all sections If no template: Use the default format below

Default Format (when no template exists)

## Summary

Brief overview of what this PR does (2-4 bullet points)

## Why

Explain the motivation and context for this change:
- What problem does this solve?
- Why is this change necessary?
- What is the business value or technical benefit?

## Changes

- List major changes or components affected
- Group related changes together
- Mention any breaking changes

## Test Plan

- [ ] Describe how to test the changes
- [ ] List manual testing steps if applicable
- [ ] Mention automated tests added/updated

## Notes

[Optional section for additional context]
- Any caveats or known limitations
- Follow-up work needed
- Performance impact (if relevant)
- Migration steps (if applicable)

Workflow

1. Check for PR template

   • Look for PR template in common locations
   • Read and understand the template structure if it exists

2. Analyze branch history

   • Run git log <base-branch>...HEAD to see all commits
   • Run git diff <base-branch>...HEAD to understand full changes
   • Review commit messages to understand the scope

3. Verify branch state

   • Check if branch is pushed: git status
   • Push if needed: git push -u origin <branch-name>

4. Draft PR content

   • Create title based on the dominant change type
   • Write description following template (if exists) or default format
   • Ensure all sections are filled appropriately

5. Create PR

   • Use gh pr create --title "..." --body "..."
   • Add reviewers if configured
   • Set base branch if not default

6. Verify PR

   • Return the PR URL for user review
   • Check that description is clear and complete

Examples

Good PR with Default Format

Title: feat(auth): add JWT token refresh mechanism

Description:

## Summary

- Implements automatic JWT token refresh before expiration
- Reduces authentication errors and improves user experience
- Adds background refresh logic with configurable timing

## Why

Users were experiencing frequent authentication errors when tokens expired
during active sessions. This implementation proactively refreshes tokens
before expiration, eliminating interruptions and improving UX.

## Changes

- Add `TokenRefreshService` for managing token lifecycle
- Update authentication middleware to handle token refresh
- Add configuration options for refresh timing
- Include comprehensive error handling and logging

## Test Plan

- [ ] Verify token refresh works before expiration
- [ ] Test error handling when refresh fails
- [ ] Confirm existing authentication flows still work
- [ ] Run integration tests for auth endpoints

## Notes

Performance impact: Minimal, refresh happens in background.

Bad PR Examples ❌

# Too vague
fix: bug fixes

# Not descriptive
Update code

# Multiple unrelated changes
feat: add login, fix user profile, update tests, refactor API

# Missing Why section
Just implements the feature without explaining motivation

PR Guidelines (from CLAUDE.md)

• Focus on high-level problem and solution
• Never mention tools used (no "Generated by Claude Code", no co-authored-by)
• Add specific reviewers as configured in repository settings
• Include performance impact if relevant to the changes
• Keep descriptions clear and concise

Notes

• PR description should be self-contained and explain the context
• Assume reviewers may not have full context of discussions
• Link to related issues if applicable: Closes #123, Relates to #456
• For large PRs, consider breaking into smaller, focused PRs
• Each PR should ideally address one logical feature or fix
• Always respect project-specific PR templates when they exist