# Atomic Commits

> Use when implementing features, fixing bugs, refactoring code, or making any multi-step code changes. Guides agents to commit early and often in atomic increments, separate feature/refactor/cleanup work, and keep pull requests under ~200 lines. Use whenever writing code that will be committed, even if the user doesn't mention commits or PRs.

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

---


# Atomic Commits

Work in small, focused increments. Every commit should be atomic. Every PR should be reviewable in one sitting.

## Atomic Commit Criteria

Every commit must:

1. **Pass CI** — tests, linter, build all green
2. **Be deployable** — application is in a valid state
3. **Introduce no dead code** — no unreachable code, unused imports, or half-wired features

## One Commit, One Type of Work

- **Refactor** — restructure code without changing behavior
- **Feature** — the behavior change itself
- **Cleanup** — remove old code, update docs

If the commit message needs "and", split it.

## PR Size

Target ~200 lines per PR. If larger, find a seam — ship refactor and feature as separate PRs, each independently mergeable and deployable.

## Agent Behavior

1. Plan atomic steps before coding: refactors, then features, then cleanup.
2. Commit after each atomic step — don't accumulate.
3. Stage selectively (`git add --patch` or specific files).
4. When branch diff nears 200 lines, open a PR and continue in a follow-up.

## Hook

This skill includes a PostToolUse hook (`hooks/check-diff-size.sh`) that monitors diff size after Edit/Write operations and nudges when it's time to commit or open a PR.