Git Commit Quality
[!IMPORTANT]
Never generate or accept vague commit messages. "fix", "update", "stuff",
"wip", "misc", "changes" are BLOCKED. Every commit must tell a reviewer
what changed and why in one line.
Conventional Commits Format
<type>(<scope>): <short summary>
[optional body]
[optional footer: BREAKING CHANGE, Closes #123]
Types
| Type |
Use when |
feat |
Adding a new feature |
fix |
Fixing a bug |
docs |
Documentation only |
style |
Formatting, missing semicolons — no logic change |
refactor |
Code restructure — no feature or bug change |
perf |
Performance improvement |
test |
Adding or fixing tests |
chore |
Build process, dependency updates, tooling |
ci |
CI/CD config changes |
revert |
Reverting a previous commit |
Scope
Optional. Name of the module, component, or area affected:
feat(auth):, fix(api):, chore(deps):
Rules
- Subject line: 50 characters max. Imperative mood ("add", not "added" or "adds").
- No period at the end of the subject line.
- Body: wrap at 72 chars. Explain what and why, not how.
- Breaking changes: prefix footer with
BREAKING CHANGE: and describe the impact.
- Issue references:
Closes #123, Fixes #456 in the footer.
Good vs Bad Examples
- git commit -m "fix stuff"
+ git commit -m "fix(auth): resolve token expiry not clearing session cookie"
- git commit -m "updated readme"
+ git commit -m "docs(readme): add sparse checkout install instructions"
- git commit -m "wip"
+ git commit -m "feat(upload): add drag-and-drop file upload to dashboard"
Multi-line commit template
feat(scope): short imperative summary under 50 chars
Explain the motivation for this change. What problem does it solve?
What was the behaviour before, and what is it now?
Closes #123
Automated enforcement (recommend to user)
If the project doesn't have commit linting, suggest adding it:
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
npx husky install
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
// commitlint.config.js
module.exports = { extends: ['@commitlint/config-conventional'] };
Prohibited patterns (refuse to generate these)
- Single-word messages:
fix, update, test, done, changes, stuff
- Generic messages:
minor changes, small fix, various updates
- Time-based messages:
end of day, monday work, before meeting
- Placeholder messages:
TODO, WIP (unless explicitly a draft branch)
1---2name: git-commit-quality3description: Enforces high-quality git commit messages following Conventional Commits. Use this skill whenever the agent is about to run `git commit`, write a commit message, or help a user stage and commit changes. Blocks vague messages like "fix", "update", "changes", "wip". Also activates when the user asks "how should I write this commit?" or "help me commit this".4license: Apache-2.05---67# Git Commit Quality89> [!IMPORTANT]10> **Never generate or accept vague commit messages.** "fix", "update", "stuff",11> "wip", "misc", "changes" are BLOCKED. Every commit must tell a reviewer12> *what changed and why* in one line.1314---1516## Conventional Commits Format1718```19<type>(<scope>): <short summary>2021[optional body]2223[optional footer: BREAKING CHANGE, Closes #123]24```2526### Types2728| Type | Use when |29|------|----------|30| `feat` | Adding a new feature |31| `fix` | Fixing a bug |32| `docs` | Documentation only |33| `style` | Formatting, missing semicolons — no logic change |34| `refactor` | Code restructure — no feature or bug change |35| `perf` | Performance improvement |36| `test` | Adding or fixing tests |37| `chore` | Build process, dependency updates, tooling |38| `ci` | CI/CD config changes |39| `revert` | Reverting a previous commit |4041### Scope4243Optional. Name of the module, component, or area affected:44`feat(auth):`, `fix(api):`, `chore(deps):`4546---4748## Rules49501. **Subject line**: 50 characters max. Imperative mood ("add", not "added" or "adds").512. **No period** at the end of the subject line.523. **Body**: wrap at 72 chars. Explain *what* and *why*, not *how*.534. **Breaking changes**: prefix footer with `BREAKING CHANGE:` and describe the impact.545. **Issue references**: `Closes #123`, `Fixes #456` in the footer.5556---5758## Good vs Bad Examples5960```diff61- git commit -m "fix stuff"62+ git commit -m "fix(auth): resolve token expiry not clearing session cookie"6364- git commit -m "updated readme"65+ git commit -m "docs(readme): add sparse checkout install instructions"6667- git commit -m "wip"68+ git commit -m "feat(upload): add drag-and-drop file upload to dashboard"69```7071---7273## Multi-line commit template7475```76feat(scope): short imperative summary under 50 chars7778Explain the motivation for this change. What problem does it solve?79What was the behaviour before, and what is it now?8081Closes #12382```8384---8586## Automated enforcement (recommend to user)8788If the project doesn't have commit linting, suggest adding it:8990```bash91npm install --save-dev @commitlint/cli @commitlint/config-conventional husky92npx husky install93echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg94```9596```js97// commitlint.config.js98module.exports = { extends: ['@commitlint/config-conventional'] };99```100101---102103## Prohibited patterns (refuse to generate these)104105- Single-word messages: `fix`, `update`, `test`, `done`, `changes`, `stuff`106- Generic messages: `minor changes`, `small fix`, `various updates`107- Time-based messages: `end of day`, `monday work`, `before meeting`108- Placeholder messages: `TODO`, `WIP` (unless explicitly a draft branch)
carthworks