技能使用指南

skill-git-workflow（Git工作流技能）Skill 是什么？如何安装使用？

Git工作流技能（skill-git-workflow）为 AI 任务操作自动生成范围化 Git 提交：任务创建、研究完成、计划制定、阶段推进、实施收尾都有固定消息格式，自动暂存对应文件、默认跳过 CI、按需加 [ci] 触发流水线，并内置敏感文件检查与危险命令防护。本文拆解安装启用步骤、提交范围规则、CI 决策标准与竞品对比，帮你把零散提交变成可追溯的工程记录。

Git工作流技能Skillskill-git-workflow
8 个章节 约 16 分钟阅读 AI 智能生成

Git工作流技能：让 AI 为每一次任务操作自动生成范围精准、格式规范的 Git 提交

  • 一句话定位：这是一个把「任务状态变化」和「Git 提交」自动绑定的技能，AI 在任务创建、研究完成、计划制定、阶段推进、实施收尾时，自动按规则暂存文件并生成标准化提交消息。
  • 范围可控：任务提交只包含 specs/ 下的任务工件，实施提交只包含被修改的源文件，避免一次提交混入无关改动。
  • 格式统一：内置任务操作与系统操作两套提交消息模板，团队成员和 AI 产出的历史记录风格一致，便于追溯与审计。
  • CI 可控：推送事件默认跳过 CI，只有显式添加 [ci] 标记才触发流水线，既能省下流水线额度，又能在关键改动前强制验证。
  • 安全兜底：提交前检查暂存内容、拦截敏感文件，且明确禁止 git push --force、无请求的 git reset --hard、git rebase -i 等危险操作。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

这个技能的中文名是 Git工作流技能，英文名是 skill-git-workflow，技能 ID 为 12880。它要解决的问题非常具体：在使用 AI 协作开发时，AI 会不断产生任务状态变更、研究笔记、实施计划、代码改动等大量中间产物，人工逐个提交既费时又容易出错——要么忘记提交导致改动堆积，要么一次提交塞进十几个不相关文件，要么提交消息五花八门。Git工作流技能就是把这些动作交给 AI 按统一规则完成。

它解决的核心问题：

  1. 提交时机靠人盯——任务状态一变化就需要提交，人容易漏；技能在任务生命周期操作发生时自动激活。
  2. 提交范围靠猜——哪些文件该进这次提交？技能内置了任务提交、实施提交、阶段提交三类范围规则。
  3. 提交消息靠自觉——格式不统一，回溯历史时难以判断某次提交属于哪个任务、哪个阶段。
  4. CI 反复跑——每次推送都触发流水线，浪费资源；技能提供 [ci] 标记做精细控制。

一键安装与启用的通用思路：

AI 技能的安装方式取决于你使用的宿主工具（技能市场、技能库或本地技能目录），本技能详情未提供具体的安装命令与下载地址，请以官方说明为准。通用步骤如下：

  1. 确认安装前提：宿主环境需支持按技能名加载技能（本例为 skill-git-workflow），并具备执行 Git 命令的能力——技能声明了 allowed-tools: Bash(git:*)，即只允许调用 git 开头的命令，这是一个天然的安全边界。
  2. 安装技能：通过宿主工具的技能安装入口搜索技能名或技能 ID（12880），或在技能市场中按名称安装；若使用本地技能目录方式，则将技能目录放入宿主约定的技能目录下。具体路径与命令以官方说明为准。
  3. 启用并授权工具：启用技能，确认 Bash(git:*) 权限已放行，否则技能无法执行暂存与提交动作。
  4. 按需加载上下文：技能通过 @ 引用按需读取上下文文件，例如 @.opencode/context/core/standards/git-safety.md（Git 安全规则与最佳实践）与 @.opencode/context/index.md（完整上下文发现索引），无需一次性把全部规范塞进上下文。
  5. 验证是否生效：让 AI 执行一次任务状态变更（例如新建任务或完成研究），观察是否自动产生一条形如 task {N}: create {title} 或 task {N}: complete research 的提交；也可以直接查看返回结果中是否包含 commit_hash 与 files_committed 字段。若返回 "summary": "No changes to commit"，说明没有变更可提交，属于正常状态而非失败。

该技能的主要功能和特点

  • 任务操作标准化提交：为「创建任务」「完成研究」「创建计划」「完成阶段」「完成任务」「修订计划」等动作预设消息格式，AI 只需填入任务编号、阶段名与版本号。
  • 系统操作标准化提交：覆盖归档任务、错误修复计划、代码审查、状态同步等系统级动作，例如 todo: archive {N} completed tasks、sync: reconcile TODO.md and state.json。
  • 三类提交范围规则：任务特定提交只包含 specs/TODO.md、specs/state.json 与任务目录 specs/{NNN}_{SLUG}/**；实施提交包含被修改的源文件（如 Lean 任务的 Logos/**/*.lean、通用任务的 src/**/*）；阶段提交仅限该阶段变更的文件与带阶段状态的计划。
  • CI 触发精细控制：通过 trigger_ci 参数决定是否在消息末尾附加 [ci]，默认 false 不触发，减少无谓的流水线消耗。
  • CI 决策标准内置：Lean 文件修改、实施完成、CI 配置变更、Mathlib 依赖更新、关键错误修复建议触发 CI；纯文档、研究/规划工件、常规任务管理操作建议跳过。
  • 提交前安全检查：先用 git status 核对暂存文件，检查是否误暂存 .env、凭据等敏感文件，再校验提交消息格式。
  • 危险命令黑名单：从不运行 git push --force、未经显式请求的 git reset --hard、git rebase -i。
  • 结构化返回结果：以 JSON 返回 status、summary、commit_hash、files_committed、message、ci_triggered，便于上层任务流程判断成败。
  • 非阻塞设计：Git 失败不会卡住任务本身——记录失败、继续任务、向用户报告，任务状态照常保留。

和「让 AI 随手 git add . && git commit -m "update"」的普通做法相比，它强在范围边界清晰、消息可机器解析、CI 成本可控、危险动作有护栏。

如何使用该技能？

第 1 步：让技能被触发。 你不需要手动喊「提交」，只要发生以下任一情况，技能即激活：任务状态更改（研究、计划、实施完成）、工件创建、任务生命周期操作发生。

第 2 步：准备提交请求。 技能接收四类信息：operation_type（操作类型）、task_number（任务编号，如不适用可省略）、scope（要包含的文件范围）、message_template（消息模板）。一个典型请求可以这样描述：

「任务 12『实现登录校验』已完成实施，请创建提交，范围包含本次修改的源文件，触发 CI。」

第 3 步：技能执行标准流程。 依次为：接收请求 → 执行 git add {scope} 暂存适当文件 → 格式化消息并添加共同作者 → 执行提交 → 检查退出码并记录结果 → 返回结果。

第 4 步：理解实际执行的命令。 标准提交形如：

git add {files}
git commit -m "$(cat <<'EOF'
{message}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

任务提交则只暂存 specs/：

git add specs/
git commit -m "$(cat <<'EOF'
task {N}: {action}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

第 5 步：读取返回结果。 成功时返回类似：

{
  "status": "completed",
  "summary": "Created commit: task 12: complete implementation",
  "commit_hash": "abc123",
  "files_committed": ["src/auth/login.ts"],
  "message": "task 12: complete implementation [ci]",
  "ci_triggered": true
}

第 6 步：按需处理异常。 若返回 "status": "failed" 且 error 为「Pre-commit hook failed」，正确做法是修复问题后重试，不要使用 --no-verify 绕过钩子；若为 Git 命令失败，按提示检查 git status 后手动解决。

第 7 步：决定是否触发 CI。 需要验证构建时设置 trigger_ci: true，消息末尾会自动追加 [ci]，此时格式为 task {N}: complete implementation [ci]。注意：拉取请求事件、手动 workflow_dispatch 触发、带 [ci] 标记的提交这三种情况，CI 无论如何都会运行。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
Git工作流技能（skill-git-workflow） AI 任务流程中的自动提交代理 任务/系统操作消息模板、三类提交范围规则、[ci] 触发控制、敏感文件检查、危险命令黑名单、结构化 JSON 返回 需宿主工具支持技能加载并放行 Bash(git:*)，安装方式以官方说明为准；触发自动化，无需人工敲命令 AI 协作开发、任务驱动的长周期项目 优势：与任务状态天然联动，范围与 CI 均可控；不足：依赖 AI 宿主环境，纯人工项目用不上
commitizen（交互式提交规范工具） 人工提交规范化 交互式问答生成符合 Conventional Commits 的消息 需 Node.js 环境并全局或项目内安装，需人工逐次触发 团队统一提交消息格式 优势：生态成熟、规范通用；不足：仍需人工操作，不感知任务状态，无法自动决定提交范围
husky + lint-staged（提交钩子方案） 提交前自动化校验 钩子拦截提交、只对暂存文件跑格式化与 lint 需在仓库内初始化并配置钩子脚本 代码质量守门 优势：拦截效果好；不足：管的是「提交质量」而非「提交时机与范围」，不生成业务语义消息
手工 git 命令 + 团队约定 零工具方案 完全依赖开发者自律 零安装 小团队、短周期项目 优势：灵活无依赖；不足：格式漂移严重，AI 参与时极易出现 git add . 式大杂烩提交，历史难追溯

该技能的典型应用场景与实际体验情况

场景一：AI 长任务的分阶段留痕。 一位独立开发者用 AI 推进一个包含「研究 → 计划 → 实施 → 收尾」的长任务。痛点是 AI 一轮对话改十几个文件，人工拆提交要花十几分钟。使用该技能后，完成研究时自动产生 task {N}: complete research，创建计划时自动产生 task {N}: create implementation plan，阶段推进时产生 task {N} phase {P}: {phase_name}，历史一眼可读。体验：几乎零学习成本，触发是自动的；注意阶段提交的范围要明确，否则容易把下一次阶段改动提前带进来。

场景二：Lean 项目的构建验证节奏。 团队使用 Lean 做形式化开发，痛点是改完 .lean 文件忘记触发 CI，合并前才发现构建失败。技能内置的 CI 决策标准把「Lean 文件修改」「Mathlib 依赖更新（lakefile.lean、lake-manifest.json）」「CI 配置变更」列为建议触发项，实施完成时加 [ci] 做最终验证。体验：流水线费用明显下降，因为文档、研究、规划类提交不再触发 CI；需要注意的是团队要统一 trigger_ci 的使用习惯，否则会出现「该验证的没验证」。

场景三：多任务并行的仓库管理。 一位技术负责人同时跟进多个任务，痛点是提交范围混乱，一次提交里混着两个任务的改动，回溯困难。技能的任务特定提交范围锁死为 specs/TODO.md、specs/state.json 与对应任务目录，实施提交只包含源文件，天然实现了「一提交一任务」。体验：范围规则是最大价值点；注意事项是如果任务编号填错，提交会挂到错误的任务签名下，提交前应核对 task_number。

场景四：敏感信息防泄漏。 团队中最常见的失误是 git add . 把 .env 带进仓库。技能的提交前检查会先跑 git status 验证暂存文件，并明确检查是否暂存了 .env 与凭据文件。体验：这是一层低成本高收益的护栏；但它不是密钥扫描器，无法识别内容层面的密钥泄漏，仍需配合仓库级密钥检测。

该技能能为用户带来的价值

  • 把「记得提交」变成「自动提交」：提交时机从人工盯守转为任务生命周期驱动，减少因遗忘导致的巨型提交，回滚时影响面更小。
  • 把「约定」变成「格式」：任务操作与系统操作各有固定消息模板，task {N}: complete research 这类消息可以直接被脚本解析，用于生成任务进度报表或发布说明。
  • 把「CI 全跑」变成「按需跑」：默认跳过、显式标记触发的机制，让每一次流水线运行都有明确目的，长期可节省可观的构建资源与等待时间。
  • 把「危险操作」挡在门外：禁止强推、禁止无请求的硬重置与交互式变基，对刚接触 Git 的新手和放任 AI 执行的开发者都是重要保护。
  • 降低 AI 协作的审计门槛：结构化返回结果里有 commit_hash 与 files_committed，AI 可以据此判断提交是否成功、要不要补救，人类也能快速核对。
  • 长期价值：一个项目的提交历史是最难重建的资产。规范化的提交序列让半年后的你依然能回答「这个功能是在哪个任务、哪个阶段、为什么改的」。

常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？ A：它属于 AI 技能（Skill），安装方式取决于你使用的宿主工具，通常是在技能市场按技能名 skill-git-workflow 或技能 ID 12880 搜索安装，或放入宿主约定的本地技能目录，具体命令与入口以官方说明为准。安装前需确认环境支持技能加载并能执行 git 命令。是否付费、是否有额度限制同样以官方说明为准，本文不做推测。

Q2：它会不会自动提交我不想提交的文件？ A：不会无边界地提交。技能内置了明确的暂存范围规则：任务提交只暂存 specs/ 目录下相关内容，实施提交只包含被修改的源文件，阶段提交只限该阶段的变更文件；并且在提交前会执行 git status 核对暂存内容、检查是否误暂存 .env、凭据等敏感文件。但范围参数由调用方给出，建议在请求中明确 scope。

Q3：为什么我的提交没有触发 CI？ A：因为该技能在推送事件上默认跳过 CI，这是刻意设计。要触发流水线，需要在创建提交时把 trigger_ci 设为 true，消息末尾会自动追加 [ci] 标记。另外，拉取请求事件、手动 workflow_dispatch 触发属于始终运行的情况，与标记无关。

Q4：提交失败了任务会被卡住吗？ A：不会。技能采用非阻塞设计：记录失败、继续任务、向用户报告提交失败，任务状态照常保留。如果失败原因是 pre-commit 钩子报错，正确做法是修复问题后重试，不要用 --no-verify 绕过校验。

Q5：它和 commitizen、husky 这类工具怎么选？ A：三者管的不是同一件事。commitizen 管「消息格式是否规范」，husky 管「提交前代码是否通过校验」，Git工作流技能管「什么时候提交、提交哪些文件、要不要触发 CI」。团队已有 husky 做代码守门时，可以把它当作提交时机与范围的自动化层；如果项目完全由人工开发、不存在 AI 任务流程，那么传统工具组合更合适。若三者同时使用，注意钩子报错与技能重试逻辑的配合，避免重复触发。