# Commit Conventions

> Conventional Commits with a leading gitmoji - valid types, scope derived from file paths, header at most 72 characters excluding the emoji, subject/body/breaking-changes rules. Load when writing, reviewing, or generating a commit message.

- Skill: `carlosferorduna/commit-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add carlosferorduna/commit-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/carlosferorduna/commit-conventions/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: CarlosFerOrduna (https://skillmd.com/u/carlosferorduna)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/carlosferorduna/commit-conventions

---


# Commit Conventions

Commit messages are written in **English** using **Conventional Commits** with a
leading gitmoji:

```text
<emoji> <type>(<scope>): <subject>
```

## Valid types

The `type` must be one of: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`,
`test`, `build`, `ci`, `chore`, `revert`.

The emoji identifies the change, the type must **always** be valid. Critical
hotfixes and security fixes are still a `fix`, never a new type:

| Gitmoji | Type       | Meaning                           |
| ------- | ---------- | --------------------------------- |
| ✨      | `feat`     | New feature                       |
| 🐛      | `fix`      | Bug fix                           |
| 🚑️      | `fix`      | Critical hotfix                   |
| 🔒️      | `fix`      | Security fix or hardening         |
| 📝      | `docs`     | Documentation                     |
| 🎨      | `style`    | Formatting/style, no logic change |
| ♻️      | `refactor` | Refactoring                       |
| ⚡️      | `perf`     | Performance improvement           |
| ✅      | `test`     | Tests                             |
| 👷      | `build`    | Build changes                     |
| 💚      | `ci`       | CI changes                        |
| 🔧      | `chore`    | Chore/configuration               |
| ⏪️      | `revert`   | Revert                            |
| ⬆️      | `chore`    | Dependency upgrade                |
| ⬇️      | `chore`    | Dependency downgrade              |
| ➕      | `chore`    | Add dependency                    |
| ➖      | `chore`    | Remove dependency                 |
| 🔥      | `chore`    | Remove code or files              |
| 🗃️      | `chore`    | Database schema/migration         |
| 🚀      | `ci`       | Deploy/release                    |

## Scope

- The `scope` is based on the affected file **PATH**: the service directory or a
  module inside it, never a class name or symbol.
- Prefer short scopes derived from the service path (`payments` for a payment
  service, `ui` for a web client), not the full repo or module name.
- Omit the scope when it adds no signal or the header would exceed the limit.

## Header length

- Maximum **72 characters excluding the emoji**. Some gitmojis carry U+FE0F
  (multiple code points), so counting the emoji would make the limit unstable;
  exclude it.
- Aim for **60 characters or fewer**.
- Subject: imperative mood, starts lowercase, no trailing punctuation.
- If the header is too long: tighten the subject, shorten the scope, drop the
  scope, then move useful context into the body.

## Body

- Omit the body when the subject expresses the change.
- Use it only for useful context: why the change was made, non-obvious design
  decisions, reviewer context.
- Do not repeat the subject or describe the diff line by line.
- Separate subject and body with a blank line.

## Breaking changes

- Add `!` after type/scope and a `BREAKING CHANGE:` footer explaining the
  impact.

## Other rules

- Never reference tickets, issues, or PR numbers.
- Never include `Co-Authored-By:` trailers in commit messages.
- Only return a commit message when asked to generate one.

Example:

```text
✨ feat(auth): add JWT refresh-token rotation
```