用途
commit 是一个用于创建 git 提交的 Agent 技能。它把改动文件提交为一次 git commit,提交信息尽量精简,可选带 JIRA 单号前缀。触发方式包括:/commit、commit this、commit my changes。
主要能力
收集上下文
该技能会运行其捆绑脚本,建议在单次 Bash 调用中执行(技能被调用时会显示其基准目录):
bash <skill-base-dir>/scripts/gather-context.sh
该脚本会输出:分支名、从分支名提取的 JIRA 单号候选、git status、最近 5 次提交(用于匹配仓库的提交风格),以及已暂存/未暂存的 diff(超过 400 行会被截断,可通过设置 MAX_DIFF_LINES 调高)。
脚本把 JIRA 单号视为候选而非事实:如果明显不是工单引用则应拒绝(例如 feature/uc-1-gtfs-import 会得到 UC-1,这是用例编号而非工单)。若单号为 none 或被拒绝,会在当前对话最近约 10 条用户消息中扫描 [A-Z]+-\d+ 形式的提及,并使用最近的一个。若仍无结果,则不带前缀继续。
决定暂存内容
查看 git status。如果 $ARGUMENTS 列出了具体路径,只暂存这些路径;否则根据对话上下文暂存明确属于当前任务的文件。不暂存无关改动(notebook 重跑、.gitignore 修改、设置文件等),除非用户明确要求包含,并应把这些无关改动指出来。禁止使用 git add -A 或 git add .,必须按显式路径暂存。
起草提交信息
硬性规则:
- 首行总长度不超过 100 字符,含 JIRA 前缀。
- 格式:若找到单号则为
BRO-XX <简短的祈使句摘要>,否则仅为<简短的祈使句摘要>。 - 使用祈使语气(“Add”“Fix”“Refactor”),结尾不加句号。
- 除非改动从 diff 看确实不明显,或带有未来读者需要的约束(变通方案、刻意省略、后续事项),否则不写正文。不确定时省略正文。
- 若确实需要正文:主题行后空一行,然后写一段紧凑文字或 2–3 条简短要点。不要标题、不要 co-author 尾注、不要营销文案。
提交前确认
通过 AskUserQuestion 询问用户是提交还是取消。该对话框必须自包含——不能依赖工具调用之前打印的文本可见:
- 在 Commit 选项的 preview 字段中放入完整的起草提交信息。
- 在问题文本中列出将要暂存的文件,以及刻意不纳入的文件(附一行理由)。
- 不设单独的“edit”选项。若用户选择 Commit 并附带说明,则按说明微调信息后直接提交,不再询问。若用户通过“Other”作答,则视为重写指示:修改后再次确认。
- 用户未批准前不要提交。
执行提交
获得批准后:
git add <显式路径>git commit -m "$(cat <<'EOF' ... EOF)"—— 始终通过 heredoc 传递信息,以便多行正文正确格式化。- 运行 git status 并报告新的 HEAD 短 SHA 与摘要。
- 若提交因钩子被拒,进入“处理提交钩子失败”流程。
处理提交钩子失败
当 git commit 因 pre-commit 或 commit-msg 钩子失败时,不要放弃,也不要绕过。先分析:
- 阅读完整钩子输出,确定实际原因(格式化器、linter、类型检查、测试、密钥扫描、信息策略等)。
- 再次运行 git status 与 git diff —— 许多钩子(prettier、black、ruff、eslint --fix、import 排序工具)会就地修复文件并仅以失败提示需要重新暂存。
然后把失败分类:
琐碎——无需询问直接修复
指不可能改变行为或含义的机械性改动:
- 空白:行尾空白、缺少文件末尾换行、行尾符规范化、制表符与空格
- 格式化器施加的代码格式(prettier、black、gofmt、rustfmt 等)
- 自动修复工具完成的 import 排序 / 删除未使用 import
- 钩子已就地修改、只需重新暂存的文件
对于这些,应用修复(或仅重新暂存钩子修改过的文件——仅限属于本次提交的文件),以同一信息重试 git commit,并简要报告钩子改动了什么。
实质性——先询问
指任何需要判断或真实代码改动的情况:
- 需要手动改代码的 lint 或类型错误
- 失败的测试
- 密钥/凭据检测发现
- commit-msg 策略拒绝(用户已批准该确切信息——通过 AskUserQuestion 确认调整后的信息,新信息放在确认选项的 preview 中)
对于这些,用 1–3 行总结失败,说明拟采取的修复,并通过 AskUserQuestion 询问是修复、不包含这些改动提交(例如在合理情况下取消暂存问题文件),还是取消。仅在批准后应用修复,然后重试提交。
硬性规则:
- 绝不传
--no-verify。 - 绝不 amend —— 以全新 git commit 重试(失败的尝试未产生任何提交)。
- 若经过 2 次修复尝试后钩子仍失败,停止,展示剩余错误输出,交由用户决定。
参数
$ARGUMENTS 可包含要暂存的显式文件路径,或提交信息的额外上下文。若为空,则从对话中推断。
使用方式
以 /commit、commit this、commit my changes 等形式触发。技能不接受子代理(subagent)。
适用场景与限制
适用于在对话式开发过程中把当前任务的改动提交为一次 git commit,并希望提交信息精简、可选带 JIRA 前缀的场景。限制包括:不使用 git add -A/git add .,需按显式路径暂存;不允许 --no-verify;不允许 amend;遇到需要判断的钩子失败必须先征得用户同意。