pr-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pull Request Creation Best Practices

拉取请求（PR）创建最佳实践

Purpose

目的

This skill enforces three critical best practices when creating GitHub pull requests:

Include ticket numbers - Associates PRs with tracking tickets (Jira, GitHub Issues)
Use PR templates when available - Ensures consistent, complete PR descriptions
Create PRs as drafts by default - Allows review before marking ready for review

此Skill在创建GitHub拉取请求时，会强制执行三项关键最佳实践：

关联工单编号 - 将PR与跟踪工单（Jira、GitHub Issues）关联
如有可用则使用PR模板 - 确保PR描述一致、完整
默认创建草稿PR - 允许在标记为可审核前进行自我检查

Ticket Detection and Integration

工单检测与集成

Before creating the pull request, attempt to identify an associated ticket number from Jira or GitHub Issues.

在创建拉取请求前，尝试从Jira或GitHub Issues中识别关联的工单编号。

Detection Sources

检测来源

Check the following sources for ticket numbers (in order of preference):

Conversation context - Ticket mentioned in recent messages or conversation history
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
Recent commit messages - Check for ticket references in commit messages
Ask user - If no ticket found in above sources, use AskUserQuestion to ask if there's an associated ticket

按以下优先级顺序检查工单编号来源：

对话上下文 - 近期消息或对话历史中提到的工单
分支名称 - 解析当前分支名称中的工单模式：
- ```
PROJ-123/description
```
  （Jira风格前缀）
- ```
feature/PROJ-123-description
```
  （前缀后的Jira编号）
- ```
123-description
```
  （GitHub Issue编号）
- 其他符合直觉的常见模式
近期提交信息 - 检查提交信息中的工单引用
询问用户 - 若以上来源均未找到工单，使用AskUserQuestion询问用户是否有关联工单

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)

识别以下常见模式：

Jira工单：
```
PROJ-123
```
、
```
ABC-456
```
（大写字母、连字符、数字组合）
GitHub Issues：
```
#123
```
、
```
456
```
（数字，可选带#前缀）

PR Title Integration

PR标题集成

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标题格式化为：

[TICKET-NUM] 描述性PR标题

示例：

```
[MSI-608] Add Zendesk integration
```
```
[#456] Fix authentication bug
```
```
[PLATFORM-123] Refactor API endpoints
```

PR Body Integration

PR正文集成

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)

**Ticket:** TICKET-NUM

if no URL

If no template:

Include ticket reference at the start of the PR description
Format with link if available

若PR模板包含工单字段：

查找类似
```
[TICKET]
```
、
```
[ISSUE]
```
、
```
Ticket:
```
、
```
Issue:
```
、
```
JIRA:
```
等占位符
用工单编号替换占位符（若能确定URL则添加链接）
保留模板格式

若模板无特定工单字段：

在PR正文顶部添加工单引用

格式为：

**工单：** [TICKET-NUM](url)

，若无法确定URL则使用

**工单：** TICKET-NUM

若无模板：

在PR描述开头包含工单引用
若可获取则添加链接

Ticket URL Determination

工单URL确定

Determine ticket URLs from available context and knowledge:

Check CLAUDE.md or project configuration - Look for Jira base URL, GitHub repo URL, or ticket system configuration
Parse git remote - Extract GitHub repository URL from git config for GitHub issues
Use conversation context - Apply knowledge from earlier in conversation about project's ticket systems
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.

根据可用上下文和知识确定工单URL：

检查CLAUDE.md或项目配置 - 查找Jira基础URL、GitHub仓库URL或工单系统配置
解析git远程仓库 - 从git配置中提取GitHub仓库URL以关联GitHub Issues
利用对话上下文 - 应用对话中关于项目工单系统的已知信息
从项目结构推断 - 查找
```
.jira
```
、项目配置文件或提及工单URL的文档

URL格式：

Jira：

https://company.atlassian.net/browse/PROJ-123

GitHub Issues：

https://github.com/owner/repo/issues/123

若无法确定URL，仅包含工单编号即可。

PR Template Discovery

PR模板发现

Before creating the pull request, check for GitHub PR templates in the

.github/

directory using the following search order:

```
.github/pull_request_template.md
```
(lowercase, standard GitHub convention)
```
.github/PULL_REQUEST_TEMPLATE.md
```
(uppercase variant)
```
.github/PULL_REQUEST_TEMPLATE/*.md
```
(multiple templates in subdirectory)

创建拉取请求前，按以下搜索顺序检查

.github/

目录中的GitHub PR模板：

```
.github/pull_request_template.md
```
（小写，GitHub标准约定）
```
.github/PULL_REQUEST_TEMPLATE.md
```
（大写变体）
```
.github/PULL_REQUEST_TEMPLATE/*.md
```
（子目录中的多个模板）

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

若找到模板：

读取模板文件以了解必填章节
使用
```
gh pr create --body
```
构建PR正文时遵循模板结构
根据提交的变更适当填充每个模板章节
保留模板格式、标题和结构

若

.github/PULL_REQUEST_TEMPLATE/

中存在多个模板：

向用户列出可用模板
询问用户本次PR使用哪个模板
使用用户选择的模板继续操作

若未找到模板：

按标准流程创建PR
生成包含以下内容的完整PR描述：
- 变更摘要
- 测试计划或验证步骤
- 任何相关上下文或决策

Draft PR Creation

草稿PR创建

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
)"

始终使用

--draft

标志创建草稿拉取请求：

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

草稿PR有多个优势：

允许在请求审核前运行CI/CD检查
提供在GitHub上查看PR差异后再征求反馈的机会
避免因未完成的工作意外向审核者发送通知垃圾信息
支持在标记为可审核前进行增量提交和优化

Making PR Ready for Review

将PR标记为可审核

After creating the draft PR, inform the user they can mark it ready for review when appropriate:

bash

gh pr ready <pr-number>

Or they can mark it ready directly on GitHub.

创建草稿PR后，告知用户可在合适时机将其标记为可审核：

bash

gh pr ready <pr-number>

或用户可直接在GitHub上进行标记。

Complete Workflow

完整工作流程

Follow this sequence when the user requests PR creation:

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
Check for PR templates:
- Search
```
.github/
```
  directory for template files
- If found, read template content
- Identify if template has ticket field/placeholder
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
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
Verify creation:
- Confirm PR was created successfully
- Display PR URL to user
- Remind user that PR is in draft state
Provide next steps:
- Inform user how to mark PR ready when appropriate
- Note any CI/CD checks that will run

用户请求创建PR时，遵循以下步骤：

检测工单编号：
- 检查对话上下文以查找工单引用
- 解析当前分支名称中的工单模式
- 检查近期提交信息
- 若未找到工单，使用AskUserQuestion询问用户
- 根据上下文、CLAUDE.md或git配置确定工单URL（若可能）
检查PR模板：
- 搜索
```
.github/
```
  目录中的模板文件
- 若找到，读取模板内容
- 确认模板是否包含工单字段/占位符
收集PR信息：
- 使用
```
git log
```
  和
```
git diff
```
  分析近期提交
- 生成包含工单的PR标题：
```
[TICKET] Title
```
- 生成PR描述：
  - 若模板包含工单字段：填充工单（若可获取则添加链接）
  - 若模板无工单字段：在正文顶部添加工单
  - 若无模板：在描述开头包含工单
- 若使用模板，根据模板结构组织描述
创建草稿PR：
- 使用
```
gh pr create --draft
```
  命令，搭配包含工单的标题和正文
- 若适用则包含模板内容
- 使用here-doc传递正文以确保格式正确
验证创建结果：
- 确认PR创建成功
- 向用户展示PR URL
- 提醒用户PR当前为草稿状态
提供后续步骤：
- 告知用户如何在合适时机将PR标记为可审核
- 说明将运行的CI/CD检查

Example Commands

示例命令

PR with ticket from branch name

从分支名称获取工单的PR

bash

undefined

bash

undefined

Detect ticket from branch (e.g., MSI-608/zendesk2)

从分支中检测工单（例如：MSI-608/zendesk2）

BRANCH=$(git branch --show-current)

Parse ticket: MSI-608

解析工单：MSI-608

Create draft PR with ticket in title

创建包含工单标题的草稿PR

gh pr create --draft --title "[MSI-608] Add Zendesk integration" --body "$(cat <<'EOF' Ticket: MSI-608

Summary

Added Zendesk integration for customer support tickets

Changes

Implemented Zendesk API client
Added webhook handlers EOF )"

undefined

Implemented Zendesk API client
Added webhook handlers EOF )"

undefined

PR with template containing ticket placeholder

包含工单占位符模板的PR

bash

undefined

bash

undefined

Template has "Ticket: [TICKET]" placeholder

模板包含 "Ticket: [TICKET]" 占位符

Replace with actual ticket and link

替换为实际工单和链接

gh pr create --draft --title "[PLATFORM-123] Refactor API endpoints" --body "$(cat <<'EOF'

Ticket

PLATFORM-123

Summary

[Filled from template]

Test Plan

[Filled from template] EOF )"

undefined

[Filled from template] EOF )"

undefined

PR with GitHub issue number

关联GitHub Issue编号的PR

bash

undefined

bash

undefined

Detect from branch: 456-fix-auth-bug

从分支检测：456-fix-auth-bug

gh pr create --draft --title "[#456] Fix authentication bug" --body "$(cat <<'EOF' Related Issue: #456

Summary

Fixed authentication token expiration handling EOF )"

undefined

Fixed authentication token expiration handling EOF )"

undefined

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

检测工单编号 - 询问用户前，始终尝试从上下文、分支或提交信息中查找关联工单
始终使用
--draft
标志 - 切勿直接创建可立即审核的PR
在标题中包含工单 - 识别到工单后，格式化为
```
[TICKET] Title
```
尽可能链接工单 - 使用上下文知识确定工单URL
遵循模板结构 - 若存在模板，严格按照其格式执行
使用here-doc传递正文 - 确保多行格式正确，避免Shell转义问题
验证模板位置 - 继续操作前检查所有三个标准位置
告知用户 - 始终告知用户PR已创建为草稿，以及如何将其标记为可审核

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

未找到工单且用户拒绝提供：若用户表示无关联工单或选择不提供，无需在标题或正文中包含工单即可创建PR

多个工单引用：若找到多个工单，询问用户哪个是本次PR的主要关联工单

无效工单格式：若检测到的工单不符合预期模式，使用前需与用户确认

无法确定工单URL：若识别到工单但无法从上下文确定URL，仅包含工单编号即可

无git仓库：继续操作前验证当前目录是否为git仓库

非GitHub仓库：使用

gh

命令前确认远程仓库为GitHub

无GitHub CLI：若

gh

命令不可用，告知用户安装GitHub CLI

分支已存在PR：若当前分支已有PR，告知用户而非创建重复PR

无提交可推送：创建PR前确保存在可包含的提交