git commit skill

SKILL.md

---
name: git-commit
description: Use when the user explicitly asks to prepare, review, or create a Git commit, including "提交", "提交代码", "帮我提交", "commit", "git commit", "确认提交", or requests a commit message.
---

# Git Commit

基于仓库规则和全部未提交改动生成 Conventional Commit 计划。核心原则是：**先按业务意图形成可独立审查、可独立回滚的原子变更，再用该组的主要意图确定 type。**

## Hard Gate

Skill 首次被调用时只执行准备阶段：读取、分析、分组并展示提交消息。完成展示后必须停止，等待用户确认。

- 准备阶段不得执行 `git add`、`git commit`、`git reset`、`git restore` 或其他写操作。
- 只有当前对话中已经展示过完整提交计划，且用户随后明确回复“确认提交”“按方案提交”等确认表达，才能进入执行阶段。
- “直接提交”出现在首次调用中时仍先展示计划；它不能跳过确认门禁。
- 如果没有可核对的当前计划，“确认提交”只触发重新准备，不直接提交。

## Workflow

### 1. Validate Repository State

先确认仓库根目录、当前分支和 Git 操作状态。检查是否存在未完成的 merge、rebase、cherry-pick、revert 或冲突；存在时停止并说明，不能生成可执行提交计划。

收集全部非忽略改动，而不是只看暂存区：

```bash
git rev-parse --show-toplevel
git status --short --branch
git status --porcelain=v1 -z
git diff --cached --name-status
git diff --name-status
git ls-files --others --exclude-standard
```

随后读取：

- staged 文件的完整文本 diff；
- unstaged 文件的完整文本 diff；
- untracked 文本文件的内容；
- 删除、重命名、类型变化、子模块和冲突状态；
- 二进制、大文件和敏感文件的路径与元数据，不在输出中暴露其内容。

如果 staged、unstaged、untracked 都为空，报告“没有可提交的改动”并停止。不得使用 `git diff HEAD~1` 代替当前改动。

### 2. Read Repository Rules

读取与改动文件适用的仓库规则，优先级如下：

1. 用户本次明确要求；
2. 适用的 `AGENTS.md`、`CLAUDE.md`；
3. `.github/COMMIT_CONVENTION.md`、`CONTRIBUTING.md`、README 中的提交约定；
4. `.commitlintrc*`、`commitlint.config.*`、`package.json` 中的 commitlint 配置；
5. `git config --get commit.template` 指向的模板和相关 commit hook；
6. 最近 20 条非 merge 提交：`git log --no-merges -20 --pretty=format:%s`；
7. 本 Skill 的默认 Conventional Commits 规则。

报告实际采用了哪些规则来源。仓库规则不能覆盖确认门禁和敏感文件保护。

### 3. Account for Every Changed Path

建立完整改动清单。按去重后的仓库相对路径计数：同一路径同时包含 staged 和 unstaged 内容时只计一次；rename 作为一个改动条目记录旧、新路径。每个改动条目必须且只能出现在以下一个位置：

- 某个原子提交组；
- 明确排除清单；
- 待用户决定清单。

完成分组前核对：

```text
检测到的改动路径数 = 已归组路径数 + 排除路径数 + 待决定路径数
```

如果等式不成立、路径重复归组、untracked 文件尚未检查或存在无法读取的内容，不得声称计划完成。

### 4. Group by Business Intent

先判断每项改动解决的业务问题或交付目标，再形成原子组：

- 同一功能的实现、类型定义、测试、mock、文档、迁移、配置和国际化资源放在同一组。
- 缺陷修复与证明该缺陷的回归测试放在同一组。
- 无关功能、独立重构、依赖升级、纯格式化或工具链调整拆成不同组。
- 同为 `feat` 或同为 `fix` 不代表属于同一组；业务意图不同仍要拆分。
- 文件类型只是证据，不能主导分组。不得因为文件是 `*.spec.*` 或 `*.md` 就把它从所属功能组拆走。
- 一个文件包含多个无法安全分离的业务意图时，列入“待用户决定”；不得自行使用交互式 hunk staging 猜测边界。

每个原子组应满足：有一个清晰意图，可以独立说明、独立审查，并能安全地独立回滚。

### 5. Choose Type From the Primary Intent

先形成原子组，再选择 type。项目约定优先；没有约定时使用：

| Primary intent | Type |
|---|---|
| 增加或扩展用户可用能力 | `feat` |
| 修复错误行为 | `fix` |
| 只调整内部结构且不改变外部行为 | `refactor` |
| 主要改善性能 | `perf` |
| 只新增或修改测试 | `test` |
| 只修改文档 | `docs` |
| 只修改格式且不改变语义 | `style` |
| 构建系统、构建依赖或打包 | `build` |
| CI/CD 配置 | `ci` |
| 其他维护工作 | `chore` |
| 回退既有提交 | `revert` |

不要把含义不明确的组自动降级为 `chore`；说明歧义并等待用户决定。

Scope 遵循项目历史和 commitlint 规则；否则选择最能表示业务模块的简短名称。跨多个无共同模块的改动省略 scope。

### 6. Construct the Message

格式：

```text
<type>[optional scope][optional !]: <subject>

[optional body]

[optional footer]
```

默认规则：

- type 始终使用小写英文；
- 中文 subject 使用简洁动宾结构，英文 subject 使用 imperative mood；
- subject 不加句号，默认不超过 72 个字符；
- body 说明这组改动做了什么、为什么需要，避免机械复述文件清单；
- 简单改动允许省略 body；
- footer 使用机器可读格式，如 `Refs #123`、`Fixes #456`；
- breaking change 使用 `!` 和 `BREAKING CHANGE: ...`，并在计划中醒目标记风险。

消息语言优先遵循仓库规则，其次参考最近非 merge 提交；无法判断时默认中文。

### 7. Present the Plan and Stop

按以下结构展示，不输出依赖特定 shell 的 Bash HEREDOC：

```text
提交计划

仓库：<name>
分支：<branch>
规则来源：<files/config/history>

提交组 1：<业务意图>
文件：
- <status> <path>

Commit message:
<完整消息>

分组原因：<为什么这些文件构成一个原子变更>

风险或待决定项：<无，或具体说明>

覆盖核对：
- 检测到：N
- 已归组：N
- 排除：N
- 待决定：N

回复“确认提交”后执行；也可以要求调整分组或消息。
```

存在多个组时逐组展示，并说明建议提交顺序。展示完成后停止，不执行任何 Git 写操作。

## Execute After Confirmation

收到有效确认后：

1. 重新执行仓库状态和全部改动检查。
2. 将当前路径、状态和 diff 与已确认计划逐项比较。
3. 只要出现新增、删除、内容变化、暂存状态变化或规则变化，旧确认立即失效；重新生成计划并再次等待确认。
4. 记录执行前的 staged 路径和 staged diff 快照，并标明它们属于哪个计划组。
5. 如果当前 index 的全部内容只属于一个计划组，优先提交该组；按组使用 `git add -A -- <exact-paths>` 精确暂存，不使用 `git add .`。rename 必须同时包含旧、新路径。
6. 已暂存与未暂存内容共存于同一文件时，确保计划包含整份文件；否则停止并请用户决定，不能意外扩大提交范围。
7. 每组提交前重新检查当前组的 staged diff 和整个 index：
   - index 不含其他组内容时，才可使用普通 `git commit`；
   - index 同时包含其他组内容时，禁止普通 `git commit`，使用 `git commit --only -- <current-group-exact-paths>` 隔离当前组；
   - 如果精确 pathspec 不能安全表示当前组，停止并请用户决定，不得通过 reset、restore 或交互式 staging 猜测处理。
8. 使用适合当前 shell 的安全多行输入提交消息；PowerShell 不得生成 Bash HEREDOC。需要跨 shell 时优先使用 `git commit -F -` 配合当前 shell 的标准输入方式。
9. 每次提交后验证退出码、commit hash 和实际文件清单；如果使用 `--only`，还要比较其余 staged diff 与提交前快照，确认其他组的暂存内容没有丢失或改变。
10. 验证通过后再继续下一组；最终报告每个 commit hash、消息、文件，以及剩余未提交改动。

如果某组失败，停止后续提交并报告已经成功的提交和当前仓库状态；不得自动 amend、reset 或回滚。

## Safety

- 敏感路径或内容（如 `.env*`、credentials、secrets、`*.pem`、`*.key`、令牌、证书）默认排除；只有用户明确点名包含后才可暂存。
- 大型或未知二进制文件必须在计划中标出大小并等待明确确认。
- 不输出检测到的秘密值。
- 不使用 `--no-verify`，除非用户明确要求并已获准。
- 不 amend、不 force push，不修改或删除用户未授权的改动。
- Commit hook 修改工作区或提交失败时立即停止并报告，不自动修复或重试。

## Completion Criteria

准备阶段只有在以下条件全部满足时才完成：

- 仓库规则已读取并报告来源；
- staged、unstaged、untracked 等全部路径均已检查；
- 每个路径恰好归入一个组、排除项或待决定项；
- 原子组按业务意图形成，type 只表示主要意图；
- 每组完整 commit message 已展示；
- 尚未执行任何 Git 写操作；
- 已明确等待用户确认。

执行阶段只有在每个成功提交都完成 hash/文件验证，并报告剩余工作区状态后才完成。

## Example

以下文件共同交付“用户登录”能力：

```text
src/auth/login.ts
tests/auth/login.spec.ts
docs/auth.md
```

它们应形成一个原子组，而不是拆成 `feat`、`test`、`docs` 三个提交：

```text
feat(auth): 增加用户登录能力

实现登录认证及回归测试，并补充使用说明。
```