# Creating Commits

> Create well-structured git commits with clear, conventional commit messages. Use this skill whenever the user asks to commit changes, "commit this", "save my work", "make a commit", "write a commit message", or after completing a coding task when changes need to be committed. Also use when the user asks to split changes into multiple commits, amend a commit, or improve an existing commit message.

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

---


# Creating Commits

A skill for producing clean, atomic commits with high-quality messages.

## Workflow

Always follow these steps in order:

### 1. Inspect before committing

Run these in parallel to understand the state of the repo:

```bash
git status                 # what's staged, unstaged, untracked
git diff                   # unstaged changes
git diff --staged          # staged changes
git log --oneline -10      # recent messages, to match repo style
```

Never commit blind. Read the actual diff — the commit message must describe what changed, not what you think you changed.

### 2. Decide what belongs in the commit

- **One logical change per commit.** If the diff contains unrelated changes (e.g., a bug fix AND a refactor AND a config tweak), propose splitting into separate commits. Use `git add -p` or stage files selectively.
- **Never use `git add .` or `git add -A` reflexively.** Stage files explicitly by path so unrelated or accidental files (logs, `.env`, build artifacts, editor files) don't slip in.
- Check for files that should not be committed: secrets, credentials, large binaries, generated output. Warn the user if any appear in the diff.
- Do not commit commented-out code or leftover debug statements without flagging them first.

### 3. Write the message

Detect the repo's convention from `git log`. If the repo uses Conventional Commits, follow it. Otherwise use the standard format below.

**Format:**

```
<type>(<optional scope>): <summary, imperative, ≤50 chars>

<body: what and WHY, wrapped at 72 chars — optional for trivial changes>
```

**Types** (Conventional Commits): `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `style`, `revert`.

**Subject line rules:**
- Imperative mood: "add validation", not "added" or "adds". Test: the line should complete "If applied, this commit will ___".
- ≤50 characters, no trailing period, lowercase after the type prefix.
- Be specific: `fix: prevent race condition in session refresh` — not `fix: bug fix` or `update code`.

**Body rules (when needed):**
- Explain *why* the change was made and any non-obvious consequences; the diff already shows *what*.
- Mention alternatives considered or constraints if relevant.
- Skip the body only for genuinely trivial changes (typo fixes, version bumps).

**Never:**
- Vague messages: "fixes", "wip", "updates", "misc changes".
- Restating the diff line-by-line.
- Bundling "and also..." — that's a sign the commit should be split.
- Adding footer and information about co-author like Claude etc.

### 4. Commit

Use a heredoc for multi-line messages:

```bash
git commit -m "$(cat <<'EOF'
fix(auth): prevent race condition in token refresh

Two concurrent requests could both detect an expired token and
trigger duplicate refresh calls, invalidating each other's sessions.
Serialize refresh behind a per-user mutex.

Fixes #482
EOF
)"
```

### 5. Verify

Run `git status` and `git log -1 --stat` after committing to confirm the commit contains exactly what was intended.

## Special cases

- **Amending**: only `git commit --amend` when the commit has NOT been pushed, and confirm with the user first.
- **Empty diff**: if there is nothing to commit, say so — do not create empty commits.
- **Pre-commit hooks**: if a hook fails, fix the underlying issue rather than using `--no-verify`. Only bypass hooks if the user explicitly asks. If a hook modifies files (e.g., a formatter), re-stage and retry once.
- **Never push, force-push, or rewrite history** unless the user explicitly asks.
- **Breaking changes**: mark with `!` after the type (`feat!:`) and a `BREAKING CHANGE:` footer explaining migration.

## Examples

Good:

```
feat(api): add cursor-based pagination to /orders endpoint

Offset pagination degraded past ~100k rows. Cursor pagination keeps
response times flat and matches the pattern used in /customers.
```

```
chore: bump lodash to 4.17.21
```

Bad:

```
update stuff
fixed the thing we talked about
WIP
feat: changes to api and also fixed tests and updated readme
```