# Conventional Commits

> Use when committing changes to git. Analyzes the staged diff, splits unrelated changes into separate commits, and writes conventional commit messages that explain why, not just what.

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

---


# Conventional Commits

Produce commits a future maintainer can trust: atomic, well-scoped, and explained.

## Protocol

1. **Survey before staging.** Run `git status` and `git diff` (both staged and unstaged). Never commit blind.
2. **Split unrelated work.** If the diff mixes concerns (a bugfix plus a refactor plus a config tweak), stage and commit them separately. One logical change per commit.
3. **Choose the type** from: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`. When two apply, pick the one that matches the *intent* of the change, not its file types.
4. **Write the subject line.**
   - Format: `type(scope): imperative summary` under 72 characters
   - Scope is the module or area touched, only when it adds clarity
   - Imperative mood: "add", "fix", "remove", never "added" or "adds"
5. **Write the body only when the diff cannot speak for itself.** The body answers *why*: what problem existed, why this approach. Wrap at 72 characters.
6. **Verify before committing.** If the repo has a test or lint command, run it on the staged state first.

## Never

- Never commit secrets, keys, `.env` files, or credentials. Check the diff for anything that looks like one before every commit.
- Never use `--no-verify` to skip hooks without being explicitly told to.
- Never amend or force-push published history.
- Never write bodies that restate the diff line by line.

## Done means

The working tree is clean or intentionally dirty, every commit passes `git log --oneline` readability (a stranger can follow the story), and tests pass on the final commit.