pr-description-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Description Writer Skill

PR描述撰写Skill

This skill generates clean, structured, production-ready Pull Request descriptions in Markdown format.

The user provides context about their PR (changes, bug, feature, architecture, etc). The skill determines or asks for the PR type and generates the correct template.

该Skill可生成简洁、结构化、可直接用于生产环境的Markdown格式Pull Request描述。

用户只需提供PR的相关背景信息（如变更内容、bug修复、功能开发、架构调整等），该Skill会自动判断或询问PR类型，然后生成对应的模板内容。

Proactive PR Detection

主动PR检测

Before generating anything, always check if an open Pull Request already exists for the current branch using the

gh

CLI:

bash

gh pr view --json number,title,url,body 2>/dev/null

If a PR is found, note its number, current title, URL, and body. Inform the user that an open PR was detected and show the PR URL.
If no PR is found (command exits non-zero), skip this step and proceed normally.

This detection is automatic — do not ask the user whether to check. Always check.

在生成任何内容之前，必须使用

gh

CLI检查当前分支是否已存在开放的Pull Request：

bash

gh pr view --json number,title,url,body 2>/dev/null

如果检测到PR，记录其编号、当前标题、URL和内容。告知用户已检测到开放PR，并展示PR的URL。
如果未检测到PR（命令执行返回非零值），则跳过此步骤，正常执行后续流程。

此检测为自动执行——无需询问用户是否需要检测，必须默认执行。

PR Types

PR类型

Supported types:

```
issue
```
```
feature
```
```
big-feature
```

If the user does not specify the type, ask them to choose one.

支持的类型：

```
issue
```
```
feature
```
```
big-feature
```

如果用户未指定PR类型，需询问用户进行选择。

General Writing Rules

通用撰写规则

Write in English.
Be concise and high-signal.
Avoid generic filler text.
Focus on why + impact, not only what changed.
Use clean, professional technical writing.
Prefer clear technical explanations over marketing language.

使用英文撰写PR内容
简洁明了，突出关键信息
避免使用通用的填充文本
重点说明原因与影响，而非仅描述变更内容
使用专业、规范的技术写作风格
优先选择清晰的技术解释，而非营销话术

PR Title Rules

PR标题规则

The skill must always generate a PR title before the description.

Rules:

Must be concise and descriptive
Must reflect intent and impact (not only change)
Prefer conventional PR style when possible

Examples:

fix(auth): prevent session reset on refresh

feat(payments): add MercadoPago checkout support

refactor(ui): migrate layout system to grid tokens

该Skill必须先生成PR标题，再生成描述内容。

规则：

必须简洁且具有描述性
必须体现意图与影响（而非仅描述变更）
尽可能遵循常规PR标题风格

示例：

fix(auth): prevent session reset on refresh

feat(payments): add MercadoPago checkout support

refactor(ui): migrate layout system to grid tokens

Output Mode

输出模式

This skill ONLY generates Markdown output.

It always:

Generates PR title
Generates PR description
Formats everything as Markdown
Is ready for manual copy/paste into GitHub

该Skill仅生成Markdown格式的输出。

输出内容始终包含：

PR标题
PR描述
所有内容均以Markdown格式排版
可直接复制粘贴至GitHub使用

Final Output Format

最终输出格式

undefined

undefined

<PR Title>

<PR Description using the selected template> ```

Linear Issue / Issue Link

Linear Issue / 问题链接

Always ask if there is a related issue (Linear, Jira, GitHub Issues, or similar).

If an issue exists, add this section at the top of the PR description:

undefined

必须询问用户是否存在相关的问题（如Linear、Jira、GitHub Issues等平台的问题）。

如果存在相关问题，需在PR描述顶部添加以下章节：

undefined

Issue

[Issue link here]


If there is no issue, omit this section.

---

[Issue link here]


如果不存在相关问题，则省略此章节。

---

Template --- Issue

模板 --- Issue

Use for:

Bugs
Fixes
Regressions
Performance problems
Technical corrections

undefined

适用场景：

Bug修复
问题修正
回归问题修复
性能优化
技术修正

undefined

Problem

<清晰解释bug或问题。问题表现是什么？何时会出现？>

Root Cause

<如果已知，解释问题的技术原因。>

Solution

<解释变更内容，以及该变更为何能解决问题。>

Result

---

<解释变更带来的影响。如有可用的演示链接、视频或截图，请附上。>

---

Template --- Feature (Small / Medium)

模板 --- Feature（中小型）

Use for:

Normal features
Improvements
Small UX additions
Non-architectural changes

undefined

适用场景：

常规功能开发
功能改进
小型UX新增功能
非架构性变更

undefined

Problem

<解释需求、现有局限或缺失的功能。>

Root Cause

<Optional. Only include if there was a technical limitation to solve.>

<可选。仅当存在需要解决的技术局限时才添加。>

Result

<Explain what the new feature enables and its impact.> ```

Rules:

Do NOT include Solution section for features.
Root Cause is optional.

<解释新功能带来的能力及其影响。>


规则：
- 功能类PR**不得**包含**Solution**章节。
- Root Cause章节为可选。

---

Template --- Big Feature

模板 --- Big Feature

Use for:

New systems
Architectural changes
Major UX flows
New platform capabilities
Large refactors

undefined

适用场景：

新系统开发
架构变更
主要UX流程调整
新平台能力搭建
大型重构

undefined

Summary

<该PR引入的核心内容及其重要性的高层级说明。>

Key Changes

<Main change>
<Main change>
<Main change>

<主要变更>
<主要变更>
<主要变更>

Architecture Overview

1. Concept / Strategy

<解释核心架构理念>

2. Implementation

<Folders, routing, state, patterns, infra, etc>

<涉及的文件夹、路由、状态管理、设计模式、基础设施等>

3. Components / Systems

<涉及的主要模块或领域>

4. Data / State Flow

<数据在系统中的流转方式>

5. Navigation / UX Flow

<如适用>

6. Migration / Breaking Changes

<如适用>

Notes

<Tradeoffs, future improvements, known limitations>

---

<权衡方案、未来改进方向、已知局限>

---

Output Delivery

输出交付方式

After generating the PR Title and PR Description, the skill must ask the user how they want to receive the output.

If an open PR was detected for the current branch, present these options:

"Do you want me to update the open PR directly, generate a

.md

file, or just show it here?"

Options:

Update the open PR (recommended when a PR was detected) — uses
```
gh pr edit
```
to update title and body directly on GitHub.
Show in chat
Generate
```
.md
```
file

If no open PR was detected, present the standard options:

"Do you want me to generate a

.md

file with this content, or just show it here?"

Options:

Show in chat (default)
Generate
```
.md
```
file

生成PR标题和描述后，该Skill必须询问用户希望如何接收输出内容。

如果检测到当前分支存在开放PR，提供以下选项：

"您希望我直接更新该开放PR、生成

.md

文件，还是直接在聊天窗口展示？"

选项：

更新开放PR（检测到PR时推荐）——使用
```
gh pr edit
```
直接在GitHub上更新标题和内容。
在聊天窗口展示
生成
```
.md
```
文件

如果未检测到开放PR，提供标准选项：

"您希望我生成包含该内容的

.md

文件，还是直接在聊天窗口展示？"

选项：

在聊天窗口展示（默认）
生成
```
.md
```
文件

Updating an Open PR

更新开放PR

When the user confirms they want to update the open PR, use the

gh

CLI:

bash

gh pr edit <number> --title "<new title>" --body "<new body>"

Rules:

Never update the PR without explicit user confirmation. Always ask first using
```
AskUserQuestion
```
.
The
```
<number>
```
comes from the PR detected in the Proactive PR Detection step.
The
```
<new title>
```
is the generated PR title.
The
```
<new body>
```
is the generated PR description body (Markdown). Pass it via a heredoc to preserve formatting:

bash

gh pr edit <number> --title "<new title>" --body "$(cat <<'EOF'
<generated PR description body>
EOF
)"

After a successful update, confirm to the user and show the PR URL.
If the update fails, show the error and fall back to displaying the output in chat so the user can copy/paste manually.

当用户确认要更新开放PR时，使用

gh

CLI执行以下命令：

bash

gh pr edit <number> --title "<new title>" --body "<new body>"

规则：

**未经用户明确确认，绝不能更新PR。**必须使用
```
AskUserQuestion
```
先询问用户。
```
<number>
```
来自主动PR检测步骤中获取的PR编号。
```
<new title>
```
为生成的PR标题。
```
<new body>
```
为生成的PR描述内容（Markdown格式）。通过here-doc传递内容以保留格式：

bash

gh pr edit <number> --title "<new title>" --body "$(cat <<'EOF'
<generated PR description body>
EOF
)"

更新成功后，向用户确认并展示PR的URL。
如果更新失败，展示错误信息，并 fallback 到在聊天窗口展示输出内容，方便用户手动复制粘贴。

Markdown File Rules

Markdown文件规则

If the user requests a

.md

file:

The file must contain:
- PR Title as H1
- PR Description body
No extra text outside Markdown
File must be ready to upload or commit

如果用户请求生成

.md

文件：

文件必须包含：
- 作为一级标题的PR标题
- PR描述内容
不得包含Markdown格式以外的额外文本
文件必须可直接上传或提交

Behavior Rules

行为规则

When running this skill:

Proactively check for an open PR on the current branch using
```
gh pr view
```
. This is automatic — do not ask the user whether to check. If a PR is found, inform the user (show PR URL and number).
Detect PR type from context OR ask user to choose:
- issue
- feature
- big-feature
Always ask if there is a related issue link.
If issue exists, add Issue section at the top.
Generate:
- PR Title
- PR Description (Markdown body)
Ask how to deliver the output:
- If an open PR was detected: offer to update the PR directly, show in chat, or generate
```
.md
```
  file. Use
```
AskUserQuestion
```
  to confirm.
- If no open PR: offer to show in chat or generate
```
.md
```
  file.
If the user chose to update the open PR, run
```
gh pr edit
```
with the generated title and body. Never run this without confirmation.
If
```
.md
```
file is requested, generate file-ready Markdown content.

运行该Skill时：

主动检测当前分支的开放PR：使用
```
gh pr view
```
命令。此步骤为自动执行——无需询问用户是否需要检测。如果检测到PR，告知用户（展示PR的URL和编号）。
从上下文检测PR类型，或询问用户选择：
- issue
- feature
- big-feature
必须询问用户是否存在相关问题链接。
如果存在相关问题，在PR描述顶部添加Issue章节。
生成：
- PR标题
- PR描述（Markdown内容）
询问用户输出交付方式：
- 如果检测到开放PR：提供直接更新PR、在聊天窗口展示、生成
```
.md
```
  文件三个选项。使用
```
AskUserQuestion
```
  确认用户选择。
- 如果未检测到开放PR：提供在聊天窗口展示或生成
```
.md
```
  文件两个选项。
如果用户选择更新开放PR，使用生成的标题和内容执行
```
gh pr edit
```
命令。未经确认绝不能执行此操作。
如果用户请求生成
```
.md
```
文件，生成可直接使用的Markdown内容。

Quality Bar

质量标准

The generated PR description must:

Be copy-paste ready for GitHub PR
Be technically accurate
Be easy to scan
Be useful for reviewers and future maintainers

生成的PR描述必须：

可直接复制粘贴至GitHub PR使用
技术准确
易于快速浏览
对评审人员和未来维护人员有实际帮助