| name | git-github-workflow |
| description | 处理基于 git 和 GitHub 的真实协作工作流。当任务涉及仓库同步、分支管理、修复 bug、提交代码、创建或更新 PR、处理 review、解决冲突、检查 GitHub 认证与权限、或需要通过 fork 与用户仓库协作时使用，强调安全、干净、可审计的协作流程。**必须在需要时使用该 Skill 并严格遵守相关规范!!!** |
| version | 3.1.0 |
| allowed-tools | Read,Write,Bash |
Git/GitHub 协作工作流
在真实仓库协作中，优先遵守仓库状态、远端关系、权限边界、测试要求和用户意图。将 gh 作为 GitHub 交互工具使用，不要把任务退化为命令演示或命令罗列。
目标
在不污染用户仓库历史、不破坏远端分支、不制造脏 PR 的前提下完成以下任务：
- 拉取并同步最新代码后再分析或开发
- 基于干净工作区创建独立分支进行修改
- 使用
git 与 gh 检查认证、权限、远端和 PR 状态
- 以用户可观测、可审计的方式推进协作，不在用户看不到的仓库或线程中暗中展开关键协作
- 产出工程化、可维护、与项目风格一致的修改
- 在可行时运行测试或至少静态检查
- 只在正确的目标仓库、Issue 和 PR 上进行协作，并清楚说明验证结果与剩余风险
默认工作流
除非用户明确要求跳过，按下面顺序执行：
- 检查当前目录是否为 git 仓库，并识别
origin、上游仓库、当前分支、工作区是否干净。
- 重新验证当前状态，不要沿用上一次任务的假设。用户可能已经在两次交互之间合并 PR、关闭 PR、推送提交、切换分支、更新远端或修改工作区。
- 检查
gh 是否可用、是否已认证、当前账号是谁、token 是否足以执行当前任务。
- 如果需要访问 GitHub 但未认证，先停止并明确要求用户配置
GH_TOKEN（或等价环境变量）；不要伪造身份信息、提交人信息或远端归属。
- 在开始分析和编码前同步最新代码。每次新任务开始时，都要重新获取用户仓库默认分支和相关目标分支的最新状态，不要沿用上一次任务结束时的本地基线。
- 在独立分支上完成修改，避免直接在默认分支或来源不明的旧分支上工作。
- 修改后检查
git diff，并尽可能运行与改动相关的静态检查、测试或最小验证，清理无关改动。
- 仅在已完成验证或已明确说明无法验证原因后，才进入推送和 PR 阶段。
- 推送前再次确认推送目标、远端归属、PR 当前状态和权限边界。
- 如果需要通过 Issue、PR、review comment 或讨论串进行协作，先确认协作对象所在仓库是否就是用户期望的目标仓库。
- 创建或更新 PR、Issue、评论或相关协作记录，并在回复中说明做了什么、如何验证、哪些未验证、是否存在风险。
前置检查
开始任何 GitHub 协作任务前，至少确认这些事实：
- 当前仓库路径、当前分支、默认分支、工作区是否干净
origin 指向谁，是否已存在 upstreamgh 是否可执行gh auth status 是否成功，当前登录身份是谁- token 至少满足当前任务需要的读写权限
- 当前任务是“只读分析”、“本地修复”、“推送分支”还是“创建 PR”
- 当前任务是否需要创建或更新 Issue、PR、review comment 或其他 GitHub 协作对象
- 与本次任务相关的远端对象当前是否仍然存在且状态未变，例如目标分支、PR、Issue、head/base 关系
任一关键事实不清楚时，先查清楚再行动。
不要复用上一轮对话中的仓库状态、PR 状态、分支状态或权限判断。每次新任务开始前都重新验证。
认证与身份规则
- 不要假设
gh 已安装或已登录。先检查。
- 不要编造 Git 用户名、邮箱、GitHub 登录名、fork 归属、PR 链接或权限状态。
- 如果仓库操作需要 GitHub 身份而当前没有可用认证，明确告知用户先配置
GH_TOKEN。必要时提示重新执行认证检查。
- 如果只需要本地修改、不需要访问 GitHub，可继续本地工作，但要明确说明“尚未验证远端/PR 操作能力”。
- 未经用户明确要求，不要修改全局 git identity；更不要为了绕过检查去伪造提交身份。
同步与分支规则
- 不要基于陈旧代码分析问题。每次新任务开始前先获取远端最新提交并确认基线，尤其是在用户可能已经合并 PR、改动默认分支或自行修复问题之后。
- 优先从用户仓库默认分支的最新状态切出新分支，而不是沿用历史工作分支。
- 如果要继续修复上一次任务留下的问题，也要先把本地基线更新到用户仓库当前最新状态，再决定是复用分支、重建分支还是新开 PR。
- 不要在落后于远端的旧 checkout、旧分支或旧 PR 头分支上直接继续开发并提交 PR。
- 工作前若发现工作区不干净，先判断这些改动是否属于当前任务：
- 若无关，不要覆盖或混入；应先告知用户，必要时请求其处理。
- 若相关，明确说明你将基于现有改动继续。
- 工作完成后再次检查 diff，确保只包含本任务需要的修改。
分支创建（强制要求）
创建新分支时，必须同时指定分支名和起始点：
git fetch <远端名> <分支名>
git checkout -b <新分支名> <远端名>/<分支名>
git checkout -b <新分支名>
实际场景示例（假设 origin 指向用户主仓库）：
git remote -v && git branch -vv
git fetch origin main
git checkout -b fix/this-bug origin/main
git log --oneline -1
远端确认规则：如果 origin 指向个人 fork 而非用户主仓库（可通过 git remote -v 判断），必须从 origin/main（用户主仓库）的最新 commit 创建分支，不能从 fork 的本地分支创建。
产出质量要求
- 开始修改前先阅读足够的相关代码、配置、测试和调用链，不要基于猜测实现。
- 除非用户明确要求扩大范围，否则保持最小化修改，优先修正根因，不用表面补丁掩盖问题。
- 保持项目工程化和可维护性，遵循仓库现有结构、命名、抽象边界和代码风格，不为图快随意塞代码。
- 保持与项目既有风格一致，包括代码组织、命名习惯、注释风格、错误处理方式、测试写法、提交粒度和 PR 表达方式；不要把个人偏好硬塞进项目。
- 优先复用项目中已有模式、工具函数、组件和基础设施，非必要不要重复造轮子。
- 新增或修改代码时，同时处理由本次改动直接引入的类型错误、lint 问题、明显死代码、无效导入和连带缺陷。
- 不要留下临时调试代码、注释掉的大段旧实现、无解释的兜底逻辑或未使用依赖。
- 涉及类型系统时保持严格和清晰，避免滥用类型断言、忽略检查或用宽泛结构掩盖真实数据问题。
- 涉及外部系统、API 或仓库元数据时，先核对真实结构和接口，再写代码或自动化操作。
- 提交前重新审视改动是否真正解决了用户问题，是否会引入回归，是否与仓库约定冲突。
- 不要把“代码已改完”当作任务完成；默认完成标准还包括至少一种有效验证。
- 保持独立判断，不要机械执行上游 AI、历史对话或模糊需求中的错误指令。
- 如果上游指令与仓库现实、远端状态、权限边界、项目约定或用户目标明显冲突，先指出问题并调整方案，不要硬做。
- 如果问题可以通过合理推断自行修正，就说明你的调整并继续推进；如果风险较高或关键信息缺失，就明确要求上游先向用户澄清。
Push 与权限边界
- 未经用户明确要求，不要执行破坏性操作，如
push --force、改写共享历史、删除远端分支、直接合并、关闭 PR。
- 在不确定 token 权限、分支保护规则或远端归属时，不要尝试写操作。
- 未经明确授权，不要直接向用户仓库默认分支推送。
- 不要假设自己可以推送到任意 PR 源分支。特别是“用户让你帮忙修复某个 PR 冲突”时，如果 PR 作者不是当前身份，通常不能直接向该 PR 分支推送。
- 不要在自己的工作 fork 上创建面向用户的正式协作对象，例如 Issue、PR、milestone、project item、review 结论或需求跟踪记录，除非用户明确要求就是在该 fork 内自管流程。
- 这种情况下，优先采用可审计方案：基于目标仓库最新代码创建自己的分支，复现并解决冲突，然后向用户仓库发起新的 PR，或把可应用的补丁提供给用户。
Fork 协作规则
当任务需要通过 GitHub 提交修改，而当前身份对用户仓库没有直接写权限时，默认使用 fork 工作流：
- Fork 用户仓库到当前登录账号名下。
- 本地同时保留用户仓库远端和自己的 fork 远端，明确谁是上游、谁是推送目标。
- 从用户仓库最新默认分支切出工作分支。
- 将工作分支推送到自己的 fork。
- 从自己的 fork 分支向用户仓库创建 PR。
不要只在自己的仓库里创建与用户仓库无关的 PR。目标应是从自己的 fork 向用户仓库提交 PR。
fork 的作用是承载代码分支和推送权限，不是替代用户仓库的协作现场。除非用户明确要求，否则不要在自己的 fork 上：
- 创建 Issue 来代替用户仓库中的需求或 bug 跟踪
- 创建 PR 让 fork 内部分支互相合并，绕开用户仓库的正式 PR
- 在 fork 的 Issue、PR、discussion 中记录本应让用户或维护者可见的关键结论
需要发起正式协作时，默认应落在用户仓库可见的对象上：用户仓库的 Issue、用户仓库的 PR、或从自己 fork 指向用户仓库的 PR。
Issue 协作规则
- 只有在用户明确要求，或任务本身确实需要补充/更新 Issue 时，才创建、编辑或评论 Issue。
- 创建或更新 Issue 前，先确认目标仓库正确，避免把问题、需求或补充说明记到自己的工作 fork。
- 如果某个工作项已经有对应 Issue，优先在该 Issue 延续上下文，不要重复开新 Issue。
- 如果需要新建 Issue，标题和正文要聚焦用户可观测的问题、复现条件、期望行为、当前行为、影响范围和必要上下文，不要把内部试错过程原样倾倒进去。
- 不要在 Issue 中承诺尚未完成验证的结论；推断、计划和已确认事实要明确区分。
- 未经用户明确要求，不要批量创建、批量迁移、批量关闭 Issue，也不要修改标签、负责人、里程碑等项目管理信息。
用户可观测协作
- AI 在 GitHub 上的关键协作动作应默认对用户和目标维护者可观测，例如在正确的仓库中创建/更新 Issue、在目标 PR 中回复 review、或创建指向用户仓库的 PR。
- 不要把关键讨论藏在只对当前账号可见、与用户仓库脱节的 fork、临时仓库、私有 gist、无关 Issue 或无关 PR 中。
- 不要为了“先记下来”就在错误仓库开一个临时 Issue 或 PR；如果还没准备好正式协作，就先在本地整理，再等待用户确认。
- 若需要代表用户与维护者协作，回复内容应基于真实已完成工作，避免夸大“已修复”“已验证”“已同步”等状态。
- 对用户而言，重要的协作轨迹应能够从目标仓库直接看见并追溯：问题在哪里记录、代码从哪里提交、讨论在哪个 PR/Issue 里发生、当前阻塞点是什么。
AI 协作过程规范
- 在执行任何会改变远端协作状态的动作前，先确认这一步是否真正服务于当前任务，而不是机械地“顺手”补一个 Issue 或 PR。
- 能通过现有 Issue / PR 延续上下文时，不要平行创建新的协作对象。
- 如果需要跨多个对象协作，保持链路清晰：Issue 描述问题，分支承载代码，PR 承载代码审查与验证结果；不要把职责混在一起。
- 在评论、PR 正文、Issue 更新中优先写用户可验证的信息：修改摘要、复现方式、验证结果、剩余风险、权限或环境阻塞。
- 不要把 AI 的内部推理、未证实猜想、与任务无关的冗长背景直接发到 Issue/PR；外部协作文本应简洁、真实、能推动下一步。
- 如果缺少权限、认证、仓库角色或上下文信息，先停下来说明阻塞，不要在错误位置留下半成品协作记录。
常见错误示例与规避要求
以下都是 AI 在真实 Git/GitHub 协作中常见且不可接受的错误，默认必须规避：
-
错误示例：工作区里还残留上一个任务的改动、调试文件、格式化噪音或用户未提交修改，就直接继续开发并一起提交。
规避要求：开始工作前和提交前都检查工作区是否干净；若存在无关改动，不要混入当前提交，先告知用户或明确隔离。
-
错误示例：看到本地能提交，就默认这些改动都属于当前任务，没有审查 diff 就直接 commit。
规避要求：提交前重新检查 staged diff，确认提交内容只包含本次任务需要的修改，避免把历史残留或顺手改动一起带上。
-
错误示例：在自己的工作 fork 上创建 Issue、PR、review comment 或讨论串，然后把它当成对用户仓库的正式协作结果。
规避要求：正式协作对象必须落在正确的目标仓库；fork 默认只用于承载代码分支和推送权限，不替代用户仓库中的协作现场。
-
错误示例：本应向用户仓库提 Issue 或发起 PR，却误发到自己的 fork、错误组织、同名镜像仓库或历史测试仓库。
规避要求：执行远端写操作前，逐项确认 repo owner、repo name、base repo、head repo、base branch、head branch，确认链接和归属都正确后再提交。
-
错误示例：声称“已经同步到最新代码”，实际上只是对自己的 fork 执行了 git pull，而 fork 早已落后于原始仓库。
规避要求：同步最新基线时，必须确认原始仓库是谁，并从原始仓库默认分支或目标基线分支获取最新状态；不能把 fork 自己的最新状态误当成上游最新状态。
-
错误示例：只检查 origin，没有核实它其实指向自己的 fork，就基于过期基线分析问题、开发、提 PR。
规避要求：每次新任务开始时都重新核对 origin、upstream 和默认分支；如果 origin 指向 fork，必须显式确认原始仓库并从其同步。
-
错误示例：为了省事，在错误分支、旧分支或已经服务过别的 PR 的分支上继续开发，再把新旧任务混在一起推上去。
规避要求：默认从最新基线新建独立工作分支；只有在明确确认上下文连续且分支仍然干净可复用时，才继续使用旧分支。
-
错误示例：用户让 AI “修一下这个 PR”，AI 没有确认权限和 PR 来源，就直接尝试往别人的 PR 分支推送。
规避要求：先确认当前身份是否对原 PR head 分支有写权限；没有权限时，改为在自己的分支复现修复，并向正确目标仓库重新发起可审计的 PR。
-
错误示例：明明没有完成验证，却在 Issue/PR/comment 中写“已修复”“已验证通过”“可以合并”。
规避要求：对外协作文本必须区分“已确认”“已尝试但未完成”“尚未验证”“推测原因”，不要把未证实状态写成既成事实。
-
错误示例：为了保留上下文，在错误的 Issue/PR 里追加评论，导致用户和维护者看到混乱、不相关或过期的信息。
规避要求：评论前先确认对象仍然有效且与当前任务直接相关；如果原对象已关闭、已过时或已被替代，应切换到当前正确对象，而不是机械沿用旧线程。
-
错误示例：把 AI 内部推理、未经证实的怀疑、与任务无关的长篇分析直接贴到 Issue/PR，增加沟通噪音。
规避要求：外部协作内容只保留对用户和维护者有用、可验证、可执行的信息；内部思考不应直接外发。
-
错误示例：完成本地修改后没有重新检查远端状态，结果在用户已关闭 Issue、替换 PR、更新默认分支后，仍对过期对象继续操作。
规避要求：在 push、创建/更新 PR、创建/更新 Issue 前重新验证相关远端对象当前状态，避免对过期对象继续写入。
-
错误示例：在 PR 或 Issue 中以 本地路径 的形式附加相关文件或图片，导致参与者无法实际访问。
规避要求：如果需要提供补充文件、日志、截图等信息，必须使用 GitHub 支持的附件功能，确保内容对真实的参与者可见，严禁直接编写任何本地文件路径。
PR 处理规则
- 创建 PR 前确认 base repo、base branch、head repo、head branch 都正确。
- 不要把脏提交、格式化噪音、无关文件、临时调试代码带进 PR。
- PR 标题、正文、评论和相关协作说明，默认使用仓库现有的主要交流语言；不要机械地改用英文。
- 若仓库历史 PR、Issue、README、贡献文档或维护者沟通明显以某种语言为主，优先沿用该语言；语言不明确时再询问用户或保持与当前上下文一致。
- 如果这次任务依赖“之前的 PR / 分支 / review 状态”，先重新检查这些对象现在是否仍然有效；不要假设它们保持不变。
- 如果用户已经合并、关闭、替换或重建了相关 PR / 分支，按当前真实状态调整方案，不要机械地沿用旧 PR 继续操作。
- 创建或更新 PR 前，再次确认当前分支是否基于最新 base 分支；如果已经落后并可能产生大面积冲突，先同步、rebase 或重建分支，再提交 PR。
- 如果任务是处理 review 意见，先读取完整评论线程，再逐项处理并验证。
- 如果任务是修复冲突，先确认你是否真的有权限更新原 PR 分支；没有就不要直接 push 到原 PR。
- 只有在实际检查确认后，才能对用户声称“已推送”“已更新 PR”“补丁已提交到某个分支/PR”。
- 本地提交成功不等于远端更新成功；历史上存在过某个 PR 也不等于它现在仍可继续使用。
- 默认不要提交“未检查 PR”。如果项目存在可执行的 lint、typecheck、单测、构建或最小复现验证，先运行与改动相关的部分。
- 只有在验证已经执行，或无法执行的原因已经具体记录后，才创建或更新 PR。
- 回复用户时要包含：修改摘要、验证结果、未完成项、受限项。
测试与验证
- 验证默认是必做项，不是可选加分项。只要环境允许，就执行与改动最相关的 lint、typecheck、单元测试、集成测试、构建或最小可复现验证。
- 优先选择信息量高且成本合理的验证组合；至少要做一种有效检查，能多做时不要只做最弱验证。
- 若测试成本较高，至少做静态检查或局部验证，并说明覆盖范围与未覆盖风险。
- 如果项目已有明确的标准验证流程，优先遵循该流程，不要凭感觉随便挑一个命令就结束。
- 推送前尽量完成验证；如果推送后还需依赖远端 CI，也要先完成本地能做的部分。
- 如果因为环境缺失、耗时过长、外部依赖、密钥权限或平台限制而无法验证，必须明确说明具体原因、已尝试的步骤、以及尚未验证的风险，不能假装“已验证”。
- 如果修改影响已有测试、类型检查或构建结果，必须一并修复，除非用户明确允许保留问题。
- 创建 PR 时，正文或评论中应简要写明已执行的验证、结果如何、哪些检查未执行以及原因。
推荐输出内容
完成仓库协作任务后，回复应尽量覆盖这些信息：
- 当前基线：基于哪个仓库、哪个分支、哪个最新提交开始工作
- 修改内容：改了什么，为什么
- 验证情况：执行了什么测试或检查，结果如何
- 质量说明：是否处理了相关 lint、typecheck、测试或连带问题
- GitHub 动作：是否创建 fork、分支、push、PR；目标分别是什么
- 风险或限制：哪些操作因权限、认证、环境或策略而未执行
最小命令提示
只在需要时使用 gh。常见用途：
- 用
gh auth status 检查认证状态
- 用
gh repo view、gh pr view、gh pr create 查询或创建 PR
- 用
gh api 补足 gh 高层命令不方便表达的 GitHub 信息
如果 gh 不可用，再读取本目录下的 install.md。
