Agent skill

clean-commits

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

Stars 5
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/troykelly/codex-skills/tree/main/skills/clean-commits

SKILL.md

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:

bash
# 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:

bash
# 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

bash
# Review what changed
git diff

# Stage specific files
git add [specific files]

# Or stage interactively
git add -p

2. Review Staged Changes

bash
# See what will be committed
git diff --staged

3. Write Descriptive Message

bash
# 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

bash
# 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:

bash
# 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)
bash
# 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:

bash
# 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

Expand your agent's capabilities with these related and highly-rated skills.

troykelly/codex-skills

hook-development

Use when the user wants to create Codex workflow hooks (pre/post run gates, tool-use validators, stop checks) or needs guidance on hook scripts and hooks.json configuration.

5 0
Explore
troykelly/codex-skills

sentry-setup-ai-monitoring

Setup Sentry AI Agent Monitoring in any project. Use this when asked to add AI monitoring, track LLM calls, monitor AI agents, or instrument OpenAI/Anthropic/Vercel AI/LangChain/Google GenAI. Automatically detects installed AI SDKs and configures the appropriate Sentry integration.

5 0
Explore
troykelly/codex-skills

agent-development

Use when the user wants to design Codex agent equivalents (specialized workers/profiles/prompt files), define triggering conditions, or build reusable agent prompts and validation tools.

5 0
Explore
troykelly/codex-skills

skill-development

Use when the user wants to create or refine Codex skills, improve skill descriptions, organize skill resources, or follow Codex skill best practices.

5 0
Explore
troykelly/codex-skills

sentry-setup-logging

Setup Sentry Logging in any project. Use this when asked to add Sentry logs, enable structured logging, setup console log capture, or integrate logging with Sentry. Supports JavaScript, TypeScript, Python, Ruby, React, Next.js, and other frameworks.

5 0
Explore
troykelly/codex-skills

frontend-design

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

5 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results