commit-work

commit-work skill 概览

commit-work skill 是一个高度聚焦的工作流，用来把凌乱的 working tree 整理成可审查、可落地的 Git commits。它特别适合那些希望把最容易被草草带过的环节做好的人：先确认到底改了什么、把不相关的修改拆开、只暂存正确的 hunks，并写出一条清晰的 Conventional Commit message，既说明改了什么，也说明为什么要改。

commit-work 的设计目标是什么

commit-work 不是一份通用 Git 教程。它真正要做的是帮助 agent 在日常开发里产出更安全、更干净的 commits。这个 skill 围绕四个结果展开：

• 只包含原本就打算提交的改动
• 把互不相关的工作拆成独立 commits
• 提交前精确检查已暂存的 diff
• 写出有信息量的 Conventional Commit message

所以当你的分支里混杂了多类修改、同一文件里有局部变更、夹杂格式化噪音、测试更新，或者你还不太信任当前 commit message 时，它尤其有价值。

哪些人适合安装 commit-work skill

commit-work skill 最适合已经在使用 Git、但希望 commit 质量更稳定一致的开发者。尤其适合：

• 在大型仓库或高频变动仓库中工作的开发者
• 团队明确要求使用 Conventional Commits 的场景
• 经常习惯“一把梭一个大 commit”，但想改善 commit 边界的人
• AI 辅助编码流程中代码生成很快、但 commit 阶段需要认真复查的场景

如果你主要想解决的是分支策略、merge conflict 处理或发布自动化，那这个 skill 就偏窄了。

为什么 commit-work 比泛泛的“帮我写个 commit”提示更好

泛用提示通常会直接跳到写 message。commit-work 补上了中间最关键的一段：先检查、再划分边界、再 patch-stage、再审阅 staged diff，最后才写 message。之所以重要，是因为大多数 commit 问题本质上不是措辞问题，而是暂存范围错了。

它的核心差异不在于花哨自动化，而在于工作流纪律。

在采用 commit-work 前，最该关注什么

对大多数人来说，判断是否值得采用，问题其实很直接：它到底能不能减少坏 commit？如果你的痛点是下面这些，答案通常是能：

• 不相关的改动经常被打包到一起
• debug 代码或敏感信息会不小心混进去
• commit message 很空泛
• 不确定什么时候该拆成多个 commits

如果你的 repo 改动一直都很小，而且天然隔离得很干净，那这个 skill 的价值会低一些。

如何使用 commit-work skill

commit-work 的安装上下文

如果你的 AI client 支持 GitHub-hosted skills，可以从 softaworks/agent-toolkit 安装 commit-work。常见安装方式是：

npx skills add softaworks/agent-toolkit --skill commit-work

如果你的环境不支持直接安装 skill，那就直接阅读源码文件，并手动照着里面的工作流来：

• skills/commit-work/SKILL.md
• skills/commit-work/README.md
• skills/commit-work/references/commit-message-template.md

使用 commit-work skill 前，先看这些文件

如果你想快速评估，建议按这个顺序看：

1. SKILL.md — 实际执行时用的操作清单
2. references/commit-message-template.md — 期望的 message 结构
3. README.md — 更完整的定位说明和触发示例

比起把整个仓库从头翻到尾，这条阅读路径更快让你抓住真实用法。

commit-work 需要你提供哪些输入

要让 commit-work usage 发挥得更好，最好一开始就把几个关键决策说清楚：

• 你是想要一个 commit，还是多个 commits
• 是否必须使用 Conventional Commits
• 团队规则，比如 subject 最大长度、scope 是否必填
• agent 是否可以直接 stage 和 commit，还是只能给出命令与 message 建议

如果你没有明确指定拆分策略，这个 skill 默认会偏向更稳妥的做法：当改动互不相关时，拆成多个较小 commits。

commit-work 实际遵循的工作流

这个 skill 的工作流很简单，但很有效：

1. 用 git status 和 git diff 检查 working tree
2. 决定 commit 边界
3. 只暂存下一个逻辑上完整的 commit，最好用 git add -p
4. 用 git diff --cached 复查已暂存改动
5. 总结改了什么、为什么改
6. 写一条 Conventional Commit message
7. 运行相关检查
8. 重复以上步骤，直到 working tree 清空

这也是为什么 commit-work for Git Workflows 很实用：它同时改善 commit 内容和 commit hygiene。

如何把一个模糊目标改写成高质量的 commit-work 提示词

弱提示：

• “Commit my changes.”

强提示：

• “Use commit-work. Inspect the current diff, split unrelated changes into separate commits, use Conventional Commits with scope api, and show me the proposed commit boundaries before committing.”

更强的提示：

• “Use commit-work on the current branch. I expect at least two commits if tests and production code changed separately. Use Conventional Commits, keep subjects under 72 chars, and flag any debug code, secrets, or formatting-only churn before staging.”

差别在于，后者给的是决策标准，而不只是一个最终动作。

什么时候该要一个 commit，什么时候该拆成多个 commits

当整个 diff 只服务于一个目的，而且 reviewer 也应该把它当作一次完整变更来理解时，就适合一个 commit。出现下面这些模式时，更适合多个 commits：

• refactor 和行为变更混在一起
• tests 和生产代码改动混在一起
• 依赖升级和代码修改混在一起
• 格式化噪音和逻辑修改混在一起
• frontend 和 backend 改动可以独立审查

这是 commit-work guide 里最有价值的部分之一。

为什么 patch staging 是 commit-work usage 的核心

这个 skill 强烈偏向 patch staging，因为混合修改文件在真实项目里非常常见。git add -p 能让 agent 或用户只暂存属于下一个 commit 的那些 hunks。这比 message 是否写得漂亮更重要。一个范围划错的 commit，就算 message 再完美，依然是个坏 commit。

skill 里提到的相关恢复命令也很实用：

• git restore --staged -p
• git restore --staged <path>

commit-work 如何处理 commit messages

仓库里提供了一个简单的 message template：

• 用 Conventional Commits 形式写 header
• 用简短正文说明改了什么
• 用简短正文说明为什么这么改

好的结构大致像这样：

<type>(<scope>): <summary>

然后在 body 里解释行为变化和改动意图，而不是堆实现细节。这个 skill 也提到了 breaking change 的处理方式：使用 !，或添加 BREAKING CHANGE: footer。

最终提交前应该跑哪些检查

真正 commit 之前，要复查 staged diff，并做一轮 sanity check，重点看：

• 有没有 secrets 或 tokens
• 有没有误提交的 debug logging
• 有没有不相关的格式化噪音
• 是否缺少测试，或与本次改动相关的检查未通过

这是一个很关键的采用点：只有当你愿意让 commit-work install 在最后一公里稍微“慢下来”，去拦住错误，它才真正值回票价。

在 agent 场景里使用 commit-work 的最佳工作方式

一个很实用的模式是：

1. 先让 agent 检查改动并提出边界方案
2. 你来批准或调整拆分计划
3. 再让它为每个 commit 起草 message
4. 对每个 staged commit 复查 git diff --cached
5. 然后让它执行 commit，或者你自己复制最终命令

这种 human-in-the-loop 的方式，既能保持输出质量，也依然很省时间。

commit-work skill 常见问题

commit-work skill 适合新手吗？

适合，前提是你已经理解 Git 的基础概念，比如 staging 和 commit。commit-work skill 提供的是一套可重复执行的检查清单和更稳妥的命令选择，但它并不会从零把整个 Git 都教一遍。

commit-work 必须使用 Conventional Commits 吗？

从源码设计来看，默认是把 Conventional Commits 当成必需项。如果你的团队用的是别的规范，调用这个 skill 时要明确说出来。否则，默认输出会是 Conventional Commit 格式。

commit-work 真的能把我的工作拆成多个 commits 吗？

可以，这本来就是它存在的主要理由之一。这个 skill 明确就是为“判断边界、选择性暂存、重复执行直到 working tree 干净”而设计的。

什么情况下不该用 commit-work？

遇到下面这些情况，就可以跳过 commit-work：

• 你需要的是 branching 或 rebasing 帮助，而不是 commit 帮助
• 变更非常小，而且已经天然隔离
• 你的环境不允许 agent 检查 diff 或做选择性暂存
• 团队的 commit 流程高度定制，已经超出这个 skill 的覆盖范围

这些情况下，直接走一套 Git 命令往往更快。

commit-work 和“只让我写个 commit message”到底有什么区别？

只写 commit message 的提示，默认假设 staged 内容本来就是对的。而 commit-work usage 从更早的环节就开始介入：它会先检查 working tree、划分边界、审查 staged diff，然后才进入 message 编写。

commit-work 对审查标准严格的团队有用吗？

有，而且通常更有用。特别是在 reviewer 很在意“小而清晰的逻辑 commits”、可读的历史记录，以及 message 是否能解释意图的团队里，这套工作流纪律价值最大。

如何改进 commit-work skill 的使用效果

提前给 commit-work 更明确的约束

想让 commit-work 结果更好，最快的方法就是尽早把约束说清楚：

• 偏好的 commit scopes
• subject 长度限制
• tests 是否需要单独拆开
• 纯格式化修改是否必须独立成 commit
• agent 可以直接 commit，还是只能提案

如果不提供这些，skill 依然能工作，但它做出的边界判断不一定符合你们团队的习惯。

在 staging 之前，先让它提出 commit 边界方案

一个很强的提示模式是：

• “Use commit-work to inspect the diff and propose commit boundaries first. Do not stage yet.”

这样做能尽早暴露最大的质量问题。因为一旦开始 staging，人通常就不太愿意再回头重想拆分是否合理。

提供会直接影响 message 质量的仓库上下文

如果 agent 知道功能区域或业务意图，commit body 的质量通常会明显提升。特别有帮助的上下文包括：

• ticket 或 issue 的目标
• 这次修改是在修 bug、降风险，还是为某个功能铺路
• 对用户可见的影响
• 是否存在 breaking behavior

这些信息能帮助 skill 解释“为什么会有这次改动”，而不只是罗列改了哪些文件。

留意 commit-work 常见的失败模式

commit-work 仍然可能出问题，最常见的方式包括：

• 把“看起来相关”但其实可以独立审查的修改合并到一起
• 把格式化噪音和逻辑变更一起暂存
• Conventional Commit header 写对了，但 body 很空
• 因为 message “看起来不错”，就跳过 staged diff 审查

如果你遇到其中任何一种，最好从边界划分那一步重新跑一遍工作流。

用更强的提示词改进 commit-work 输出

不要只说：

• “Use commit-work and commit this.”

可以改成：

• “Use commit-work. Inspect unstaged and staged diffs, isolate formatting-only edits into their own commit if present, use scope ui, and show the final staged diff and message for approval before commit.”

这样的提示能同时提升安全性和 reviewer 体验。

不要整份照收，先基于第一版继续迭代

高质量的后续请求可以是：

• “Split commit 1 into refactor and behavior change.”
• “Rewrite the subject to be more specific about the user-visible effect.”
• “Remove implementation details from the body and focus on intent.”
• “Check whether test updates should be committed separately.”

这是改进 commit-work for Git Workflows 的最高杠杆做法：把第一版输出当成提案，而不是最终答案。