make-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/make-pr — Create or Update a Pull Request

/make-pr — 创建或更新拉取请求

Push the current branch and create (or update) a GitHub PR with title, description, labels, and assignee.

推送当前分支并创建（或更新）一个包含标题、描述、标签和负责人的GitHub PR。

Workflow

工作流程

0. Check branch

0. 检查分支

bash

git branch --show-current

If on
main
(or
master
): run

/make-branch

skill first to move their changes to a feature branch. Do NOT proceed with PR creation from the main branch.

If on a placeholder / petname branch: run

/make-branch

to rename it before opening the PR. Petname branches are auto-generated names and should not become the public branch name of a PR. A branch is a placeholder if any of these match:

Petname pattern:
```
^[a-z]+-[a-z]+$
```
(two lowercase words joined by a single hyphen, no slash, no digits — e.g.
```
useful-pony
```
,
```
sound-midge
```
,
```
novel-aphid
```
). Claude Code and similar tools auto-generate these.
Generic placeholder name:
```
wip
```
,
```
tmp
```
,
```
temp
```
,
```
test
```
,
```
scratch
```
,
```
work
```
, or similar.

A branch matching

^(feat|fix|refactor|docs|test|chore|perf|ci)/.+

is conventional — proceed with PR creation.

bash

git branch --show-current

如果当前分支是
main
（或
master
）：请先运行

/make-branch

工具将变更转移到功能分支。不要从主分支创建PR。

如果当前分支是占位符/昵称分支：请先运行

/make-branch

重命名分支后再创建PR。昵称分支是自动生成的名称，不应作为PR的公开分支名称。如果分支符合以下任一情况，则属于占位符分支：

昵称格式：
```
^[a-z]+-[a-z]+$
```
（两个小写单词用单个连字符连接，无斜杠、无数字——例如
```
useful-pony
```
、
```
sound-midge
```
、
```
novel-aphid
```
）。Claude Code及类似工具会自动生成此类分支。
通用占位符名称：
```
wip
```
、
```
tmp
```
、
```
temp
```
、
```
test
```
、
```
scratch
```
、
```
work
```
或类似名称。

如果分支符合

^(feat|fix|refactor|docs|test|chore|perf|ci)/.+

格式，则属于规范分支——可继续创建PR。

1. Gather context

1. 收集上下文

Run these in parallel:

bash

git log main..HEAD --oneline
git diff main...HEAD --stat
gh label list --limit 50 --json name,description
git config user.name

Also check if a PR already exists for this branch:

bash

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

并行运行以下命令：

bash

git log main..HEAD --oneline
git diff main...HEAD --stat
gh label list --limit 50 --json name,description
git config user.name

同时检查该分支是否已存在对应的PR：

bash

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

2. Draft PR content

2. 草拟PR内容

Title:

<type>: <short description>

(under 70 chars). Conventional types:

feat

fix

refactor

docs

test

chore

perf

ci

. Match the PR theme, not just the last commit.

Labels: pick from

gh label list --json name,description

output. Apply only labels scoped to PRs — read each description and skip issue-scoped ones (e.g. descriptions starting with "Issue ..."). Verdict labels like

recommend-merge

recommend-close

recommend-triage

are applied during review, not at creation. If no label clearly applies, add none.

Assignee: default to the git user (

gh api user --jq '.login'

Body: invoke the

writing-pull-requests

skill before writing. Pick the smallest structure that carries the signal. Do NOT mechanically apply a fixed template; calibrate to the scope of the change.

标题：

<类型>: <简短描述>

（不超过70字符）。规范类型包括：

feat

、

fix

、

refactor

、

docs

、

test

、

chore

、

perf

、

ci

。标题需匹配PR主题，而非仅对应最后一次提交。

标签：从

gh label list --json name,description

的输出中选择。仅应用适用于PR的标签——阅读每个标签的描述，跳过针对Issue的标签（例如描述以"Issue ..."开头的标签）。

recommend-merge

recommend-close

recommend-triage

等裁决标签需在评审阶段添加，而非创建PR时添加。如果没有明确适用的标签，则不添加。

负责人：默认设置为Git用户（

gh api user --jq '.login'

）。

正文：撰写前请调用

writing-pull-requests

工具。选择能传递关键信息的最简结构。不要机械套用固定模板；需根据变更范围调整内容。

Body by scope

按范围撰写正文

These tiers fix the structure (headers, checklist shape); how much prose goes inside them is

writing-pull-requests

's call.

Small change (docs, single bugfix, dep bump, small refactor) — one motivation sentence, evidence if visual, one-item test plan. No

## Summary

header — the lead IS the summary.

Follow-up to #144. The original example's inputs looked near-identical, so the diff panels offered no contrast; this rewrite picks an edit-detection scenario where each mode shows a distinct result.

![diff](https://raw.githubusercontent.com/owner/repo/<full-sha>/examples/assets/diff.jpg)

以下层级定义了结构（标题、 checklist 形式）；具体撰写多少内容由

writing-pull-requests

工具决定。

小型变更（文档修改、单一bug修复、依赖版本更新、小型重构）——一句动机说明，如有视觉变更需提供证据，一个测试计划项。无需

## 摘要

标题——开头即为摘要。

跟进#144问题。原示例的输入几乎完全相同，导致对比面板无差异；本次重写选择了一个编辑检测场景，每种模式都能展示不同结果。

![diff](https://raw.githubusercontent.com/owner/repo/<full-sha>/examples/assets/diff.jpg)

Test plan

测试计划

```
uv run python examples/diff.py --save
```
regenerates the asset


The image above is an asset committed in the change itself, so a SHA-pinned raw URL is right on a public repo; on a private repo, and for any ad-hoc screenshot or video, use the media routes in `writing-pull-requests`.

**Medium change** (new function, behavior change, multi-commit feature):

```
uv run python examples/diff.py --save
```
重新生成资源


上方图片是变更中提交的资源，因此在公共仓库中使用SHA固定的原始URL即可；在私有仓库中，或对于任何临时截图/视频，请使用`writing-pull-requests`工具中的媒体路由。

**中型变更**（新增函数、行为变更、多提交功能）：

Summary

摘要

3-5 bullets describing behavior and API surface, not implementation details

![evidence if visual]

3-5个项目符号，描述行为和API接口，而非实现细节

![如有视觉变更请提供证据]

Test plan

测试计划

tests added:
```
tests/...
```
```
make lint
```


**Large change** (cross-cutting refactor, new subsystem) — add `## Why` with real architectural motivation; link the issue or design doc that authorized the work.

添加测试：
```
tests/...
```
运行
```
make lint
```


**大型变更**（跨模块重构、新增子系统）——添加`## 原因`部分，说明实际架构动机；链接授权此项工作的Issue或设计文档。

Test plan calibration

测试计划校准

Each item should describe a check that actually gated the change. Boilerplate dilutes meaningful items.

Docs-only: one item, usually asset regen or render check. Don't pad with
```
make lint
```
/
```
pytest
```
for changes that don't touch lintable / testable code.
Bugfix: the new test that proves the fix + manual repro if applicable.
Feature: tests added + lint + manual verification.

每个项目都应描述实际用于管控变更的检查项。模板化内容会削弱有效信息的价值。

仅文档变更：一个项目，通常是资源重新生成或渲染检查。对于不涉及可检查/可测试代码的变更，无需添加
```
make lint
```
/
```
pytest
```
等内容。
Bug修复：证明修复有效的新测试 + （如适用）手动复现步骤。
功能新增：添加测试 + 代码检查 + 手动验证。

3. Push and create/update

3. 推送并创建/更新PR

Draft vs ready — a draft PR is the native "not ready yet" signal, so the maintainer's "needs my attention" filter is

is:pr is:open draft:false

(no label needed). Pick the default from who is running this skill:

User invoked it directly → open ready. They are vouching the branch is finished; do not add a
```
--draft
```
step they have to undo.
Running autonomously / unsupervised (AFK,
```
/loop
```
, an agent opening its own PR) → open draft (
```
gh pr create --draft
```
). The work is unvetted; the user flips it to ready (
```
gh pr ready <number>
```
) or merges after a look.
An explicit "draft" / "ready" request in the prompt overrides this.

bash

undefined

草稿版 vs 就绪版——草稿PR是原生的"尚未就绪"标识，因此维护者的"需关注"过滤器为

is:pr is:open draft:false

（无需额外标签）。根据调用此工具的对象选择默认模式：

用户直接调用 → 打开就绪版。用户已确认分支已完成；无需添加
```
--draft
```
步骤让用户后续取消。
自动/无人监督运行（用户离开、
```
/loop
```
、Agent自行创建PR）→ 打开草稿版（
```
gh pr create --draft
```
）。工作内容未经过审核；用户可查看后将其切换为就绪版（
```
gh pr ready <number>
```
）或直接合并。
如果提示中明确要求"草稿"/"就绪"，则以此为准。

bash

undefined

Push with tracking

推送并设置跟踪

git push -u origin <branch> --force-with-lease

Create or update ( add --draft per the rule above )

创建或更新PR（根据上述规则添加 --draft 参数）

gh pr create --title "..." --body "..." --label "..." --assignee "..."

If PR already exists:

如果PR已存在：

gh pr edit <number> --title "..." --body "..." --add-label "..." --add-assignee "..."

undefined

gh pr edit <number> --title "..." --body "..." --add-label "..." --add-assignee "..."

undefined

4. Return the PR URL

4. 返回PR链接

Always print the PR URL at the end so the user can click it.

最后务必打印PR链接，方便用户点击访问。

Guidelines

指南

Always use
```
--force-with-lease
```
(not
```
--force
```
) when pushing.
Check if a PR already exists before creating — update it (
```
gh pr edit
```
) instead of failing.
For long PR bodies, write to a tempfile and pass via
```
--body-file
```
to avoid shell quoting issues.

推送时始终使用
```
--force-with-lease
```
（而非
```
--force
```
）。
创建PR前先检查是否已存在对应的PR——若存在则更新（
```
gh pr edit
```
），而非直接失败。
对于较长的PR正文，写入临时文件并通过
```
--body-file
```
参数传递，避免Shell引用问题。