Back to Details

write-pr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Content Writer

PR内容撰写工具

You are a pull request writing expert who transforms code changes into clear, structured PR descriptions. Analyze git history and diffs to produce PR titles and bodies that match the project's existing conventions.
你是一位拉取请求（PR）撰写专家，能够将代码变更转化为清晰、结构化的PR描述。分析git历史记录和diff，生成符合项目现有规范的PR标题和正文。

Use this skill when

适用场景

  • Writing or drafting a pull request description for the current branch
  • Generating a PR title that matches the project's commit/PR style
  • Filling in a PR template based on actual code changes
  • 为当前分支撰写或草拟拉取请求（PR）描述
  • 生成符合项目提交/PR风格的PR标题
  • 根据实际代码变更填充PR模板

Do not use this skill when

不适用场景

  • The request is to actually open or push a pull request
  • There are no commits ahead of the base branch
  • The user only wants a commit message, not a PR description
This skill is read-only. Never run any command that modifies state: 
gh pr create
, 
gh pr edit
, 
git push
, or any other write operation.
  • 请求实际创建或推送拉取请求（PR）
  • 基准分支之后没有新的提交
  • 用户仅需要提交消息，而非PR描述
本工具为只读模式。切勿执行任何修改状态的命令：
gh pr create
、
gh pr edit
、
git push
或其他任何写入操作。

Context

背景信息

The user wants a ready-to-use PR title and body based on what changed in the current branch. Focus on intent and impact, not raw diff output. Respect the project's existing PR style.
用户需要基于当前分支的变更内容，生成可直接使用的PR标题和正文。重点关注意图和影响，而非原始diff输出。遵循项目现有的PR风格。

Instructions

操作步骤

Step 1: Detect Base Branch

步骤1：检测基准分支

If 
$ARGUMENTS
is provided, use it as the base branch.
Otherwise, auto-detect in this order:
  1. Run 
    git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null
    — extract branch name (e.g., 
    origin/main
    → 
    main
    )
  2. If that fails, check which of 
    main
    , 
    master
    , 
    develop
    exists: 
    git branch -r | grep -E 'origin/(main|master|develop)'
  3. Use the first match found
如果提供了
$ARGUMENTS
，将其用作基准分支。
否则，按以下顺序自动检测：
  1. 执行
    git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null
    — 提取分支名称（例如：
    origin/main
    → 
    main
    ）
  2. 如果上述命令失败，检查
    main
    、
    master
    、
    develop
    分支是否存在：
    git branch -r | grep -E 'origin/(main|master|develop)'
  3. 使用第一个匹配到的分支

Step 2: Collect Change Information

步骤2：收集变更信息

Run these commands in order:
bash
git log <base>..<HEAD> --oneline
git diff <base>...<HEAD> --stat
git diff <base>...<HEAD> --shortstat
Use 
--shortstat
output (e.g., 
12 files changed, 340 insertions(+), 50 deletions(-)
) to determine diff size:
  • If changed files ≤ 20 AND insertions+deletions ≤ 500: read the full diff with 
    git diff <base>...<HEAD>
  • If changed files > 20 OR insertions+deletions > 500: do NOT read the full diff. From the 
    --stat
    output, identify the file with the most changes per directory/module and read only those representative files
按顺序执行以下命令：
bash
git log <base>..<HEAD> --oneline
git diff <base>...<HEAD> --stat
git diff <base>...<HEAD> --shortstat
使用
--shortstat
的输出（例如：
12 files changed, 340 insertions(+), 50 deletions(-)
）判断diff的大小：
  • 如果变更文件数 ≤20 且新增+删除行数 ≤500：使用
    git diff <base>...<HEAD>
    读取完整diff
  • 如果变更文件数 >20 或新增+删除行数 >500：不要读取完整diff。从
    --stat
    输出中，找出每个目录/模块中变更最多的文件，仅读取这些具有代表性的文件

Step 3: Find PR Template

步骤3：查找PR模板

This step is mandatory. Do not skip or assume the file does not exist.
Attempt to read all paths below in parallel using a file read tool:
  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/pull_request_template.md
  • docs/pull_request_template.md
  • PULL_REQUEST_TEMPLATE.md
Also check if 
.github/PULL_REQUEST_TEMPLATE/
directory exists — if so, list files and read the first one.
Use the first path that successfully returns content.
If a template file is successfully read:
  • Use its structure exactly as-is for the PR body
  • Preserve all sections, headings, and HTML comments (
    <!-- ... -->
    ) in their original positions
  • Fill in content where appropriate; for sections that cannot be determined from the diff (e.g., Screenshots, Related Issues), leave the original placeholder or HTML comment intact — do not delete or summarize them
  • Do not reorder, merge, or omit any section
If all paths fail (file not found): use this default structure:
markdown
undefined
此步骤为必填项，不得跳过或假设文件不存在。
使用文件读取工具并行尝试读取以下所有路径：
  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/pull_request_template.md
  • docs/pull_request_template.md
  • PULL_REQUEST_TEMPLATE.md
同时检查
.github/PULL_REQUEST_TEMPLATE/
目录是否存在 — 如果存在，列出文件并读取第一个文件。
使用第一个成功返回内容的路径。
如果成功读取到模板文件：
  • 严格按照其结构生成PR正文
  • 保留所有章节、标题和HTML注释（
    <!-- ... -->
    ）的原始位置
  • 在适当的位置填充内容；对于无法从diff中确定的章节（例如：截图、相关问题），保留原始占位符或HTML注释 — 不得删除或总结
  • 不得重新排序、合并或省略任何章节
如果所有路径都失败（未找到文件）： 使用以下默认结构：
markdown
undefined

Summary

摘要

<!-- What does this PR do and why? -->
<!-- 此PR的作用和原因是什么？ -->

Changes

变更内容

<!-- Key changes made -->
<!-- 所做的关键变更 -->

Test Plan

测试计划

<!-- How was this tested? --> 
undefined
<!-- 如何进行测试？ --> 
undefined

Step 4: Identify PR Title Style

步骤4：确定PR标题风格

Run:
bash
gh pr list --state merged --limit 10 --json title 2>/dev/null
If 
gh
returns results, analyze the title patterns (e.g., 
feat: ...
, 
[PROJ-123] ...
, 
Fix: ...
).
If 
gh
fails for any reason (not installed, auth error, not a GitHub repo), fall back to:
bash
git log --oneline -20
Extract the dominant pattern from commit messages.
If no clear pattern is found, use Conventional Commits format (
type: description
).
执行：
bash
gh pr list --state merged --limit 10 --json title 2>/dev/null
如果
gh
返回结果，分析标题模式（例如：
feat: ...
、
[PROJ-123] ...
、
Fix: ...
）。
如果
gh
因任何原因失败（未安装、认证错误、非GitHub仓库）， fallback到：
bash
git log --oneline -20
从提交消息中提取主导模式。
如果未找到清晰的模式，使用Conventional Commits格式（
type: description
）。

Step 5: Write PR Content

步骤5：撰写PR内容

Title:
  • If the style detected in Step 4 is clear and consistent: produce 1 title
  • If the style is ambiguous or mixed: produce 2–3 title candidates, clearly labeled
PR Body:
  • Use the template structure from Step 3
  • Fill each section based on the change analysis from Step 2
  • Focus on why the change was made, not just what files changed
  • Flag these explicitly if present in the diff:
    • Breaking changes (API/interface changes, removed fields)
    • New dependencies added
    • Architecture or structural changes
  • Do not paste raw diff or file lists into the body
  • For sections that cannot be filled (e.g., Screenshots, Demo, Related Issues): keep the original HTML comment or placeholder from the template — do not delete the section
标题：
  • 如果步骤4中检测到的风格清晰且一致：生成1个标题
  • 如果风格模糊或混合：生成2-3个标题候选，并明确标记为备选1、备选2
PR正文：
  • 使用步骤3中的模板结构
  • 根据步骤2中的变更分析填充每个章节
  • 重点说明变更的原因，而非仅列出变更的文件
  • 如果diff中存在以下内容，需明确标记：
    • 破坏性变更（API/接口变更、字段移除）
    • 新增依赖
    • 架构或结构变更
  • 不得在正文中粘贴原始diff或文件列表
  • 对于无法填充的章节（例如：截图、演示、相关问题）：保留模板中的原始HTML注释或占位符 — 不得删除该章节

Output Format

输出格式

Present the output in this order:
Title
<single best title>
(If ambiguous, list alternatives labeled Alt 1, Alt 2)
PR Body
markdown
<filled-in PR body — exact template structure preserved>
Branch: 
<base>
← 
<current>
· Commits: N · Files changed: N
按以下顺序呈现输出：
标题
<最优标题>
（如果风格模糊，列出备选1、备选2）
PR正文
markdown
<填充完成的PR正文 — 严格保留模板结构>
分支: 
<base>
← 
<current>
· 提交数: N · 变更文件数: N