agentleFS
eduardokairalla1eduardokairalla1/personal-skills/skills/atomic-commit/SKILL.md

atomic-commit

Skill0 starsChanged 24 days agoMITView on GitHub

Plans and executes atomic git commits following Eduardo's commit conventions. Use when the user wants to commit changes, stage files, write commit messages, or organize work into commits. Triggers on "commit my changes", "make commits", "commit this", "stage and commit", "organize my commits", "what should I commit", or any request to save progress to git history.

5 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions5 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 5

    1. d-oit/rust-2026-template★ 15same name
    2. dimastriann/odoo-erp-mcp★ 3same name
    3. TitusKirch/skills★ 2same name
    4. Leshm0321/skills★ 1same name
    5. sowahq/claude-code-stack★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. 0 are common, 18 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 18

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every commit must be a single, self-contained unit of work.

    line 12
  2. Very specific:

    Add UserRepository with get_by_id method

    line 19
  3. Very specific:

    Add UserService with get_user business logic

    line 20
  4. Distinctive:

    When a feature has independent sub-parts (e.g., "how a conversation enters the queue" vs.

    line 22
  5. Distinctive:

    Never create a commit that references something that doesn't exist yet (e.g., importing a class before the commit that creates it).

    line 23
  6. Very specific:

    No conventional commits prefix (no feat:, fix:, etc.)

    line 29
  7. Distinctive:

    No period at the end

    line 30
  8. Distinctive:

    No co-author tags, no "Generated by", no AI attribution — ever

    line 32
  9. Distinctive:

    Do any files in separate commits have import dependencies?

    line 62
  10. Distinctive:

    Is a mechanical refactor bundled with a behavior change?: If yes, split them — see "Refactor vs.

    line 65
  11. Distinctive:

    Ask: "Does this plan look right?

    line 86
  12. Distinctive:

    Only after explicit approval, run the commits in order using:

    line 89
  13. Distinctive:

    After all commits are done:

    line 98
  14. Distinctive:

    When a signature or return-type change breaks callers, the codebase must still be valid at every commit — never leave an intermediate …

    line 106
  15. Distinctive:

    If a change has exactly one caller, it's safe to bundle both in the same commit.

    line 108
  16. Distinctive:

    Prefer a single larger commit that's correct over several small ones with a broken state in between.

    line 110
  17. Distinctive:

    If a new feature requires refactoring existing code (e.g., changing a shared method's return type so a new caller can consume richer data), …

    line 115
  18. Distinctive:

    Don't mix "adjusted the code to fit the new shape" with "changed what the code does" in the same commit, even though both touch the same …

    line 120
  19. Distinctive:

    When a single file contains changes that belong in different commits (multiple new functions, or a function change bundled with an …

    line 124
  20. Very specific:

    When asked for a branch name, use eduardo/<kebab-case-feature-name> — short, descriptive of the feature, not the individual commits.

    line 134
  21. Distinctive:

    If new changes show up on a branch that already has commits from a previous planning round (fixes, refinements, additional files):

    line 139
  22. Distinctive:

    Never amend existing commits to absorb the new changes.

    line 140

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

atomic-commit

You plan and execute atomic git commits. Your job is to analyze the current changes, design a logical commit sequence, propose it for approval, then execute it.

Core principle: atomic commits

Every commit must be a single, self-contained unit of work. The codebase must be in a valid, working state after each commit — never broken in between, not even for one commit in the middle of the sequence.

Rules:

  • One commit = one logical change. Never mix unrelated changes in the same commit.
  • Granularity: one function/operation per commit, even within the same file. Don't bundle multiple new functions into one commit just because they live in the same file or were written together. When a file has more than one new/changed function that belong in different commits, split it with partial staging (git add -p, or manually reconstruct the intermediate file content for each commit — see "Partial staging" below).
  • Exception: a type/constant and the first piece of code that uses it can stay together if the type has no meaning on its own (e.g., a new TypedDict added purely to support a new function). Tests that directly test a new function stay with it. When genuinely unsure whether to split, default to keeping together — but this is a fallback, not the default posture.
  • Commits must form a logical staircase toward the goal, ordered as a dependency narrative: "to build X, we first need Y; to build Y, we need Z" — not horizontal layers ("all types, then all state, then all api"). Example for "build a GET endpoint":
    1. Add UserRepository with get_by_id method
    2. Add UserService with get_user business logic
    3. Add GET /users/{id} endpoint When a feature has independent sub-parts (e.g., "how a conversation enters the queue" vs. "how the loop stops when there's no more work"), finish all commits for one sub-part before starting the next — don't interleave them.
  • Never create a commit that references something that doesn't exist yet (e.g., importing a class before the commit that creates it).

Commit message format

  • English only
  • Short and direct, imperative mood (what the commit does, not what you did)
  • No conventional commits prefix (no feat:, fix:, etc.)
  • No period at the end
  • 50 characters max on the first line
  • No co-author tags, no "Generated by", no AI attribution — ever
  • No commit body by default. Add a body ONLY when the commit implements something non-obvious that a developer can't infer from reading the code and the subject line — for example, a non-trivial algorithm, a workaround for an external bug, or an architectural decision with non-obvious tradeoffs. Routine additions (models, endpoints, services, UI components) never need a body.
  • Never name the function, class, or type in the message. Describe the behavior/effect for the system, not the implementation. A reviewer should understand what changed for the product without knowing the symbol names.

Good examples:

Add UserProfile model to represent authenticated user data
Add operation to retrieve user profile by uid
Add operation to mark agent as available or unavailable
Implement login page UI design
Fix HomePage to StatefulWidget and enhance UI with animations

Bad examples:

feat: add user profile          ← no conventional commits prefix
Added user profile model.       ← past tense, has period
Update stuff                    ← vague
Add UserProfile model and UserService and login page  ← not atomic
Add setStatus function          ← names the function instead of its effect
Change name of _getAvailable function ← implementation detail, not behavior

Workflow

Step 1 — Understand the changes

Run git diff HEAD and git status to get the full picture of what changed. Read the full content of every new/untracked file — don't rely on the diff alone for files that don't exist yet in the index. If the project has a clear structure (e.g., FastAPI with routers/services/repositories, Flutter with models/pages/providers), use that to reason about dependencies between files.

Step 2 — Design the commit plan

Group changes into atomic commits at the granularity described above (one function/operation per commit by default). Order them as a dependency narrative. Check:

  • Do any files in separate commits have import dependencies? If yes, they must be in the same commit or reordered.
  • Is any commit doing two unrelated things? If yes, split it.
  • Trace every call chain for breaking signature changes. If a commit changes a function's signature (params added/removed, return type changed), find every caller and confirm each one is either in the same commit or already compatible. See "Breaking changes across the call chain" below.
  • Is a mechanical refactor bundled with a behavior change? If yes, split them — see "Refactor vs. behavior change" below.

Step 3 — Present the plan

Show the proposed commit sequence BEFORE executing anything. Format:

Proposed commits (in order):

1. Add UserProfile model to represent authenticated user data
   Files: app/models/user_profile.py, app/schemas/user_profile.py

2. Add storage function to retrieve user profile by uid
   Files: app/repositories/user_repository.py

3. Add callable function for retrieving user profile
   Files: app/services/user_service.py

4. Add GET /users/{id} endpoint
   Files: app/routers/users.py

Ask: "Does this plan look right? I'll execute it once you confirm."

Step 4 — Execute after approval

Only after explicit approval, run the commits in order using:

git add <files>
git commit -m "<message>"

One git add + git commit per planned commit. Do not batch all files into one git add ..

Step 5 — Verify

After all commits are done:

  1. git status must be clean (nothing left uncommitted).
  2. git log --oneline -n <count> to show the final history.
  3. Check that every commit in the sequence — not just the final one — has valid syntax. For each commit hash, extract the changed files at that point and run a parse/compile check (e.g. python -c "import ast; ast.parse(open(f).read())" or the language equivalent). This catches intermediate states that only "look" atomic but would actually break a bisect.
  4. If a reference commit with all the original (unsplit) changes still exists (e.g. a "wip" commit made before splitting), run git diff <wip> HEAD and confirm it's empty — this proves the atomic sequence reconstructs the exact same end state, without losing or altering a single line (including incidental things like stray blank lines).

Breaking changes across the call chain

When a signature or return-type change breaks callers, the codebase must still be valid at every commit — never leave an intermediate commit where a caller passes the wrong number of arguments or expects an old return shape.

  • If a change has exactly one caller, it's safe to bundle both in the same commit.
  • If the change propagates through multiple layers (e.g., state → api → router, each just forwarding to the next), trace the whole chain before finalizing the plan. Usually the minimal-but-correct answer is to bundle the function and its immediate caller together, one layer at a time, and repeat for the next layer up — never leave a commit where a rewritten function's caller hasn't been updated to match.
  • Prefer a single larger commit that's correct over several small ones with a broken state in between.
  • When two changes in the same file are logically separable but you need to defer one of them (e.g., a private helper both are used by), it's fine to leave the helper in place unused-by-one-caller for one commit and remove it once its last caller is gone in a later commit — this is a valid technique, not a shortcut.

Refactor vs. behavior change

If a new feature requires refactoring existing code (e.g., changing a shared method's return type so a new caller can consume richer data), split it into:

  1. A commit that adapts every existing caller to the new shape while preserving their exact old behavior.
  2. A separate, later commit (can come after the new feature's own commits) that actually changes the behavior.

Don't mix "adjusted the code to fit the new shape" with "changed what the code does" in the same commit, even though both touch the same lines.

Partial staging

When a single file contains changes that belong in different commits (multiple new functions, or a function change bundled with an unrelated one), stage only the relevant hunks:

git add -p <file>

If the hunks are adjacent and git add -p can't split them cleanly (e.g., a function being removed sits right next to a signature rewrite of the function below it), reconstruct the intermediate file content manually: write the file in the exact state that commit should have, commit it, then edit again for the next commit. Always run a syntax check (e.g. python -m py_compile <file> or the language equivalent) before committing a manually-reconstructed intermediate state.

Branches and MRs

  • When asked for a branch name, use eduardo/<kebab-case-feature-name> — short, descriptive of the feature, not the individual commits.
  • When asked for an MR/PR title, use a short imperative sentence, same tone as commit messages (no prefix, no period), describing the feature as a whole rather than any single commit. If Eduardo proposes his own simpler title, use his wording instead of arguing for a more "descriptive" one.

Handling follow-up changes on an already-committed branch

If new changes show up on a branch that already has commits from a previous planning round (fixes, refinements, additional files):

  • Never amend existing commits to absorb the new changes.
  • Analyze the new diff the same way as a fresh set of changes, and propose new commits slotted into their correct logical position in the existing sequence (not necessarily at the end).
  • If the new commits need to land in the middle of existing history, that requires an interactive rebase — do this only if the branch has no upstream/hasn't been pushed (check with git status -sb and git log --oneline @{u}), and confirm with the user first since rebasing rewrites history.

Edge cases

  • Unstaged deletions or renames: include them in the commit of the feature they belong to.
  • New dependencies (e.g., pyproject.toml + poetry.lock, package.json + lockfile, pubspec.yaml): get a commit of their own, containing only the manifest and lock files, placed immediately before the first commit that imports the library — never bundled with the first function that uses it. Message names the libraries, e.g. Add SQLAlchemy and asyncpg as dependencies. If the lock file is new to the repo, it goes in this same commit. A standalone version bump with no related feature is also its own commit.
  • New configuration settings (a new key in the service config template, e.g. data/<service>.yml.j2, and its mirror in the test fixture): get a commit of their own, placed immediately before the first commit that reads the setting — never bundled with the code that uses it. Message says what was configured, e.g. Add admin credentials to the Postgres settings.
  • Refactors that touch many files: these are valid atomic commits as long as the refactor is the only thing happening. Don't mix a refactor with a new feature.
  • If you're unsure whether two files belong in the same commit, default to keeping them together. It's better to slightly over-group than to create a broken intermediate state.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.