---
name: conventional-commits
description: >
  Format commit messages following the Conventional Commits specification:
  type, optional scope, and a concise description.
tags:
  - git
  - standards
metadata:
  version: "1.0"
---

# Conventional Commits

Write commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.

## Instructions

When creating a git commit, format the message as:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Types:**

| Type | When to use |
|------|-------------|
| `feat` | A new feature |
| `fix` | A bug fix |
| `docs` | Documentation-only changes |
| `style` | Formatting, whitespace — no logic changes |
| `refactor` | Code restructuring with no feature or fix |
| `test` | Adding or updating tests |
| `chore` | Build scripts, tooling, dependency updates |
| `perf` | Performance improvements |
| `ci` | CI/CD configuration changes |

**Rules:**

- The description must be lowercase and imperative ("add feature", not "Added feature").
- Keep the first line under 72 characters.
- Use the body to explain *why*, not *what* — the diff shows what changed.
- Add `BREAKING CHANGE:` in the footer (or `!` after the type) for breaking changes.

## Examples

```
feat(auth): add password reset flow

Implements the forgot-password endpoint and email
verification step.

Closes #42
```

```
fix: prevent crash on empty input array
```

```
refactor(api)!: rename user endpoints

BREAKING CHANGE: /users/list is now /users and
/users/get/:id is now /users/:id.
```

## Notes

- If the project already has a commit convention, follow that instead.
- Scope is optional — use it when the change is clearly limited to one module or area.