# Commit Message Conventions

> Write git commit messages that follow the Conventional Commits standard.

- Skill: `driftproofhq/commit-message-conventions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add driftproofhq/commit-message-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/driftproofhq/commit-message-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: driftproofhq (https://skillmd.com/u/driftproofhq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/driftproofhq/commit-message-conventions

---


# Commit Message Conventions

When asked to write a git commit message, produce a message that follows the
Conventional Commits 1.0.0 specification.

## Format

```
<type>(<optional scope>): <subject>

<optional body>

<optional footer(s)>
```

## Rules

1. **Type** is required and MUST be one of:
   `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
2. **Scope** is optional, lowercase, in parentheses, naming the area touched
   (e.g. `feat(auth):`).
3. **Subject**:
   - imperative mood ("add", not "added" or "adds"),
   - lowercase first letter,
   - no trailing period,
   - 72 characters or fewer.
4. **Breaking changes** MUST be signalled either with a `!` before the colon
   (`feat!:`) or a `BREAKING CHANGE:` footer (using both is fine).
5. **Body** (when present) explains *what* and *why*, not *how*, wrapped at ~72
   columns, separated from the subject by one blank line.
6. Output ONLY the commit message — no surrounding prose, no code fences, no
   explanation unless explicitly asked.

## Choosing the right type

The type is the most common mistake. Pick by the *nature* of the change, not the
files touched:

- `feat` — a new capability visible to users.
- `fix` — a correction to broken behaviour.
- `perf` — a change whose purpose is to make existing behaviour faster/leaner
  (NOT `refactor` and NOT `fix` — performance is its own type).
- `refactor` — restructuring with no behaviour change and no perf goal.
- `docs` — documentation only.
- `test` — adding or fixing tests only.
- `build` — build system, bundler, packaging, or dependency changes
  (e.g. bumping a build tool or production dependency).
- `ci` — CI configuration and pipelines only.
- `chore` — maintenance that fits nothing above (e.g. dev-only housekeeping).
- `style` — formatting/whitespace with no code-meaning change.

When a change plausibly fits two types, prefer the more *specific* one
(`perf` over `refactor`; `build` over `chore`).

## Footers

Footers go after the body, one per line, in `Token: value` form:

- Issue references: `Refs: #123`, `Closes #123`, `Fixes #123`.
- Breaking changes: `BREAKING CHANGE: <description>`.

## Reverts

To revert a previous commit, use the `revert` type and name the reverted commit
in the body:

```
revert: <subject of the reverted commit>

This reverts commit <hash>.
```

## Splitting unrelated changes

If asked to describe several unrelated changes in one message, the correct guidance
is that they should be **separate commits** — one Conventional Commit each. Say so,
and, if forced into one message, choose the single most significant change for the
subject and list the rest in the body.

## Examples

Good:
```
feat(parser): support trailing commas in arrays
```
```
fix(auth): reject expired refresh tokens

Tokens past their `exp` claim were still accepted because the check compared
against issue time. Compare against the current time instead.
```
```
perf(render): memoize layout computation to cut re-renders
```
```
build(deps): upgrade bundler to v6
```
```
refactor!: drop support for Node 16

BREAKING CHANGE: the minimum supported runtime is now Node 18.
```
```
revert: add dark mode toggle to settings

This reverts commit 9f3c1a2.
```

Bad (do not do these):
- `Added dark mode.` — past tense, capitalized, trailing period, no type.
- `update stuff` — no type, vague subject.
- `fix: made the list render faster` — a performance change should be `perf`, and
  the subject is past tense.
- `feat: Implemented the new caching layer for the API.` — capitalized subject,
  past tense, trailing period.