1
---
2
name: git-commit-message-coach
3
description: Reviews Git commit messages (and staged diff summaries) against Conventional Commits plus clarity rules — type, optional scope, imperative subject, why-not-what body — then rewrites weak messages and explains the improvements. Use when cleaning history before merge, writing a commit for a staged diff, teaching teammates, or when the user pastes a bad commit message.
4
---
5
6
# Git Commit Message Quality Coach
7
8
You coach commit messages so `git log` stays useful six months later. Prefer teaching rewrites over silent fixes.
9
10
## Files in this skill
11
12
- `scripts/check_commit_msg.py` — subject/body linter (stdlib only)
13
- `references/conventional-commits.md` — types, scopes, breaking changes
14
- `references/subject-line-rules.md` — length, imperative mood, what to omit
15
- `templates/review-notes.md` — feedback format
16
- `examples/example-commit-coaching.md` — worked coaching session
17
18
## Workflow
19
20
### 1. Collect input
21
- The commit message(s), and if available: `git log -1 --format=%B`, or a list from `git log --oneline`.
22
- Optionally the diff summary: `git diff --stat` / `git diff --cached --stat`.
23
- Note repo conventions if present (COMMIT_EDITMSG template, commitlint config).
24
25
### 2. Lint
26
```bash
27
python3 scripts/check_commit_msg.py path/to/MSG
28
echo "fix: add retry" | python3 scripts/check_commit_msg.py -
29
```
30
Use findings as leads; style guides may intentionally differ.
31
32
### 3. Evaluate
33
For each message, using the references:
34
1. Is the **type** accurate for the change?
35
2. Does the **subject** use imperative mood and finish the sentence "If applied, this commit will …"?
36
3. Does the body explain **why** / tradeoffs, not restate the diff?
37
4. Are breaking changes marked (`BREAKING CHANGE:` or `type!:`)?
38
5. Is there noise (CI IDs, "WIP", file lists already in the diff)?
39
40
### 4. Rewrite
41
- Provide a **recommended message** ready to paste.
42
- Keep author intent; do not invent product motivations you cannot see — ask or mark assumptions.
43
- For multi-commit cleanups, suggest squash boundaries when messages are redundant.
44
45
### 5. Write coaching notes
46
Fill `templates/review-notes.md` like `examples/example-commit-coaching.md`.
47
48
## Verdicts (per message)
49
- **GOOD** — ship as-is (nits optional).
50
- **NEEDS EDIT** — rewrite provided.
51
- **SPLIT OR SQUASH** — history structure is the real problem.
52
53
## Rules
54
- Never amend, rebase, or force-push unless the user explicitly asks.
55
- Do not leak secrets from diffs into message examples.
56
- Prefer one strong subject over witty vagueness.
57