Plane 的 create-pull-request 技能：用 Claude Code 技能文件自动化生成标准化 PR 的完整工作流

Plane 仓库在 .claude/skills/ 目录下维护了一组 Claude Code 技能（SKILL.md），其中 create-pull-request 技能定义了"从分支上下文到 PR 创建"的完整自动化流程：以 preview 为默认目标分支，从分支名中提取 Plane 工作项 ID 作为 PR 标题前缀，并依据仓库根目录的 .github/pull_request_template.md 逐节填写 PR 正文。读完本文，你可以完整理解该技能的六步工作流、每条 git/gh 命令的用途、PR 标题与正文的格式规范，以及它与 branch-name 技能在分支命名约定上的配合关系。

技能文件结构与 Frontmatter

技能定义位于 .claude/skills/create-pull-request/SKILL.md，采用标准的 Claude Code 技能格式：YAML frontmatter 加 Markdown 正文。frontmatter 包含三个字段：

字段	值	作用
name	create-pull-request	技能标识，与所在目录同名
description	"Use when creating a pull request for the current branch — gathers branch context, generates a PR description following the repo's pull_request_template.md, and creates the PR with a Plane work item ID prefix in the title."	触发条件描述，供 Agent 判断何时调用该技能
user_invocable	true	允许用户直接显式调用（如输入 /create-pull-request），而不仅由 Agent 自动触发

该技能位于 Plane 的 .claude/skills/ 技能族中，同目录还有 branch-name、release-notes、react-doctor 等技能，各自覆盖分支命名、PR 创建、发布说明生成、React 代码体检等环节，共同构成一套面向 Plane 开发流程的 Agent 工具链。

六步工作流：从上下文采集到 PR 创建

技能正文（# Create PR 一节）把整个流程拆分为 6 个步骤，每一步都有明确的命令与判断规则。

步骤 1：确定目标（base）分支

默认目标分支为 preview，除非用户另行指定。这一点与 release-notes 技能 中记录的 Plane 发布约定一致——功能分支通常汇入 preview/master 体系，PR 的 base 选择直接影响 diff 的基准。

步骤 2：并行采集分支上下文

技能要求以下 6 个上下文采集操作尽量并行执行，一次性拿全判断依据：

命令 / 操作	用途
git status -s	检查是否存在未提交的改动，避免 PR 遗漏工作区内容
git diff <base>...HEAD --stat	查看变更文件统计，确定影响范围
git log <base>...HEAD --oneline	列出分支上全部提交（而非仅最新一条）
git diff <base>...HEAD --no-color	完整 diff，用于理解改动实质；若 diff 过大，优先聚焦最重要的文件
git rev-parse --abbrev-ref --symbolic-full-name @{u}	判断当前分支是否已设置远程跟踪（upstream），决定后续 push 是否需要 -u
读取 .github/pull_request_template.md	从仓库根目录读取 PR 模板，作为正文结构的唯一来源

其中三点值得注意：

• 使用 base...HEAD 三点语法而非 base..HEAD，即 diff 基于两者的共同祖先（merge-base），保证只包含本分支引入的变更；
• git log 明确覆盖分支上所有提交——这直接对应"常见错误"一节中的第一条：只总结最新提交是典型错误；
• 读取 PR 模板而非凭记忆撰写正文，保证 PR 结构与 .github/pull_request_template.md 保持同步，模板变更时无需修改技能本身。

步骤 3：确定工作项（Work Item）ID

Plane 团队使用 Plane 自身作为项目管理工具，PR 标题前缀采用 [工作项ID] 形式。ID 的确定规则：

1. 优先从分支名提取。分支命名约定为 <type>/<work-item-id>-<short-description>，例如：
   • chore/silo-1146-foo → SILO-1146
   • feat/web-1234-x → WEB-1234 注意分支名中 ID 是小写的（silo-1146），作为 PR 标题前缀时需还原为大写形式（SILO-1146）。
2. 分支名中找不到时询问用户，而不是自行编造一个 ID。

这一约定与姊妹技能 branch-name 形成闭环：该技能在创建分支时强制使用 <type>/<work-item-id>-<short-description> 格式，其描述中明确写道"compatible with the create-pr skill's work item ID extraction"（与 create-pr 技能的 ID 提取逻辑保持兼容）。branch-name 技能还给出了一组示例分支名：

fix/silo-1146-relative-config-urls
feat/web-1234-app-tile-visibility
chore/web-2201-bump-eslint
refactor/silo-980-extract-auth-middleware
docs/web-1500-pr-template-update
perf/silo-1310-cache-workspace-lookup

至于 SILO、WEB 等前缀的含义，release-notes 技能 中有更完整的说明：[WEB-XXXX] 是 web/前端产品项，[SILO-XXXX] 对应 Silo（Slack、GitHub、GitLab 等集成）项目，另有 [MOBILE-XXXX]、[API-XXXX] 等。

步骤 4：按模板起草 PR

这是技能的核心产出环节，规则分为标题与正文两部分。

标题格式：

[WORK-ITEM-ID] <type>: <concise summary>

• <type> 反映变更性质：fix、feat、chore、refactor、docs、perf 等，与 branch-name 技能中定义的分支类型枚举保持一致；
• 整体长度控制在 70 字符以内。

技能给出的示例标题：

[SILO-1146] fix: allow relative URLs for configuration_url and improve app tile visibility

正文结构：要求"基于实际 diff 填写模板的每一个小节"（Fill in every section from the PR template based on the actual diff）。模板即 .github/pull_request_template.md，共五个小节，技能的填写要求如下：

模板小节	模板原文注释	技能的填写要求
Description	Provide a detailed description of the changes in this PR	简洁说明 PR 做了什么、为什么做，聚焦 "what" 与 "why" 而非逐行改动；提及重要的实现决策
Type of Change	六个候选复选框：Bug fix / Feature / Improvement / Code refactoring / Performance improvements / Documentation update	勾选与变更匹配的框（可多选）
Screenshots and Media	Add screenshots to help explain your changes, ideally showcasing before and after	保留占位注释 <!-- Add screenshots here -->，截图由用户后续补充
Test Scenarios	Please describe the tests that you ran to verify your changes	给出基于实际改动的具体验证场景（如"进入项目设置页并验证新开关生效"），而非泛泛的通用描述
References	Link related issues if there are any	包含工作项 ID、用户提到的关联 issue，以及对话中引用过的 Sentry issue 链接/ID（如 SENTRY-ABC123）

此外，技能要求在正文末尾追加一行 Claude Code 会话标识（Append a Claude Code session line at the bottom of the body），用于标明该 PR 描述由 Claude Code 会话生成——这是一种常见的 AI 辅助贡献标注实践。

步骤 5：推送并创建 PR

在尽可能并行的前提下执行两件事：

1. 若步骤 2 中发现分支没有 upstream，推送时带上 -u 参数建立跟踪关系：

   git push -u origin <branch>
   

2. 用 GitHub CLI 创建 PR，正文通过 HEREDOC 传入以避免 shell 对反引号、$ 等字符的解析：

   gh pr create --base preview \
     --title "[SILO-1146] fix: allow relative URLs for configuration_url" \
     --body "$(cat <<'EOF'
   ### Description
   ...
   EOF
   )"
   

   单引号包裹的 'EOF' 是关键细节——release-notes 技能 在 gh pr edit --body 场景下也使用了同样的写法，并特别强调"Always use a HEREDOC with single-quoted 'EOF' so backticks/dollars in the notes are preserved"。

步骤 6：返回 PR URL

流程的终点是把 gh pr create 返回的 PR 链接交还给用户，形成闭环。

编写准则与常见错误

技能文档用两节清单约束生成质量，这部分对任何"让 Agent 代写 PR 描述"的实践都有参考价值。

Guidelines（准则）：

• 描述要简洁但信息充分（concise but informative）；
• 列举多项改动时使用要点列表（bullet points）；
• 聚焦用户可见的影响，而非实现细节；
• 不得编造与本次改动无关的测试场景（Don't fabricate test scenarios that aren't relevant to the actual changes）——这条与步骤 4 中"Test Scenarios 必须基于实际改动"相互呼应。

Common Mistakes（常见错误）：

1. 只总结最新一条提交，而漏掉分支上的其他提交——对应步骤 2 中 git log <base>...HEAD 覆盖全部提交的设计；
2. 推送前忘记检查 upstream——对应步骤 2 中 git rev-parse @{u} 检查的设计；
3. 工作项 ID 格式与分支约定不一致（如大小写、位置放错）——对应步骤 3 的提取规则，也是 branch-name 技能 中"Common Mistakes"强调的镜像问题（该技能指出"把 ID 放在末尾而不是 type 之后会破坏提取"）；
4. 把 PR 正文整体包进代码围栏再传给 gh pr create——会导致 GitHub 把正文渲染成代码块而非 Markdown。

该技能在 Plane 仓库中的定位

从源码结构看，Plane 仓库把 PR 流程的多个环节都沉淀成了可版本化的技能文件：

• 创建分支时：branch-name 技能 保证分支名携带可提取的工作项 ID；
• 提交代码前：react-doctor 技能 要求对 React 改动跑 npx react-doctor@latest --verbose --diff 回归体检，分数回退需先修复再提交；
• 开 PR 时：本文介绍的 create-pull-request 技能完成上下文采集、标题规范化、模板化正文与推送创建；
• 发版时：release-notes 技能 从 release PR 的提交列表生成 GitHub Releases 格式的版本说明，并明确排除了 Sync: Enterprise Changes 等同步噪音提交。

值得注意的是，与 create-pull-request 配套的 AGENTS.md 定义了仓库级的命令与代码风格约定（如 pnpm dev、pnpm check、OxLint、MobX store 位于 packages/shared-state 等），Agent 在采集 diff 并撰写"Test Scenarios"时，可参照其中的测试约定（后端 pytest 套件通过 docker-compose-test.yml 运行）给出贴合实际的验证建议。

小结

create-pull-request 技能本质上是一份把"人类撰写 PR"的隐性规范显式化为机器可执行流程的技能文件：它用 git log <base>...HEAD 与 git diff <base>...HEAD 保证不遗漏分支上的任何提交，用 <type>/<work-item-id>-... 分支约定保证工作项 ID 可机械提取，用 preview 默认 base 与 gh pr create + 单引号 HEREDOC 保证推送与创建动作的可复现性，并以上游 PR 模板 .github/pull_request_template.md 作为正文结构的单一事实来源。对维护者而言，"模板放 .github/、流程放 .claude/skills/、二者解耦"的划分方式，使得 PR 格式变更时无需改动技能逻辑，而 Agent 行为调整时也无需触碰模板文件——这对任何希望规范化 AI 辅助贡献流程的开源仓库都是可以直接借鉴的组织方式。