Gemini CLI pr-creator 技能深度解析：模板合规的 Pull Request 八步安全工作流

本文基于 Gemini CLI 仓库内置的 pr-creator 技能 展开，逐条拆解其「分支保护 → 模板合规 → preflight 预检 → gh CLI 创建 PR」的完整工作流，并结合仓库中真实的 PR 模板、package.json 脚本定义与技能加载源码（docs/cli/skills.md、skillLoader.ts）解释该技能的设计原理，帮助读者掌握一套可复用的「AI Agent 安全提 PR」实践方案，并能照此模式为自己仓库编写类似的流程型技能。

一、pr-creator：一个以「流程约束」为核心的 Agent 技能

pr-creator 是 Gemini CLI 仓库放在工作区技能目录（workspace skills）下的一个 Agent Skill，位于 .gemini/skills/pr-creator/SKILL.md。与存放持久化背景知识的 GEMINI.md 不同，技能（Skill）代表「按需加载的专项能力」——平时只向模型暴露元数据，匹配到任务时才注入完整指令。

该技能的 YAML frontmatter 只有两个字段，却承担了「技能何时被触发」的全部职责：

---
name: pr-creator
description:
  Use this skill when asked to create a pull request (PR). It ensures all PRs
  follow the repository's established templates and standards.
---

description 是激活条件：当用户请求「帮我创建一个 PR」这类意图时，Gemini 会识别到与描述匹配，调用 activate_skill 工具激活该技能，随后 SKILL.md 的正文和目录结构被注入对话上下文。根据 docs/cli/skills.md 描述的技能生命周期，这一过程分为五步：Discovery（会话启动时扫描各层目录，把技能名称和描述注入系统提示）→ Activation（模型调用 activate_skill）→ Consent（UI 展示确认提示，列出技能名称、用途及将获得的目录访问权限）→ Injection（批准后将 SKILL.md 正文与目录结构加入历史，并把技能目录加入允许访问的文件路径）→ Execution（模型按技能中的程序化指引执行）。

底层实现可在 packages/core/src/skills/skillLoader.ts 与 skillManager.ts 中找到。技能按优先级从低到高分为四个发现层级：内置技能、扩展技能、用户技能（~/.gemini/skills/）、工作区技能（.gemini/skills/）。pr-creator 属于工作区技能，随代码仓库入库、与团队共享——这正是「让 AI 遵守团队 PR 规范」能落地为可版本化资产的原因。

二、八步工作流总览

SKILL.md 的核心是一份 8 步有序工作流，覆盖从「确认所在分支」到「用 gh CLI 创建 PR」的全过程。其设计重心并非「如何写一个 PR 描述」，而是把两类最容易出错的环节显式标注为 CRITICAL：

1. 分支管理（CRITICAL：绝不在 main 上工作）
2. 提交变更（先 git status 确认无未提交内容）
3. 定位模板（在 .github/ 下查找 PR 模板）
4. 读取模板
5. 起草描述（严格遵循模板结构）
6. Preflight 检查（npm run preflight）
7. 推送分支（CRITICAL SAFETY RAIL：推送前二次确认分支不是 main）
8. 创建 PR（gh pr create + --body-file）

下面按原文顺序逐步展开，并补充仓库中的实际证据。

三、步骤 1–2：分支保护与提交规范

3.1 分支管理：双重确认，绝不在 main 上工作

技能的第一条就是「关键安全约束」：

git branch --show-current

如果当前分支是 main，必须创建并切换到一个语义化新分支：

git checkout -b <new-branch-name>

3.2 提交变更：先检查，再提交，且提交信息遵循约定式

# 检查是否存在未暂存或未提交的变更
git status
# 若存在变更：暂存并提交（绝不允许直接向 main 提交）
git add .
git commit -m "type(scope): description"

这里的 type(scope): description 即 Conventional Commits 格式。仓库根目录的 GEMINI.md 也明确声明项目采用 Conventional Commits 标准，因此 PR 标题、提交信息在整个仓库层面是统一约定，而非技能单方面的要求。

四、步骤 3–5：模板定位、读取与描述起草

4.1 模板定位：候选路径与多模板决策

技能要求按以下顺序在仓库中查找 PR 模板：

• .github/pull_request_template.md
• .github/PULL_REQUEST_TEMPLATE.md
• 若存在多份模板（例如 .github/PULL_REQUEST_TEMPLATE/ 目录下的 bug_fix.md 与 feature.md），应询问用户使用哪一份，或根据上下文选择最匹配的一份。

在本仓库中，实际生效的是 .github/pull_request_template.md，单文件形式。

4.2 真实模板结构：五个固定章节

该模板定义了五个必须保留的章节，这也是技能第 5 步「起草描述」需要逐项遵循的结构：

章节	模板要求的填写要点
Summary	简明描述 PR 改了什么、为什么改，聚焦影响与紧迫性
Details	补充背景与设计决策，简短但完整
Related Issues	用关键词自动关闭 issue（Closes #123、Fixes #456）；若仅为部分修复或相关引用，则不带关键词（Related to #123）
How to Validate	列出验证步骤：命令、预期结果、边界情况
Pre-Merge Checklist	合并前勾选清单，含文档/测试/破坏性变更确认，以及跨平台验证矩阵（MacOS / Windows / Linux × npm run / npx / Docker，MacOS 另含 Podman、Seatbelt）

4.3 起草描述的三条规则

技能对「按模板写描述」给出了可操作的细则：

• Headings（标题）：保留模板中的全部标题，不得删减章节；
• Checklists（清单）：逐项审视——已完成项标记 [x]；不适用项保持未勾选 [ ]（优先保留未勾选以维持透明度，而非删除）；
• Content（内容）：用清晰、简洁的语言总结变更；
• Related Issues：链接被修复或相关的 issue（如 Fixes #123）。

这四条细则配合模板内嵌的 HTML 注释提示（模板中每个章节下都有 <!-- ... --> 注释说明填写口径），共同保证了不同作者、不同会话生成的 PR 描述在结构上完全一致。

五、步骤 6：preflight 检查——把「构建 + 质量门禁」前置

npm run preflight

技能要求：若任何检查失败，必须先修复问题，再进入创建 PR 环节。这一步的意义在于把质量门禁从事后（CI 红灯、评审返工）移到事前（本地一次性通过），减少无效推送。

对照 package.json 中该脚本的真实定义，preflight 是一条串联的完整门禁链：

"preflight": "npm run clean && npm ci && npm run format && npm run build && npm run lint:ci && npm run typecheck && npm run test:ci"

拆解后依次是：

1. clean —— 清理产物（scripts/clean.js）；
2. npm ci —— 按锁文件干净安装依赖，保证环境可复现；
3. format —— Prettier 全仓库格式化（prettier --experimental-cli --write .）；
4. build —— 执行 node scripts/build.js 构建；
5. lint:ci —— 即 lint:all，CI 口径的 lint；
6. typecheck —— 对所有 workspace 及 evals、integration-tests、memory-tests 的 tsconfig 执行 tsc -b；
7. test:ci —— 各 workspace 的 CI 测试、脚本测试与 sea-launch 测试。

这也解释了为何技能把 preflight 放在「推送之前」：它覆盖了格式化、构建、lint、类型与测试全部维度，能作为创建 PR 的准入门槛。

六、步骤 7–8：安全推送与用 gh CLI 创建 PR

6.1 推送分支：推送前的第二次 main 校验

这是全文第二次强调分支安全，措辞为 CRITICAL SAFETY RAIL（关键安全护栏）：

# 确认当前分支不是 main
git branch --show-current
# 非交互式推送
git push -u origin HEAD

git push -u origin HEAD 的写法值得注意：它推送「当前 HEAD 所在分支」而非硬编码分支名，避免脚本化执行时因分支名变化推送错分支；配合 -u 建立上游跟踪，后续可直接 git push。

6.2 创建 PR：临时文件规避 shell 转义问题

# 1. 将起草好的描述写入临时文件
# 2. 使用 --body-file 标志创建 PR
gh pr create --title "type(scope): succinct description" --body-file <temp_file_path>
# 3. 删除临时文件
rm <temp_file_path>

这里体现了两个实战技巧：

• --body-file 而非 --body：多行 Markdown 直接内嵌进命令行会被 shell 引号、反引号、$ 等字符干扰；先落盘为临时文件再引用，完全绕开转义问题。
• 标题沿用 Conventional Commits：技能给出的示例为 feat(ui): add new button、fix(core): resolve crash，与第二节提交信息、仓库 GEMINI.md 的约定一脉相承——提交、分支标题、PR 标题三处格式统一，便于 changelog 自动化与 commit 追溯。

七、设计原则：安全、合规、完整、准确

SKILL.md 末尾的四条原则（Principles）是整套工作流的价值排序，值得单独提炼：

原则	含义	在工作流中的落点
Safety First	绝不推送 main，优先级最高	步骤 1 与步骤 7 各设一道 main 校验
Compliance	绝不绕过 PR 模板，模板存在即有其原因	步骤 3–5 强制定位、读取并逐节遵循模板
Completeness	填写所有相关章节	步骤 5 的 Headings/Content 规则
Accuracy	没做的事不勾选项	步骤 5 的 Checklist 规则（保持 [ ] 而非删除）

这四条原则的共同点是针对 LLM 的失败模式做防御：模型容易「顺手在 main 上提交」、容易「凭记忆跳过模板」、容易「为了好看把没做的项也勾上」——技能把每条都可能发生的偏差都写成了显式禁令，这是「给 Agent 写规程」与「给人写文档」的关键差异。

八、源码视角：技能如何被发现与管理

从源码结构看，技能发现逻辑集中在 packages/core/src/skills/ 目录（skillLoader.ts 负责加载与解析 frontmatter，skillManager.ts 管理启用状态），并有对应的测试 skillLoader.test.ts、skillManager.test.ts、skillManagerAlias.test.ts 验证加载与 .agents/skills/ 别名解析行为。

对使用者而言，日常的验证手段有：

• 交互会话中 /skills list 查看已发现技能（/skills disable|enable 管理启停，/skills reload 重新扫描）；
• 终端 gemini skills list --all、gemini skills install <repo> --consent 等子命令管理技能安装。

完整说明见 docs/cli/skills.md 与 docs/cli/creating-skills.md。

九、在 PR 生命周期中的位置：与同类技能的配合

pr-creator 只是该仓库 PR 流程自动化的一环，仓库在同一技能目录下还提供了覆盖 PR 全生命周期的配套技能，可以按阶段理解它们的分工：

阶段	技能	职责
创建	pr-creator	分支保护 + 模板合规 + preflight + 创建 PR（本文主角）
异步评审	async-pr-review	后台运行 preflight 检查与 AI 代码评审，用临时 git worktree 隔离
处理评审意见	pr-address-comments	抓取 PR 评论并逐条处理
代码评审	code-reviewer	本地代码评审视角

其中 async-pr-review/SKILL.md 中再次复用了 npm run preflight 作为后台检查入口，印证了 preflight 在该仓库 PR 流程中的枢纽地位：无论交互式创建还是异步评审，门禁口径一致。

十、如何把这套模式迁移到自己的仓库

pr-creator 的骨架高度可复用。若要在自己的项目中实现「模板合规的 PR 创建技能」，可以按以下要点落地：

1. 目录与元数据：在仓库内建 .gemini/skills/pr-creator/SKILL.md（或对应工具的技能目录），frontmatter 中 name 保持与目录名一致，description 写清触发条件（如 "Use this skill when asked to create a pull request"），它决定技能能否被正确激活；
2. 绑定真实模板：技能里的模板路径（.github/pull_request_template.md / .github/PULL_REQUEST_TEMPLATE.md）应替换为你仓库实际存在的路径，并把「多模板时如何抉择」写成显式规则；
3. 绑定真实门禁：把 preflight 步骤替换为你仓库的等效质量门禁脚本，并保证脚本名与 package.json（或 Makefile 等）中的实际定义一致——本文示例中 preflight 的实际链是 clean → npm ci → format → build → lint:ci → typecheck → test:ci；
4. 保留双重 main 校验：在「开始工作」和「推送」两个节点各放一次 git branch --show-current 检查，这是成本最低、收益最高的安全设计；
5. 坚持 --body-file：凡是多行 Markdown 作为 CLI 参数传入的场景（gh pr create、gh issue create 等），一律先写临时文件再引用；
6. 写清四条原则：把 Safety First / Compliance / Completeness / Accuracy 这类防御性禁令显式写进技能正文，而非依赖模型默认行为。

小结

pr-creator 技能 的价值不在于罗列 git 命令，而在于它示范了「如何把团队的 PR 规范编码为 Agent 可执行的流程资产」：以 PR 模板 为合规基准、以 preflight 门禁链 为质量准入门槛、以「双重 main 校验 + 临时文件传参」为安全细节、以四条防御性原则为兜底。读懂它，等于拿到了编写同类流程型技能（issue 创建、发布流程、代码评审）的参考范式。