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 repositorys established templates and standards. ---description是激活条件当用户请求「帮我创建一个 PR」这类意图时Gemini 会识别到与描述匹配调用activate_skill工具激活该技能随后SKILL.md的正文和目录结构被注入对话上下文。根据 docs/cli/skills.md 描述的技能生命周期这一过程分为五步Discovery会话启动时扫描各层目录把技能名称和描述注入系统提示→Activation模型调用activate_skill→ConsentUI 展示确认提示列出技能名称、用途及将获得的目录访问权限→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分支管理CRITICAL绝不在main上工作提交变更先git status确认无未提交内容定位模板在.github/下查找 PR 模板读取模板起草描述严格遵循模板结构Preflight 检查npm run preflight推送分支CRITICAL SAFETY RAIL推送前二次确认分支不是main创建 PRgh pr create--body-file下面按原文顺序逐步展开并补充仓库中的实际证据。三、步骤 1–2分支保护与提交规范3.1 分支管理双重确认绝不在 main 上工作技能的第一条就是「关键安全约束」git branch --show-current如果当前分支是main必须创建并切换到一个语义化新分支git checkout -b new-branch-name3.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用关键词自动关闭 issueCloses #123、Fixes #456若仅为部分修复或相关引用则不带关键词Related to #123How to Validate列出验证步骤命令、预期结果、边界情况Pre-Merge Checklist合并前勾选清单含文档/测试/破坏性变更确认以及跨平台验证矩阵MacOS / Windows / Linux × npm run / npx / DockerMacOS 另含 Podman、Seatbelt4.3 起草描述的三条规则技能对「按模板写描述」给出了可操作的细则Headings标题保留模板中的全部标题不得删减章节Checklists清单逐项审视——已完成项标记[x]不适用项保持未勾选[ ]优先保留未勾选以维持透明度而非删除Content内容用清晰、简洁的语言总结变更Related Issues链接被修复或相关的 issue如Fixes #123。这四条细则配合模板内嵌的 HTML 注释提示模板中每个章节下都有!-- ... --注释说明填写口径共同保证了不同作者、不同会话生成的 PR 描述在结构上完全一致。五、步骤 6preflight 检查——把「构建 质量门禁」前置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拆解后依次是clean—— 清理产物scripts/clean.jsnpm ci—— 按锁文件干净安装依赖保证环境可复现format—— Prettier 全仓库格式化prettier --experimental-cli --write .build—— 执行node scripts/build.js构建lint:ci—— 即lint:allCI 口径的 linttypecheck—— 对所有 workspace 及evals、integration-tests、memory-tests的 tsconfig 执行tsc -btest:ci—— 各 workspace 的 CI 测试、脚本测试与 sea-launch 测试。这也解释了为何技能把 preflight 放在「推送之前」它覆盖了格式化、构建、lint、类型与测试全部维度能作为创建 PR 的准入门槛。六、步骤 7–8安全推送与用 gh CLI 创建 PR6.1 推送分支推送前的第二次 main 校验这是全文第二次强调分支安全措辞为CRITICAL SAFETY RAIL关键安全护栏# 确认当前分支不是 main git branch --show-current # 非交互式推送 git push -u origin HEADgit 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负责加载与解析 frontmatterskillManager.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 创建技能」可以按以下要点落地目录与元数据在仓库内建.gemini/skills/pr-creator/SKILL.md或对应工具的技能目录frontmatter 中name保持与目录名一致description写清触发条件如 Use this skill when asked to create a pull request它决定技能能否被正确激活绑定真实模板技能里的模板路径.github/pull_request_template.md/.github/PULL_REQUEST_TEMPLATE.md应替换为你仓库实际存在的路径并把「多模板时如何抉择」写成显式规则绑定真实门禁把 preflight 步骤替换为你仓库的等效质量门禁脚本并保证脚本名与package.json或 Makefile 等中的实际定义一致——本文示例中 preflight 的实际链是clean → npm ci → format → build → lint:ci → typecheck → test:ci保留双重 main 校验在「开始工作」和「推送」两个节点各放一次git branch --show-current检查这是成本最低、收益最高的安全设计坚持--body-file凡是多行 Markdown 作为 CLI 参数传入的场景gh pr create、gh issue create等一律先写临时文件再引用写清四条原则把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考