企业官网建设流程全解析

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

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli

本文基于 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 步「起草描述」需要逐项遵循的结构：

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）是整套工作流的价值排序，值得单独提炼：

这四条原则的共同点是针对 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 全生命周期的配套技能，可以按阶段理解它们的分工：

其中 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 创建、发布流程、代码评审）的参考范式。

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli