Atomic Commits Skill | Agent Skills

Atomic Commits

Creates well-structured, semantic commits following Conventional Commits specification. Automatically analyzes changes and creates atomic, focused commits.

Core Principles

Atomic: Each commit represents ONE logical change
Semantic: Type prefix describes the nature of the change
Scoped: Optional scope indicates the affected module/component
Descriptive: Message explains WHAT and WHY, not HOW

Workflow

Step 1: Analyze Changes

Run these commands to understand the current state:

git status
git diff --staged
git diff

Step 2: Identify Commit Types

For each logical change, determine the appropriate type:

| Type | When to Use | | ---------- | ------------------------------------------------------- | | feat | New feature for the user | | fix | Bug fix for the user | | docs | Documentation only changes | | style | Formatting, missing semicolons (no code change) | | refactor | Code change that neither fixes a bug nor adds a feature | | perf | Performance improvement | | test | Adding or fixing tests | | build | Build system or external dependencies | | ci | CI configuration files and scripts | | chore | Other changes that don't modify src or test files | | revert | Reverts a previous commit |

Step 3: Determine Scope

Analyze changed files to suggest scope:

api/ → scope: api
core/database.py → scope: db
agents/faq_agent/ → scope: faq-agent
tests/ → scope: tests
Multiple areas → consider splitting into multiple commits

Step 4: Create Atomic Commits

If changes span multiple concerns, split them:

git add -p  # Stage hunks interactively (but explain to user)

Or stage specific files:

git add <specific-files>
git commit -m "<type>(<scope>): <description>"

Step 5: Validate Message Format

Before committing, validate the message follows the pattern:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Rules:

Type is required and lowercase
Scope is optional, lowercase, in parentheses
Description starts lowercase, no period at end
Max 72 characters for first line
Body wrapped at 72 characters
Breaking changes: add "!" after type/scope or "BREAKING CHANGE:" in footer
NEVER add auto-generated labels like "Generated with Claude Code", "Co-Authored-By", or any AI attribution
Commit messages must be clean and professional, as if written by the developer

Commit Message Template

<type>(<scope>): <short description>

<body - explain WHAT and WHY>

<footer>

Breaking Changes

For breaking changes, use one of:

feat(api)!: change authentication method

feat(api): change authentication method

BREAKING CHANGE: API now requires Bearer token instead of API key

Multi-Commit Strategy

When changes are complex, create separate commits for:

Preparation: Refactoring needed before the feature
Core: The main feature/fix implementation
Tests: New or updated tests
Docs: Documentation updates

Example sequence:

refactor(auth): extract token validation to separate function
feat(auth): add OAuth2 support
test(auth): add OAuth2 integration tests
docs(auth): update authentication guide

Interactive Mode

When asked to commit, always:

Show the user what will be committed (files and diff summary)
Suggest the commit type and scope
Propose a commit message
Ask for confirmation before executing

References

See CONVENTIONS.md for detailed type definitions. See EXAMPLES.md for real-world examples.

Agent Skills: Atomic Commits

Skill Files