Commit Changes
Purpose
Guide the agent through inspecting the current diff, grouping changes into coherent commits, validating each group, and committing them using this repository's commit format.
When to use this skill
- The user asks to make one or more commits.
- The current diff should be split into focused commits.
- The agent needs help deciding whether changes belong together.
- The user wants the commit work done, not just explained.
Scope boundaries
This tool groups a working diff into commits and writes their messages. It owns the grouping
decision, nothing further down the git pipeline.
ref-sp-dev-git-commits — the rules this tool applies: title format, body content, when a commit
needs a long description. Read it for the rules; use this tool to apply them to a real diff.ref-sp-py-commitizen and ref-sp-dev-semantic-versioning — releases, version bumps, and
changelog generation. A conventional-commit type affects a future bump, but choosing the bump is
not this tool's job.- Branching, rebasing, pushing, and opening pull requests are out of scope. This tool stops at the
commit.
First Step
Read the repo's commit-guidance skill (ref-sp-dev-git-commits here, the requires dependency) before deciding commit boundaries or writing commit messages.
Core Workflow
- Inspect the current changed files and diff.
- Separate unrelated user changes from the slice you should commit.
- Group files by one coherent outcome, not by file type or directory alone.
- Validate each proposed commit group with the narrowest relevant check.
- Stage only one commit group at a time.
- Write the message using the
ref-sp-dev-git-commits rules. When a group came from an automated change, record its provenance in the body (the redacted command that produced it).
- Create the commit non-interactively, then repeat for the next group if needed.
Defaults
- Default to one commit only when all changed files support the same outcome.
- Treat skill-file updates as docs by default. If a commit only changes commit-guidance skills such as
ref-sp-dev-git-commits or tool-sp-commit, prefer a title like docs(commit-skills): Short description of the commit.
- Keep tests, docs, and generated outputs in the same commit as the source change they explain or validate when they are part of the same logical unit.
- Keep source-of-truth files and generated files together when one deterministically produces the other.
- Split cleanup, renames, or refactors away from behavior changes unless they are inseparable.
- If commit grouping is ambiguous, ask before staging rather than guessing.
Grouping Rules
- Group by purpose: one feature, one fix, one docs update, one chore.
- Do not mix unrelated pre-existing user work into your commit just because it is already modified.
- Do not create a separate commit for trivial support-file changes that only make sense with the primary code change.
- Do create a separate commit when a bulk mechanical rewrite would obscure a behavior change.
- When the work came from automation, keep the automated change together and record its provenance in the commit body: include the command that produced it (codemod, link fixer, formatter, generator, or bulk rewrite) so it can be rerun or audited. Redact private details first — replace absolute home paths with a repo-relative path, drop the username, and never include tokens or secrets. See
ref-sp-dev-git-commits for the exact body format.
Task Framing
| Command or action |
What |
Why |
When |
Expected outcome |
| Inspect status and diff |
Review the current change set before staging anything. |
Commit grouping is unreliable if you guess from filenames alone. |
Always before proposing or making commits. |
The changed surfaces and likely group boundaries are understood. |
| Propose commit groups |
Decide which files belong in each commit. |
Focused commits are easier to review and revert. |
When the diff contains more than one logical change. |
Each group has one coherent purpose. |
| Validate a group |
Run the narrowest relevant check for the files in that group. |
A focused commit should be valid on its own when a focused checker exists. |
After defining a group and before committing it. |
The group has passed a scoped validation step or has a justified fallback check. |
| Stage one group |
Add only the files for the current logical commit. |
This prevents unrelated changes from bleeding into the commit. |
After the group is validated. |
The index matches exactly one planned commit. |
| Commit the group |
Create the commit using the repo's message rules. |
The history should be focused and readable. |
After staging and message preparation are complete. |
One logical commit is recorded cleanly. |
Gotchas
- Do not amend existing commits unless the user explicitly asks.
- Do not use interactive git flows when a non-interactive command will do.
- If there is no narrow validation command for a group, say so and use the next best focused check.
- If the working tree contains unrelated user changes, leave them out rather than trying to tidy them up.
Validation
- Check that each commit group is internally coherent before staging it.
- Run a focused validation step for each group when one exists.
- Check the staged diff before committing so the message matches the staged content.
- For an automated group, confirm the body records the generating command and that it carries no private details (home paths, username, tokens).
- After committing, confirm whether additional groups remain in the working tree.
1---2name: tool-sp-commit3description: Inspect edited files, group them into logical commits, and create focused commits. Use when: the user asks to commit changes, split work into focused commits, or decide how the current diff should be grouped before committing.4license: MIT5---67# Commit Changes89## Purpose1011Guide the agent through inspecting the current diff, grouping changes into coherent commits, validating each group, and committing them using this repository's commit format.1213## When to use this skill1415- The user asks to make one or more commits.16- The current diff should be split into focused commits.17- The agent needs help deciding whether changes belong together.18- The user wants the commit work done, not just explained.1920## Scope boundaries2122This tool groups a working diff into commits and writes their messages. It owns the grouping23decision, nothing further down the git pipeline.2425- `ref-sp-dev-git-commits` — the rules this tool applies: title format, body content, when a commit26 needs a long description. Read it for the rules; use this tool to apply them to a real diff.27- `ref-sp-py-commitizen` and `ref-sp-dev-semantic-versioning` — releases, version bumps, and28 changelog generation. A conventional-commit *type* affects a future bump, but choosing the bump is29 not this tool's job.30- Branching, rebasing, pushing, and opening pull requests are out of scope. This tool stops at the31 commit.3233## First Step3435Read the repo's commit-guidance skill (`ref-sp-dev-git-commits` here, the `requires` dependency) before deciding commit boundaries or writing commit messages.3637## Core Workflow38391. Inspect the current changed files and diff.402. Separate unrelated user changes from the slice you should commit.413. Group files by one coherent outcome, not by file type or directory alone.424. Validate each proposed commit group with the narrowest relevant check.435. Stage only one commit group at a time.446. Write the message using the `ref-sp-dev-git-commits` rules. When a group came from an automated change, record its provenance in the body (the redacted command that produced it).457. Create the commit non-interactively, then repeat for the next group if needed.4647## Defaults4849- Default to one commit only when all changed files support the same outcome.50- Treat skill-file updates as docs by default. If a commit only changes commit-guidance skills such as `ref-sp-dev-git-commits` or `tool-sp-commit`, prefer a title like `docs(commit-skills): Short description of the commit`.51- Keep tests, docs, and generated outputs in the same commit as the source change they explain or validate when they are part of the same logical unit.52- Keep source-of-truth files and generated files together when one deterministically produces the other.53- Split cleanup, renames, or refactors away from behavior changes unless they are inseparable.54- If commit grouping is ambiguous, ask before staging rather than guessing.5556## Grouping Rules5758- Group by purpose: one feature, one fix, one docs update, one chore.59- Do not mix unrelated pre-existing user work into your commit just because it is already modified.60- Do not create a separate commit for trivial support-file changes that only make sense with the primary code change.61- Do create a separate commit when a bulk mechanical rewrite would obscure a behavior change.62- When the work came from automation, keep the automated change together and record its provenance in the commit body: include the command that produced it (codemod, link fixer, formatter, generator, or bulk rewrite) so it can be rerun or audited. Redact private details first — replace absolute home paths with a repo-relative path, drop the username, and never include tokens or secrets. See `ref-sp-dev-git-commits` for the exact body format.6364## Task Framing6566| Command or action | What | Why | When | Expected outcome |67| --- | --- | --- | --- | --- |68| Inspect status and diff | Review the current change set before staging anything. | Commit grouping is unreliable if you guess from filenames alone. | Always before proposing or making commits. | The changed surfaces and likely group boundaries are understood. |69| Propose commit groups | Decide which files belong in each commit. | Focused commits are easier to review and revert. | When the diff contains more than one logical change. | Each group has one coherent purpose. |70| Validate a group | Run the narrowest relevant check for the files in that group. | A focused commit should be valid on its own when a focused checker exists. | After defining a group and before committing it. | The group has passed a scoped validation step or has a justified fallback check. |71| Stage one group | Add only the files for the current logical commit. | This prevents unrelated changes from bleeding into the commit. | After the group is validated. | The index matches exactly one planned commit. |72| Commit the group | Create the commit using the repo's message rules. | The history should be focused and readable. | After staging and message preparation are complete. | One logical commit is recorded cleanly. |7374## Gotchas7576- Do not amend existing commits unless the user explicitly asks.77- Do not use interactive git flows when a non-interactive command will do.78- If there is no narrow validation command for a group, say so and use the next best focused check.79- If the working tree contains unrelated user changes, leave them out rather than trying to tidy them up.8081## Validation8283- Check that each commit group is internally coherent before staging it.84- Run a focused validation step for each group when one exists.85- Check the staged diff before committing so the message matches the staged content.86- For an automated group, confirm the body records the generating command and that it carries no private details (home paths, username, tokens).87- After committing, confirm whether additional groups remain in the working tree.
swiftpostlabs