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
- dimastriann/odoo-erp-mcptheir own version, first seen Nov 8, 2026
- sowahq/claude-code-stacktheir own version, first seen Oct 15, 2026
- TitusKirch/skillstheir own version, first seen Oct 13, 2026
- Leshm0321/skillstheir own version, first seen Aug 8, 2026
- d-oit/rust-2026-templatetheir own version, first seen Jun 16, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- d-oit/rust-2026-template★ 15same name
- dimastriann/odoo-erp-mcp★ 3same name
- TitusKirch/skills★ 2same name
- Leshm0321/skills★ 1same name
- 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.
- e2e-reviewSkill
- humanizerSkill
- open-prSkill
- retrofit-commitSkill
- reviewSkill
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
- Distinctive: line 12
Every commit must be a single, self-contained unit of work.
- Very specific: line 19
Add UserRepository with get_by_id method
- Very specific: line 20
Add UserService with get_user business logic
- Distinctive: line 22
When a feature has independent sub-parts (e.g., "how a conversation enters the queue" vs.
- Distinctive: line 23
Never create a commit that references something that doesn't exist yet (e.g., importing a class before the commit that creates it).
- Very specific: line 29
No conventional commits prefix (no feat:, fix:, etc.)
- Distinctive: line 30
No period at the end
- Distinctive: line 32
No co-author tags, no "Generated by", no AI attribution — ever
- Distinctive: line 62
Do any files in separate commits have import dependencies?
- Distinctive: line 65
Is a mechanical refactor bundled with a behavior change?: If yes, split them — see "Refactor vs.
- Distinctive: line 86
Ask: "Does this plan look right?
- Distinctive: line 89
Only after explicit approval, run the commits in order using:
- Distinctive: line 98
After all commits are done:
- Distinctive: line 106
When a signature or return-type change breaks callers, the codebase must still be valid at every commit — never leave an intermediate …
- Distinctive: line 108
If a change has exactly one caller, it's safe to bundle both in the same commit.
- Distinctive: line 110
Prefer a single larger commit that's correct over several small ones with a broken state in between.
- Distinctive: line 115
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), …
- Distinctive: line 120
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 …
- Distinctive: line 124
When a single file contains changes that belong in different commits (multiple new functions, or a function change bundled with an …
- Very specific: line 134
When asked for a branch name, use eduardo/<kebab-case-feature-name> — short, descriptive of the feature, not the individual commits.
- Distinctive: line 139
If new changes show up on a branch that already has commits from a previous planning round (fixes, refinements, additional files):
- Distinctive: line 140
Never amend existing commits to absorb the new changes.
“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.
Files
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":
- Add
UserRepositorywithget_by_idmethod - Add
UserServicewithget_userbusiness logic - 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.
- Add
- 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 animationsBad 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 behaviorWorkflow
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.pyAsk: "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:
git statusmust be clean (nothing left uncommitted).git log --oneline -n <count>to show the final history.- 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. - If a reference commit with all the original (unsplit) changes still exists (e.g. a "wip" commit made before splitting), run
git diff <wip> HEADand 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:
- A commit that adapts every existing caller to the new shape while preserving their exact old behavior.
- 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 -sbandgit 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.
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
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.

