pr-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pr-creator

Write PR descriptions like a developer posting in Slack, not an AI summarizing a diff.

IS: creating or updating a GitHub PR's title, body, draft state, and reviewers, plus the commit restructuring and review path that make a large diff readable.
IS NOT: changing the code in the diff (use
```
tidy
```
), reviewing it for bugs (use
```
pr-reviewer
```
), watching CI and review comments after the PR exists (use
```
pr-babysitter
```
), or cutting npm releases (use
```
autoship
```
).

撰写PR描述时要像开发者在Slack上发帖一样自然，而非AI生硬地总结代码差异。

负责： 创建或更新GitHub PR的标题、正文、草稿状态、指定评审人，同时处理提交重构和评审路径，让大体积代码差异更易读。
不负责： 修改代码差异中的代码（请使用
```
tidy
```
）、检查代码中的bug（请使用
```
pr-reviewer
```
）、PR创建后监控CI和评审评论（请使用
```
pr-babysitter
```
）、发布npm包（请使用
```
autoship
```
）。

Reference Files

参考文件

File	Read When
`references/pr-polish.md`	Commits contain fixup, WIP, or "address review" noise, the diff exceeds 500 lines, or the user asks to polish, restructure, squash, or split the PR

文件	读取时机
`references/pr-polish.md`	提交包含fixup、WIP或「处理评审意见」等冗余内容、代码差异超过500行，或用户要求优化、重构、压缩拆分PR时

Workflow

工作流程

Copy this checklist to track progress:

text

PR creation progress:
- [ ] Inspect the current branch and diff against the existing PR base, or the discovered default branch merge-base
- [ ] Existing PR? gh pr view --json url,state,isDraft (state OPEN means edit, not create)
- [ ] Linear ID from branch, commits, prompt, or issue link; no ID means no prefix
- [ ] Noisy commits or a >500-line diff? references/pr-polish.md, before pushing
- [ ] PR template present? Read it (paths under Templates)
- [ ] Draft title and body against Rules and Anti-patterns
- [ ] git push -u origin HEAD
- [ ] gh pr create (or gh pr edit); then gh pr view --json url,title and return the URL

Do not ask the user to approve the description first; the point is speed. They can ask for a rewrite and you run

gh pr edit

复制以下清单跟踪进度：

text

PR创建进度:
- [ ] 检查当前分支，并与现有PR的基准分支或已识别的默认分支合并基准对比代码差异
- [ ] 是否存在现有PR？执行gh pr view --json url,state,isDraft（状态为OPEN表示需编辑而非创建）
- [ ] 从分支、提交、提示或议题链接中获取Linear ID；若无ID则无需添加前缀
- [ ] 提交内容冗余或代码差异超过500行？先参考references/pr-polish.md再推送
- [ ] 是否存在PR模板？读取模板（路径在Templates下）
- [ ] 根据规则与反模式草拟标题和正文
- [ ] 执行git push -u origin HEAD
- [ ] 执行gh pr create（或gh pr edit）；随后执行gh pr view --json url,title并返回URL

无需先请求用户批准描述内容，核心目标是提升速度。用户可要求重写，届时执行

gh pr edit

即可。

Rules

规则

Title. With a Linear ID:
```
ABC-123: Add auth flow
```
. Without one:
```
Add auth flow
```
. Under 60 characters, no trailing period. If the repo lints PR titles (a
```
semantic-pull-request
```
or commitlint workflow under
```
.github/workflows/
```
), use its shape and put the ID at the end:
```
feat: add auth flow (ABC-123)
```
. Linear links on the ID wherever it sits in the title.
Body. One short paragraph: what changed and why it matters. Length follows the change; a one-line body is fine for a one-line fix.
No fake why. If the reason is not in the prompt, the Linear issue, the branch, the commits, or the diff, leave it out rather than inventing one.
Risk only when real. One
```
Risk:
```
line for migrations, billing, auth, permissions, irreversible writes, wide blast radius, or a subtle behavior change. Otherwise nothing.
Testing only if real. Say what you ran only if you ran it. Never a
```
Test plan
```
section, never checkboxes.
Partial work. If this PR does not finish the Linear issue, keep the ID out of the title and write
```
Part of ABC-123
```
in the body. Linear's default automation moves a linked issue to Done when the PR merges; the non-closing magic word links without closing.
Draft and reviewers only when asked.
```
--draft
```
for "draft" or "WIP";
```
gh pr ready
```
promotes it later,
```
gh pr ready --undo
```
demotes.
```
--reviewer alice,org/team
```
only for people the user named; CODEOWNERS already requests owners.
Stop after the useful content. The harness's
```
attribution
```
setting owns the PR footer (
```
Generated with Claude Code
```
, session link). Never hand-write one, and never strip one the harness or a repo policy appends. Everything above the footer is this skill's; its one-paragraph body replaces the harness's default
```
Summary
```
and
```
Test plan
```
sections.

标题：带有Linear ID时格式为
```
ABC-123: Add auth flow
```
；无ID时格式为
```
Add auth flow
```
。长度不超过60字符，末尾无句号。若仓库会校验PR标题（
```
.github/workflows/
```
下存在
```
semantic-pull-request
```
或commitlint工作流），请遵循其格式并将ID放在末尾：
```
feat: add auth flow (ABC-123)
```
。无论ID在标题中的哪个位置，都需添加Linear链接。
正文：简短段落说明变更内容及其重要性。长度随变更规模调整：单行修复对应单行正文即可。
不虚构原因：若提示、Linear议题、分支、提交或代码差异中未提及变更原因，请勿编造，直接省略。
仅如实标注风险：仅当涉及迁移、计费、认证、权限、不可逆写入、影响范围广或行为细微变更时，添加一行
```
Risk:
```
说明。否则无需标注。
仅如实标注测试：仅当实际执行了测试时，说明执行的内容。请勿添加「测试计划」章节或复选框。
部分完成的工作：若此PR未完成Linear议题，请勿将ID放在标题中，而是在正文里写入
```
Part of ABC-123
```
。Linear默认自动化会在PR合并时将关联议题标记为Done；使用这个非关闭关键词可关联议题但不触发自动完成。
仅在要求时设置草稿和评审人：当用户提及「draft」或「WIP」时添加
```
--draft
```
参数；后续可执行
```
gh pr ready
```
将其转为正式PR，
```
gh pr ready --undo
```
转回草稿。仅当用户指定人员时使用
```
--reviewer alice,org/team
```
；CODEOWNERS会自动请求所有者评审。
内容点到为止：工具的
```
attribution
```
设置负责PR页脚内容（如
```
Generated with Claude Code
```
、会话链接）。请勿手动编写页脚，也不要移除工具或仓库策略应用自动添加的页脚。页脚以上的内容由本工具负责；本工具生成的单段落正文会替代工具默认的「Summary」和「Test plan」章节。

Anti-patterns: never write these

反模式：切勿撰写以下内容

Openers that narrate the artifact: "This PR implements...", "This change ensures...", "This commit introduces..."
Changelog verbs with no reason attached: "Refactored X to improve Y", "Updated Z to handle...", "Added comprehensive test coverage for..."
Lines that start with a filename or path; the diff already lists the files
A
```
Test plan
```
section with checkboxes
A bullet list that restates the diff

以叙述PR本身开头的语句：「This PR implements...」「This change ensures...」「This commit introduces...」
未说明原因的变更日志式表述：「Refactored X to improve Y」「Updated Z to handle...」「Added comprehensive test coverage for...」
以文件名或路径开头的行；代码差异中已列出所有文件
带复选框的「Test plan」章节
重复代码差异内容的项目符号列表

Examples

示例

Feature (

ABC-123

is the real Linear ID)

功能（

ABC-123

为真实Linear ID）

text

Title: ABC-123: Add auth flow with session management

Adds the auth flow needed for session-based login, including refresh, timeout handling, and a small error boundary for auth failures.

text

Title: ABC-123: Add auth flow with session management

Adds the auth flow needed for session-based login, including refresh, timeout handling, and a small error boundary for auth failures.

Bugfix (real risk, real testing)

Bug修复（真实风险、真实测试）

text

Title: PAY-482: Dedupe Stripe webhook retries

Stripe retries webhooks on timeout and our handler wasn't idempotent, so retried events created duplicate invoices. Now we record processed event IDs and skip repeats. Tested by replaying a captured retry sequence locally.

Risk: touches the billing write path.

text

Title: PAY-482: Dedupe Stripe webhook retries

Stripe retries webhooks on timeout and our handler wasn't idempotent, so retried events created duplicate invoices. Now we record processed event IDs and skip repeats. Tested by replaying a captured retry sequence locally.

Risk: touches the billing write path.

Chore (no Linear ID, no why beyond the diff)

日常维护（无Linear ID，无代码差异之外的原因）

text

Title: Bump eslint to 9 and fix the new no-unused-vars hits

Bumps eslint to 9. The only code change is removing three unused imports it now flags.

The first two carry the real why from the commits and stop.

Risk:

earns its line in the second because the diff touches billing writes; the testing sentence is there only because a replay actually ran. The third has no deeper why, so it does not pretend to.

text

Title: Bump eslint to 9 and fix the new no-unused-vars hits

Bumps eslint to 9. The only code change is removing three unused imports it now flags.

前两个示例从提交内容中提取真实原因并点到为止。第二个示例中的

Risk:

行是合理的，因为代码差异涉及计费写入路径；测试语句仅在实际执行了重放测试时才添加。第三个示例没有更深层次的原因，因此不做虚构。

Templates

模板

GitHub reads the first match of

pull_request_template.md

(case-insensitive) in

.github/

, the repo root, or

docs/

, or a

PULL_REQUEST_TEMPLATE/

directory in any of those for multiple templates.

gh pr create --body

skips the template entirely, so when one exists, read it and write the body in its shape: keep its headings, answer each in a sentence or two, and put the one-paragraph description under the first heading. Add nothing the template does not ask for.

GitHub会读取

.github/

、仓库根目录或

docs/

中第一个匹配的

pull_request_template.md

（大小写不敏感），或上述任一目录下

PULL_REQUEST_TEMPLATE/

文件夹中的多个模板。

gh pr create --body

会完全跳过模板，因此当存在模板时，请读取模板并按照其格式撰写正文：保留模板的标题，每个标题下用一到两句话作答，并将单段落描述放在第一个标题下。请勿添加模板未要求的内容。

Creating the PR

创建PR

Write the exact body to a temporary file with the file tool, then pass its path through

--body-file

. The examples use

/tmp/pr-body.md

; choose a task-specific temporary path during execution.

使用文件工具将完整正文写入临时文件，然后通过

--body-file

参数传入文件路径。示例中使用

/tmp/pr-body.md

；执行时请选择任务专属的临时路径。

No PR yet: create

尚未创建PR：新建

bash

git push -u origin HEAD   # when creating a PR for local commits

gh pr create --title "ABC-123: Add auth flow" --body-file /tmp/pr-body.md

gh pr view --json url,title   # evidence the PR exists; return the url

Add

--draft

--reviewer

here when Rule 7 applies.

--base

only when the target is not the default branch.

bash

git push -u origin HEAD   # 为本地提交创建PR时执行

gh pr create --title "ABC-123: Add auth flow" --body-file /tmp/pr-body.md

gh pr view --json url,title   # 确认PR已创建；返回URL

当规则7适用时，在此处添加

--draft

或

--reviewer

参数。仅当目标分支不是默认分支时使用

--base

参数。

PR already open: update title and body

PR已打开：更新标题和正文

gh pr edit

overwrites the title and body wholesale, so draft the full replacement, not a patch. Same rules and anti-patterns apply.

bash

undefined

gh pr edit

会完全覆盖标题和正文，因此请草拟完整的替换内容，而非补丁。同样遵循上述规则与反模式。

bash

undefined

A metadata-only edit does not push local commits.

仅编辑元数据无需推送本地提交。

gh pr edit --title "ABC-123: Add auth flow" --body-file /tmp/pr-body.md

gh pr view --json url,title # confirm the update; return the url

undefined

gh pr edit --title "ABC-123: Add auth flow" --body-file /tmp/pr-body.md

gh pr view --json url,title # 确认更新完成；返回URL

undefined

Gotchas

注意事项

```
gh pr create
```
on a branch with no upstream: in a TTY it blocks on a "Where should we push?" prompt; from a non-interactive harness it aborts with
```
you must first push the current branch to a remote, or use the --head flag
```
. Either way,
```
git push -u origin HEAD
```
first.
Non-interactive
```
gh pr create
```
needs both
```
--title
```
and
```
--body
```
(or
```
--fill
```
); without them it exits with
```
must provide --title and --body (or --fill) when not running interactively
```
.
```
--fill
```
copies commit messages verbatim, which is exactly the changelog body this skill exists to avoid.
Quote the heredoc delimiter (
```
<<'EOF'
```
). Unquoted
```
<<EOF
```
lets the shell expand backticks and
```
$vars
```
in the body, corrupting the description or running commands.
Two different failures look alike: on the default branch,
```
gh pr create
```
aborts with
```
must be on a branch named differently than "main"
```
; on a branch with nothing new against the base it fails with
```
No commits between main and <branch>
```
. The first needs a branch, the second a commit.

A branch with an open PR fails

gh pr create

with

a pull request for branch ... into branch main already exists

gh pr view --json state

first;

OPEN

means

gh pr edit

. A

MERGED

CLOSED

result is a stale PR, so create a new one.

Derive the Linear ID from the branch, uppercased: Linear's default branch format is
```
username/abc-123-title-slug
```
, so
```
mblode/abc-123-add-auth
```
gives
```
ABC-123
```
. Never guess an ID: Linear links the PR to whatever ID the title contains, and a wrong one moves someone else's issue.
Plain
```
git diff
```
omits committed changes. Use the actual PR base with three-dot diff; do not assume
```
main
```
, especially for stacked PRs.
Restructure commits before the first push. Force-pushing a rewritten branch under an open PR marks existing inline comments "outdated" and the reviewer loses their thread.

在无上游分支的分支上执行
```
gh pr create
```
：在交互式终端中会阻塞并提示「Where should we push?」；在非交互式工具中会报错并终止，错误信息为
```
you must first push the current branch to a remote, or use the --head flag
```
。无论哪种情况，都需先执行
```
git push -u origin HEAD
```
。
非交互式
```
gh pr create
```
需要同时提供
```
--title
```
和
```
--body
```
（或
```
--fill
```
）；若未提供则会报错退出，错误信息为
```
must provide --title and --body (or --fill) when not running interactively
```
。
```
--fill
```
会直接复制提交信息，而这正是本工具要避免的变更日志式正文。
引用文档分隔符时请加引号（
```
<<'EOF'
```
）。未加引号的
```
<<EOF
```
会让shell解析反引号和
```
$vars
```
，导致描述内容损坏或执行意外命令。
两种不同的失败看起来相似：在默认分支上执行
```
gh pr create
```
会报错终止，错误信息为
```
must be on a branch named differently than "main"
```
；在与基准分支无差异的分支上执行会报错
```
No commits between main and <branch>
```
。第一种情况需要切换分支，第二种情况需要提交代码变更。
已存在开放PR的分支执行
```
gh pr create
```
会报错，错误信息为
```
a pull request for branch ... into branch main already exists
```
。请先执行
```
gh pr view --json state
```
；状态为
```
OPEN
```
时应执行
```
gh pr edit
```
。状态为
```
MERGED
```
或
```
CLOSED
```
表示PR已过时，可新建PR。
从分支名称中提取Linear ID并转为大写：Linear默认分支格式为
```
username/abc-123-title-slug
```
，例如
```
mblode/abc-123-add-auth
```
可提取出
```
ABC-123
```
。请勿猜测ID：Linear会将PR与标题中的任意ID关联，错误的ID会导致他人的议题被错误更新。
普通
```
git diff
```
会忽略已提交的变更。请使用实际PR基准分支的三点差异对比；不要默认使用
```
main
```
分支，尤其是在堆叠PR的场景中。
首次推送前重构提交内容。在已打开的PR下强制推送重写后的分支会将现有行内评论标记为「已过时」，导致评审人丢失其评论线程。

pr-creator

Original

Translation

pr-creator

pr-creator

Reference Files

参考文件

Workflow

工作流程

Rules

规则

Anti-patterns: never write these

反模式：切勿撰写以下内容

Examples

示例

Feature (
`ABC-123`
is the real Linear ID)

功能（
`ABC-123`
为真实Linear ID）

Bugfix (real risk, real testing)

Bug修复（真实风险、真实测试）

Chore (no Linear ID, no why beyond the diff)

日常维护（无Linear ID，无代码差异之外的原因）

Templates

模板

Creating the PR

创建PR

No PR yet: create

尚未创建PR：新建

PR already open: update title and body

PR已打开：更新标题和正文

A metadata-only edit does not push local commits.

仅编辑元数据无需推送本地提交。

Gotchas

注意事项

Related skills

相关工具

pr-creator

Original

Translation

pr-creator

pr-creator

Reference Files

参考文件

Workflow

工作流程

Rules

规则

Anti-patterns: never write these

反模式：切勿撰写以下内容

Examples

示例

Feature (ABC-123 is the real Linear ID)

功能（ABC-123为真实Linear ID）

Bugfix (real risk, real testing)

Bug修复（真实风险、真实测试）

Chore (no Linear ID, no why beyond the diff)

日常维护（无Linear ID，无代码差异之外的原因）

Templates

模板

Creating the PR

创建PR

No PR yet: create

尚未创建PR：新建

PR already open: update title and body

PR已打开：更新标题和正文

A metadata-only edit does not push local commits.

仅编辑元数据无需推送本地提交。

Gotchas

注意事项

Related skills

相关工具

Feature (
`ABC-123`
is the real Linear ID)

功能（
`ABC-123`
为真实Linear ID）