| name | conventional-commits |
| description | ALWAYS use this skill BEFORE committing changes. Triggers whenever you are asked to commit, create a commit, or save changes to git (e.g. "commit this", "commit the changes", "make a commit"). Enforces the Conventional Commits format, infers the commit type from the diff, handles breaking changes and reverts, and ensures GPG-signed commits when signing is enabled. |
| license | MIT |
| metadata | {"author":"veeso","version":"1.0.0","tags":["git","commit","conventional-commits","conventions"]} |
Conventional Commits
This skill governs how to write commit messages and how to create commits. Every
commit you make must follow the Conventional Commits
specification.
When to Use
- You are asked to commit changes, create a commit, or save work to git
- You are about to run
git commit
- You are reverting a previous commit
Message Format
Every commit message must follow this structure:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types
The type must be one of the following:
| Type | When to use |
|---|
feat | A new feature |
fix | A bug fix |
docs | Documentation only change |
style | Changes that don't affect the meaning or behaviour of the code |
refactor | A change that neither fixes a bug nor adds a feature, focused on the architecture |
perf | A change that improves performance |
test | Add missing tests or change existing tests |
build | Bump dependencies or affect the build system |
ci | Changes to CI configuration |
chore | Other changes that don't modify the source |
revert | Revert a previous commit |
Rules
1. Infer the type from the diff
Do not guess or default the type. Inspect the staged changes (git diff --cached)
and choose the type that matches what the change actually does. If the change adds
user-facing behaviour, it is feat. If it corrects broken behaviour, it is fix.
If it only moves or restructures code with no behaviour change, it is refactor.
Pick the single type that best describes the dominant change.
2. Write the description in the imperative present
The description must be an imperative present-tense sentence, as if completing
"This commit will ...". Do not capitalise the first letter beyond normal rules and
do not end with a period.
WRONG
feat: added a config flag
feat: adds a config flag
CORRECT
feat: allow provided config object to extend other configs
3. Add a scope when it clarifies
Add an optional scope in parentheses when it tells the reader which part of the
code changed: feat(parser): add ability to parse arrays. Keep it short and
lowercase. Omit it when no single scope fits.
4. Breaking changes
When a commit introduces a breaking change, mark it in two ways:
- Append a
! after the type or scope: feat!: or feat(api)!:.
- Add a
BREAKING CHANGE: footer describing what breaks.
feat(api)!: send an email to the customer when a product is shipped
BREAKING CHANGE: the response of the ship endpoint now returns the email id.
The ! and the BREAKING CHANGE: footer must both be present for a breaking
change. Do not use one without the other.
5. Body and footers
Use the optional body to explain the why when it is not obvious from the
description. Separate the body from the description with one blank line. Footers
go after the body, each on its own line, in the Token: value form (for example
Refs:, Reviewed-by:, BREAKING CHANGE:).
6. Reverts
To revert a previous commit, use the revert type and reference the reverted
commit hash(es) in a Refs: footer:
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
The description is the message of the commit being reverted.
Workflow
- Review the staged changes with
git diff --cached (stage them first if needed).
- Infer the correct
type and optional scope from the diff.
- Write an imperative-present description, plus body and footers as needed.
- Mark breaking changes with
! and a BREAKING CHANGE: footer.
Quick Reference
| Do | Don't |
|---|
| Infer the type from the actual diff | Default to chore or guess the type |
| Imperative present description | Past tense or third person ("added", "adds") |
feat!: plus a BREAKING CHANGE: footer | ! without the footer, or footer without ! |
revert: with a Refs: footer of the hashes | A free-form revert message |
Common Mistakes
- Defaulting to
chore instead of reading the diff and inferring the real type.
- Writing the description in the past tense ("fixed the bug") instead of the
imperative present ("fix the bug").
- Marking a breaking change with
! but forgetting the BREAKING CHANGE: footer.
- Reverting without referencing the reverted commit hash in a
Refs: footer.
- Creating an unsigned commit in a repository where signing is enabled.
- Pushing a commit after signing failed instead of reporting the failure.
