GitHub Pull Request Best Practices

This Skill provides comprehensive guidance for creating high-quality pull requests following industry best practices and conventional commit standards.

Capabilities

• •Generate conventional commit formatted PR titles
• •Structure PR descriptions with proper sections
• •Support multiple languages (English/Japanese)
• •Follow GitHub PR template conventions
• •Avoid common PR mistakes

When to Use

Use this Skill when you need to:

• •Create a new pull request
• •Write PR titles and descriptions
• •Format commit messages
• •Follow conventional commit standards
• •Generate PR content in English or Japanese

PR Title Format

Conventional Commits Standard

PR titles must follow Conventional Commits format:

<type>(<scope>): <description>

Important: NO emojis in PR titles or descriptions.

Common Types

• •feat: New feature
• •fix: Bug fix
• •docs: Documentation changes
• •style: Code style changes (formatting, no logic change)
• •refactor: Code refactoring
• •test: Adding or updating tests
• •chore: Maintenance tasks, dependencies

Scope (Optional but Recommended)

The scope should indicate what part of the codebase is affected:

• •Module name: feat(auth): add OAuth2 support
• •Component name: fix(button): resolve click handler issue
• •Area of code: docs(api): update endpoint documentation

Description

• •Use imperative mood ("add" not "added" or "adds")
• •No capitalization of first letter
• •No period at the end
• •Clear and concise (under 50 characters when possible)

Examples

Good:

feat(auth): add OAuth2 authentication
fix(api): resolve timeout on large requests
docs(readme): update installation instructions
refactor(database): optimize query performance
test(auth): add integration tests for login flow
chore(deps): update dependencies to latest versions

Bad:

✨ Add new feature  (has emoji)
Fixed bug  (not following format, wrong tense)
Update.  (vague, has period)
FEAT: NEW STUFF  (all caps, vague)

PR Description Structure

Standard Template

## Summary
- Brief description of changes (1-3 bullet points)
- Focus on what and why, not how
- Keep each point concise

## Test plan
- [ ] Test case 1
- [ ] Test case 2
- [ ] Verified no regressions

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

Key Principles

1. •

   Summary Section

   • •1-3 bullet points maximum
   • •Explain what changed and why
   • •Avoid implementation details (those are in the code)
   • •Use present tense
2. •

   Test Plan Section

   • •Use checkbox format (- [ ])
   • •List specific test scenarios
   • •Include regression testing
   • •Be specific and actionable
3. •

   Signature

   • •Always include the Claude Code signature
   • •Placed at the bottom

Detailed Explanation (When Needed)

For complex PRs, add additional sections before the signature:

## Summary
- Main changes

## Background
Context or motivation for changes

## Implementation Details
High-level overview of approach

## Test plan
- [ ] Tests

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

Multi-Language Support

English (Default)

Use English when no language is specified or when language is en:

## Summary
- Add user authentication with OAuth2
- Implement token refresh mechanism
- Add comprehensive error handling

## Test plan
- [ ] Test OAuth2 login flow
- [ ] Test token refresh
- [ ] Test error scenarios

Japanese

Use Japanese when language is ja:

## 概要
- OAuth2によるユーザー認証を追加
- トークンリフレッシュ機能を実装
- 包括的なエラーハンドリングを追加

## テスト計画
- [ ] OAuth2ログインフローのテスト
- [ ] トークンリフレッシュのテスト
- [ ] エラーシナリオのテスト

Language Selection Guidelines

• •Default to English if no language specified
• •Use the language specified by the caller
• •Be consistent throughout the entire PR
• •Don't mix languages within a single PR

PR Template Integration

Using Project Templates

If the project has a PR template at .github/pull_request_template.md:

1. •Read the template file
2. •Follow its structure exactly
3. •Don't modify section headers
4. •Don't add custom sections
5. •Fill in all required sections (use "N/A" if not applicable)

Template Best Practices

• •Preserve section headers: Keep them exactly as in template
• •Complete all sections: Even if marking as "N/A"
• •Follow order: Maintain the template's section order
• •Don't improvise: Stick to template structure

GitHub CLI Best Practices

Creating PRs with gh

Basic command structure:

gh pr create --draft --title "feat(scope): description" --body "$(cat <<'EOF'
## Summary
- Changes

## Test plan
- [ ] Tests

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

Important notes:

1. •Use HEREDOC format for multi-line descriptions
2. •Start with --draft flag for work in progress
3. •Use cat <<'EOF' (with quotes) to prevent variable expansion
4. •gh pr create automatically pushes the branch (no manual push needed)

Draft vs Ready

Start as draft when:

• •Work is still in progress
• •Tests are not complete
• •Need early feedback

Convert to ready when:

gh pr ready <PR-NUMBER>

Common Mistakes to Avoid

1. •

   Manual Push Before PR Creation

   • •❌ git push -u origin branch && gh pr create
   • •✅ gh pr create (handles push automatically)
2. •

   Including Emojis

   • •❌ ✨ feat: add new feature
   • •✅ feat: add new feature
3. •

   Incorrect Conventional Commit Format

   • •❌ Add new feature
   • •✅ feat: add new feature
4. •

   Vague Descriptions

   • •❌ ## Summary\n- Updated stuff
   • •✅ ## Summary\n- Add OAuth2 authentication support
5. •

   Ignoring Language Argument

   • •❌ Always using English
   • •✅ Using specified language (en/ja)
6. •

   Modifying Template Structure

   • •❌ Adding custom sections to template
   • •✅ Following template structure exactly

Analyzing Commits for PR

Use All Commits, Not Just Latest

When creating a PR, analyze ALL commits from the merge base:

# Get merge base
MERGE_BASE=$(git merge-base origin/main HEAD)

# Get ALL commits from merge base
git log $MERGE_BASE..HEAD

Why this matters:

• •PR should represent all work on the branch
• •Latest commit might not capture full scope
• •Users expect PR to reflect entire branch

Extracting PR Content from Commits

# Get commit messages for summary
git log --format="- %s" $MERGE_BASE..HEAD

# Get changed files for context
git diff --name-only $MERGE_BASE..HEAD

# Get commit count
git log --oneline $MERGE_BASE..HEAD | wc -l

Quality Checklist

Before creating a PR, verify:

• • Title follows conventional commit format
• • No emojis in title or description
• • Summary is clear and concise (1-3 points)
• • Test plan is specific and actionable
• • Language matches specified preference
• • Template structure is followed (if exists)
• • All commits are analyzed (not just latest)
• • Claude Code signature is included

Related Skills

• •git-analysis: Use to gather commit and branch information
• •Project-specific templates: Check .github/pull_request_template.md

Additional Resources

See REFERENCE.md for:

• •Detailed conventional commits specification
• •Language-specific examples
• •Advanced PR patterns
• •GitHub CLI command reference