pr-creator

pr-creator

像开发者在 Slack 中发帖一样撰写 PR 描述，而不是让 AI 总结差异。审阅者不了解你的上下文，因此正文要回答差异本身无法说明的问题：为什么要改、改错了会有什么代价，以及你希望他们对哪些方面发表意见。差异则说明改了什么。

• **是：**创建或更新 GitHub PR 的标题、正文、草稿状态和审阅者；为 UI 改动附上视觉素材；并整理提交和审阅路径，让大型差异更易读。
• **不是：**修改差异中的代码或检查其中的缺陷（请使用 tidy）；在 PR 创建后持续关注 CI 和审阅评论（请使用 pr-babysitter）；或发布 npm 版本（请使用 autoship）。

参考文件

文件	阅读时机
references/pr-polish.md	提交中包含 fixup、WIP 或“处理审阅意见”等杂项，差异超过 500 行，或用户要求润色、重组、压缩或拆分 PR 时

工作流

复制此清单以跟踪进度：

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
- [ ] UI change with a video or screenshots? gh pr edit <n> --attach <file> after the final body, then gh pr view <n> --json body

不要先征求用户批准描述；这样做的目的就是提速。用户可以要求重写，届时你再运行 gh pr edit。

规则

1. 标题。 有 Linear ID 时：ABC-123: Add auth flow。没有时：Add auth flow。少于 60 个字符，末尾不加句号。如果仓库会检查 PR 标题格式（.github/workflows/ 中存在 semantic-pull-request 或 commitlint 工作流），则遵循其格式，并将 ID 放在末尾：feat: add auth flow (ABC-123)。无论 ID 在标题中的什么位置，都为其添加 Linear 链接。
2. 正文。 用一段简短文字说明改了什么以及为什么重要。长度视改动而定；一行修复写一行正文即可。
3. 不要编造原因。 如果提示、Linear issue、分支、提交或差异中都没有说明原因，就不要写，别自行杜撰。
4. 仅在确有必要时说明风险和征求意见。 对于迁移、计费、身份验证、权限、不可逆写入、影响范围广或行为变化隐晦的改动，添加一行 Risk:。当差异中仍有待定决策，且审阅者的意见会影响该决策时，添加一行 Input wanted:；明确指出决策，切勿只写“欢迎发表意见”。否则不写。
5. 仅在确有实际测试时说明测试。 只说明实际运行过的测试。绝不使用 Test plan 章节，也不使用复选框。
6. 部分完成。 如果此 PR 未完成 Linear issue，就不要将 ID 放入标题，而应在正文写 Part of ABC-123。Linear 的默认自动化会在 PR 合并时将关联 issue 移至 Done；使用这个不会关闭 issue 的关键词，即可建立关联而不关闭 issue。
7. 仅在用户要求时设置草稿状态和审阅者。 用户说“draft”或“WIP”时使用 --draft；之后用 gh pr ready 将其转为就绪状态，用 gh pr ready --undo 将其改回草稿状态。仅对用户指定的人使用 --reviewer alice,org/team；CODEOWNERS 已会自动请求所有者审阅。
8. 有用内容写完就停。 工具链的 attribution 设置负责 PR 页脚（Generated with Claude Code、会话链接）。绝不要手动添加，也不要删除工具链或仓库策略应用附加的页脚。页脚上方的所有内容都由此技能撰写；其中一段式正文会替代工具链默认的 Summary 和 Test plan 章节。

反面模式：绝不要这样写

• 叙述 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 章节
• 复述差异内容的项目符号列表
• 需要审阅者通读才能找到重点的正文：如果第一句话没有点明要点，那么这段文字就是总结，而不是描述

示例

功能（ABC-123 是真实的 Linear ID）

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.

Input wanted: the 15-minute idle timeout is a guess; if product has a number, I'll use it.

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

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.

杂项（无 Linear ID，差异之外没有其他缘由）

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.

前两个条目写明了提交中真正的缘由，到此为止。第一个条目中，Input wanted: 单独占一行是有道理的，因为超时是评审者可以更改的决定；第二个条目中，Risk: 单独占一行是有道理的，因为差异涉及账单写入，而且只有在确实运行了重放测试时才提及测试。第三个条目没有更深层的缘由，所以不装作有。

模板

对于多个模板，GitHub 会读取 .github/、仓库根目录或 docs/ 中第一个匹配 pull_request_template.md（不区分大小写）的文件；也会读取上述任一目录中的 PULL_REQUEST_TEMPLATE/ 目录。gh pr create --body 会完全跳过模板，因此，如果存在模板，请先阅读，并按其格式撰写正文：保留其标题，每项用一两句话作答，并将一段式描述放在第一个标题下。不要添加模板未要求的内容。

创建 PR

使用文件工具将完整正文写入临时文件，然后通过 --body-file 传入文件路径。示例使用 /tmp/pr-body.md；执行时请选择与任务相关的临时路径。

尚无 PR：创建

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

规则 7 适用时，在此处添加 --draft 或 --reviewer。仅当目标分支不是默认分支时，才添加 --base。

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

gh pr edit 会完全覆盖标题和正文，因此请草拟完整替换内容，而不是补丁。相同的规则和反模式仍然适用。

# 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

UI 更改：附上视觉材料

视觉材料为可选项。当差异改变用户看到的内容（标记、样式、文案或资源），且你有一段较短的 MP4 或 WebM 视频、一张图片，或一组更改前后对比图时，请附上它们，让评审者无需检出分支就能看到更改。选择最能展示效果的形式：有动态效果或流程时用视频，静态更改用单张图片，视觉差异用更改前后对比图。正文中的本地文件路径不算附件。

gh pr edit 42 --attach ./demo.mp4   # after the last body rewrite

# Before and after: label them in the body, where `**Before**` sits above
# `![Before](./before.png)`, and attach on the same call so gh swaps each
# local path for its uploaded URL. A `#Before` suffix is only alt text.
gh pr edit 42 --body-file /tmp/pr-body.md --attach ./before.png --attach ./after.png

gh pr view 42 --json body   # always, even after a non-zero exit

• 顺序。 gh pr edit --body-file 会替换正文，包括已上传的 URL。完成最后一次重写后再附加，或者在最终调用 --body-file 时同时传入 --attach（gh 会将正文引用的本地路径替换为已上传的 URL，并附加其他附件）。之后若再次重写，请将回读内容中的已上传 URL 复制到新的正文文件中。
• 回读。 对于每个文件，正文都必须包含已上传的 /user-attachments/assets/... URL（主机为 github.com，或数据驻留 GHE Cloud 中的 SUBDOMAIN.ghe.com）：视频使用单独一行的裸 URL，GitHub 会将其渲染为播放器；图片使用 ![alt](...)。如果部分上传失败，gh 仍会使用已上传成功的附件编辑 PR，并以非零状态码退出，因此重试前请先读取正文：只重新附加缺失的内容，并报告哪些附件已成功上传。

注意事项

• 在没有上游分支的分支上运行 gh pr create：在 TTY 中会卡在“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 会原样复制提交消息，而这正是此技能旨在避免的变更日志正文。
• 如果正文或提交消息通过 shell heredoc 而不是 --body-file 传递，请给分隔符加引号（<<'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，填错会移动其他人的问题。
• 普通的 git diff 不会显示已提交的变更。请使用 PR 实际基分支进行三点差异比较；不要想当然地使用 main，尤其是在堆叠式 PR 中。
• --attach 需要 gh 2.99.0 或更高版本（gh --version）、用户令牌（安装令牌 ghs_ 无法上传）、仓库推送权限（可以创建贡献者从 fork 发起的 PR，但无法为其添加附件），以及 github.com 或 GHE Cloud；GHES 不支持附件。缺少其中任何一项时，请说明无法附加视觉素材及其所在位置，而不要在正文中链接本地路径。
• 首次推送前应先调整提交结构。在已有未关闭 PR 的情况下强制推送重写后的分支，会将现有行内评论标记为“outdated”，导致审阅者失去评论串。

相关技能

• tidy：创建 PR 前运行，以检查差异中的错误并修复；此技能只会编辑 PR 及其提交。
• pr-babysitter：创建 PR 后交接给它，以监控 CI、冲突和审阅评论。
• autoship：npm 发布流水线（changesets、版本 PR、发布）；如果没有发布相关上下文，“ship it”会转到此处。

仅用于维护：evals/evals.json 包含此技能变更的回归场景；用户任务期间不会加载该文件。