# Pr Creation > This skill should be used when you need to create, open, or edit a pull request (PR), or the user asks to "create a PR", "open a PR", "submit a PR", "raise a PR", "file a PR", "make a PR", "create a pull request", "open a pull request", "new PR", or any variation requesting GitHub pull request creation. Use when this capability is needed. - Skill: `tomevault-io/pr-creation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/pr-creation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/pr-creation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/pr-creation --- # Pull Request Creation Best Practices ## Purpose This skill enforces three critical best practices when creating GitHub pull requests: 1. **Include ticket numbers** - Associates PRs with tracking tickets (Jira, GitHub Issues) 2. **Use PR templates when available** - Ensures consistent, complete PR descriptions 3. **Create PRs as drafts by default** - Allows review before marking ready for review ## Ticket Detection and Integration Before creating the pull request, attempt to identify an associated ticket number from Jira or GitHub Issues. ### Detection Sources Check the following sources for ticket numbers (in order of preference): 1. **Conversation context** - Ticket mentioned in recent messages or conversation history 2. **Branch name** - Parse current branch name for ticket patterns: - `PROJ-123/description` (Jira-style prefix) - `feature/PROJ-123-description` (Jira after prefix) - `123-description` (GitHub issue number) - Other common patterns using intuition 3. **Recent commit messages** - Check for ticket references in commit messages 4. **Ask user** - If no ticket found in above sources, use AskUserQuestion to ask if there's an associated ticket ### Ticket Number Patterns Recognize these common patterns: - **Jira tickets**: `PROJ-123`, `ABC-456` (uppercase letters, hyphen, numbers) - **GitHub issues**: `#123`, `456` (numbers, optionally with # prefix) ### PR Title Integration When ticket number is identified, format the PR title as: ``` [TICKET-NUM] Descriptive PR title ``` Examples: - `[MSI-608] Add Zendesk integration` - `[#456] Fix authentication bug` - `[PLATFORM-123] Refactor API endpoints` ### PR Body Integration **If PR template exists with ticket field:** - Look for placeholders like `[TICKET]`, `[ISSUE]`, `Ticket:`, `Issue:`, `JIRA:`, etc. - Replace placeholder with ticket number (as link if URL can be determined) - Preserve template formatting **If template has no specific ticket field:** - Add ticket reference at the top of the PR body - Format as: `**Ticket:** [TICKET-NUM](url)` or `**Ticket:** TICKET-NUM` if no URL **If no template:** - Include ticket reference at the start of the PR description - Format with link if available ### Ticket URL Determination Determine ticket URLs from available context and knowledge: 1. **Check CLAUDE.md or project configuration** - Look for Jira base URL, GitHub repo URL, or ticket system configuration 2. **Parse git remote** - Extract GitHub repository URL from git config for GitHub issues 3. **Use conversation context** - Apply knowledge from earlier in conversation about project's ticket systems 4. **Infer from project structure** - Look for `.jira`, project config files, or documentation mentioning ticket URLs **URL formats:** - Jira: `https://company.atlassian.net/browse/PROJ-123` - GitHub Issues: `https://github.com/owner/repo/issues/123` If URL cannot be determined, include ticket number without link. ## PR Template Discovery Before creating the pull request, check for GitHub PR templates in the `.github/` directory using the following search order: 1. `.github/pull_request_template.md` (lowercase, standard GitHub convention) 2. `.github/PULL_REQUEST_TEMPLATE.md` (uppercase variant) 3. `.github/PULL_REQUEST_TEMPLATE/*.md` (multiple templates in subdirectory) ### Template Usage If a template is found: - Read the template file to understand the required sections - Use the template structure when constructing the PR body with `gh pr create --body` - Fill in each template section appropriately based on the changes being submitted - Preserve template formatting, headings, and structure If multiple templates exist in `.github/PULL_REQUEST_TEMPLATE/`: - List available templates to the user - Ask which template to use for this PR - Proceed with the selected template If no template is found: - Proceed with standard PR creation - Generate a comprehensive PR description including: - Summary of changes - Test plan or verification steps - Any relevant context or decisions ## Draft PR Creation Always create pull requests as drafts using the `--draft` flag: ```bash gh pr create --draft --title "PR title" --body "$(cat <<'EOF' PR description here EOF )" ``` ### Why Draft by Default Draft PRs provide several benefits: - Allows CI/CD checks to run before requesting reviews - Provides opportunity to review the PR diff on GitHub before soliciting feedback - Prevents accidental notification spam to reviewers for incomplete work - Enables incremental commits and refinements before marking ready ### Making PR Ready for Review After creating the draft PR, inform the user they can mark it ready for review when appropriate: ```bash gh pr ready ``` Or they can mark it ready directly on GitHub. ## Complete Workflow Follow this sequence when the user requests PR creation: 1. **Detect ticket number**: - Check conversation context for ticket references - Parse current branch name for ticket patterns - Check recent commit messages - If no ticket found, use AskUserQuestion to ask user - Determine ticket URL if possible from context, CLAUDE.md, or git config 2. **Check for PR templates**: - Search `.github/` directory for template files - If found, read template content - Identify if template has ticket field/placeholder 3. **Gather PR information**: - Analyze recent commits using `git log` and `git diff` - Generate appropriate PR title with ticket: `[TICKET] Title` - Generate PR description: - If template with ticket field: fill in ticket (with link if available) - If template without ticket field: add ticket at top of body - If no template: include ticket at start of description - If using template, structure description according to template format 4. **Create draft PR**: - Use `gh pr create --draft` with ticket-formatted title and body - Include template content if applicable - Ensure body is passed via heredoc for proper formatting 5. **Verify creation**: - Confirm PR was created successfully - Display PR URL to user - Remind user that PR is in draft state 6. **Provide next steps**: - Inform user how to mark PR ready when appropriate - Note any CI/CD checks that will run ## Example Commands ### PR with ticket from branch name ```bash # Detect ticket from branch (e.g., MSI-608/zendesk2) BRANCH=$(git branch --show-current) # Parse ticket: MSI-608 # Create draft PR with ticket in title gh pr create --draft --title "[MSI-608] Add Zendesk integration" --body "$(cat <<'EOF' **Ticket:** [MSI-608](https://company.atlassian.net/browse/MSI-608) ## Summary Added Zendesk integration for customer support tickets ## Changes - Implemented Zendesk API client - Added webhook handlers EOF )" ``` ### PR with template containing ticket placeholder ```bash # Template has "Ticket: [TICKET]" placeholder # Replace with actual ticket and link gh pr create --draft --title "[PLATFORM-123] Refactor API endpoints" --body "$(cat <<'EOF' ## Ticket [PLATFORM-123](https://jira.company.com/browse/PLATFORM-123) ## Summary [Filled from template] ## Test Plan [Filled from template] EOF )" ``` ### PR with GitHub issue number ```bash # Detect from branch: 456-fix-auth-bug gh pr create --draft --title "[#456] Fix authentication bug" --body "$(cat <<'EOF' **Related Issue:** [#456](https://github.com/owner/repo/issues/456) ## Summary Fixed authentication token expiration handling EOF )" ``` ## Important Notes - **Detect ticket numbers** - Always attempt to find associated ticket from context, branch, or commits before asking user - **Always use `--draft` flag** - Never create PRs as immediately ready for review - **Include ticket in title** - Format as `[TICKET] Title` when ticket is identified - **Link tickets when possible** - Use context knowledge to determine ticket URLs - **Respect template structure** - When templates exist, follow their format exactly - **Use heredoc for body** - Ensures proper multiline formatting and prevents shell escaping issues - **Verify template locations** - Check all three standard locations before proceeding - **Inform the user** - Always communicate that the PR was created as a draft and how to mark it ready ## Edge Cases **No ticket found and user declines to provide**: If user indicates there's no associated ticket or chooses not to provide one, proceed with PR creation without ticket in title or body **Multiple ticket references**: If multiple tickets are found, ask user which is the primary ticket for this PR **Invalid ticket format**: If detected ticket doesn't match expected patterns, verify with user before using **Cannot determine ticket URL**: If ticket is identified but URL cannot be determined from context, include ticket number without link **No git repository**: Verify current directory is a git repository before proceeding **Not a GitHub repository**: Confirm remote is GitHub before using `gh` commands **No GitHub CLI**: If `gh` command is not available, inform user to install GitHub CLI **Branch already has PR**: If a PR already exists for the current branch, inform user rather than creating duplicate **No commits to push**: Ensure there are commits to include in the PR before creating it --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/dhughes) — claim your Tome and manage your conversions.