clean-commits

Use when committing code - ensures atomic, descriptive commits that leave the codebase in a merge-ready state at every point

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The Clean Commits skill automates the process of creating atomic, descriptive, and high-quality Git commits. It ensures that every code change follows the Conventional Commits standard and passes essential local verification steps—such as tests, linting, and builds—before being committed. This maintains a merge-ready codebase, improves project history readability, and streamlines the code review process.

Use Cases

  • Standardizing commit messages using the Conventional Commits format (feat, fix, refactor) to facilitate automated changelog generation and better team communication.
  • Enforcing 'Working State' requirements by automatically running pnpm test and build checks before every commit to prevent breaking the CI/CD pipeline.
  • Breaking down large, complex feature implementations into small, logical, and atomic commits that are easier to review, revert, and debug.
  • Improving codebase maintainability by ensuring every commit in the history is a stable point that can be checked out and run without errors.
  • Automating the staging and committing process for AI agents to ensure they don't leave messy or non-descriptive 'WIP' messages in the repository.
nameclean-commits
descriptionUse when committing code - ensures atomic, descriptive commits that leave the codebase in a merge-ready state at every point
modelopus

Clean Commits

Overview

Every commit is atomic, descriptive, and leaves code in a working state.

Core principle: Anyone should be able to checkout any commit and have working code.

Announce at use: "I'm committing with a descriptive message following clean-commits standards."

Commit Message Format

Structure

[type](scope): Short description (max 72 chars)

[Optional body - what and why, not how]

[Optional footer - issue references, breaking changes]

Refs: #[ISSUE_NUMBER]

Types

Type Use For
feat New feature
fix Bug fix
docs Documentation only
style Formatting, no code change
refactor Code restructuring
test Adding/fixing tests
chore Maintenance, dependencies

Examples

feat(auth): Add user registration endpoint

Implement POST /api/users/register with email validation,
password hashing, and duplicate detection.

- Validates email format and uniqueness
- Hashes password with bcrypt
- Returns user object without password

Refs: #123
fix(auth): Prevent redirect loop on expired session

Session expiry was triggering redirect to login, which
checked session, found expired, and redirected again.

Now clears session cookie before redirecting.

Refs: #456
test(auth): Add integration tests for registration

Cover success case, duplicate email, invalid format,
and weak password scenarios.

Refs: #123

Atomic Commits

What Makes a Commit Atomic

Atomic Not Atomic
One logical change Multiple unrelated changes
Passes all tests Breaks tests
Complete feature slice Half-implemented feature
Can be reverted cleanly Reverts would break things

Signs of Non-Atomic Commits

  • Commit message uses "and" to describe multiple things
  • Diff includes unrelated files
  • Some tests fail after commit
  • "WIP" in commit message

Splitting Large Changes

If you have multiple changes, commit them separately:

# Stage specific files
git add src/auth/register.ts
git add src/auth/register.test.ts
git commit -m "feat(auth): Add registration endpoint"

# Stage next logical unit
git add src/auth/login.ts
git add src/auth/login.test.ts
git commit -m "feat(auth): Add login endpoint"

Working State Requirement

Every commit must leave the codebase in a state where:

  • All tests pass
  • Build succeeds
  • Application runs
  • No TypeScript errors
  • No linting errors

Before committing:

# Run tests
pnpm test

# Check build
pnpm build

# Check types
pnpm typecheck

# Check lint
pnpm lint

If any fail, fix before committing.

Commit Frequency

Commit Often

  • After each passing test in TDD cycle
  • After each refactoring step
  • After completing a logical unit

Don't Wait Too Long

Too Infrequent Just Right
"Implement entire feature" "Add user model"
"Fix all bugs" "Fix session expiry redirect"
"Update everything" "Update auth dependencies"

Small is Good

Smaller commits are:

  • Easier to review
  • Easier to revert
  • Easier to bisect
  • Easier to understand

The Commit Process

1. Stage Selectively

# Review what changed
git diff

# Stage specific files
git add [specific files]

# Or stage interactively
git add -p

2. Review Staged Changes

# See what will be committed
git diff --staged

3. Write Descriptive Message

# Short message (if simple)
git commit -m "fix(auth): Handle null user in session check"

# Long message (if complex)
git commit
# Opens editor for full message

4. Verify After Commit

# Check commit looks right
git show --stat

# Verify tests still pass
pnpm test

Commit Message Body

When to include a body:

  • Why the change was made (not just what)
  • Context that isn't obvious from code
  • Trade-offs or alternatives considered
  • Breaking changes if any

Body Examples

refactor(api): Extract validation middleware

Validation logic was duplicated across 12 endpoints.
Extracted to reusable middleware that can be composed.

Alternative considered: validation library.
Rejected because our rules are domain-specific.
fix(data): Use optimistic locking for updates

Race condition was causing lost updates when two users
edited the same record simultaneously.

BREAKING CHANGE: Update operations now require
version field in request body.

Issue References

Always reference the issue:

# In commit message
Refs: #123

# Or if commit closes the issue
Closes: #123

Amending Commits

When to Amend

  • Typo in message (if not pushed)
  • Forgot to stage a file (if not pushed)
# Amend last commit (before push only!)
git add forgotten-file.ts
git commit --amend

When NOT to Amend

  • After pushing to remote
  • Changing commits others have based work on

Revert, Don't Delete

If a commit was wrong:

# Create a new commit that undoes the change
git revert [commit-sha]

# DON'T rewrite history on shared branches
# DON'T force push to fix mistakes

Checklist

Before each commit:

  • Tests pass
  • Build succeeds
  • Change is atomic (one logical unit)
  • Message follows format
  • Message describes why, not just what
  • Issue is referenced
  • No "WIP" or placeholder messages

Integration

This skill is called by:

  • issue-driven-development - Throughout development
  • pr-creation - Before creating PR

This skill enforces:

  • Reviewable history
  • Revertible changes
  • Clear project narrative