halfline/git-stage-batch/commit-staged-changes

Commit Staged Changes

Use this skill to turn the current staged index into one git commit with project-compliant commit messaging.

This skill is autonomous and non-interactive. Inspect the staged set, confirm that it is coherent enough to commit as one change, write a compliant commit message, create the commit, and then stop without asking the user to review the draft first.

This skill only handles content that is already staged. Do not stage unstaged changes, do not unstage anything, and do not rearrange the index into a different split. Leave unstaged work exactly as you found it.

Installed resources and project guidance

Set ASSET_ROOT to the absolute .agents directory containing this installed skill, two levels above its skill directory. Resolve it from the loaded SKILL.md path, whether installed in the repository or the user's home. Resolve references/ and scripts/ paths relative to this skill directory. Keep the working directory in the target repository, quote helper paths in shell commands, and pass ASSET_ROOT to workers that use companion resources.

Before drafting, search the project tree for CONTRIBUTING.md, excluding installed assistant assets. Check the repository root, .github/, docs/, and guidance scoped to the changed paths. Read the applicable project guide. Only if the project has no contribution guide of its own, read $ASSET_ROOT/internal/CONTRIBUTING.md. Other project instructions and commit hooks still take precedence over bundled defaults. Pass the selected guide's path and applicable rules to any drafting worker.

Core Workflow

1. Inspect repository state with git status --short.
2. Check whether the index contains staged changes.
3. If there are no staged changes, stop and tell the user there is nothing to

commit.

1. Read repository-specific commit guidance before drafting messages:

• CONTRIBUTING.md when present
• .git/hooks/commit-msg when present

1. Inspect the staged set with:

• git diff --cached --stat
• git diff --cached

1. Treat unstaged changes as context only. They are not part of this commit

and must remain untouched.

1. Decide whether the staged set is coherent as one commit.
2. If the staged set clearly contains multiple independent concerns, stop and

explain that the current index should be split before committing. Do not repair the split yourself under this skill.

1. If the staged set is coherent, draft the commit message.
2. Prefer a fresh-context subagent for commit-message drafting after the

staged set is complete. Use the shared commit-message-drafter constraints below as the briefing template rather than keeping message drafting in the same long-running context when the session involved substantial staging or series analysis.

1. Create the commit from the staged set only.
2. If the commit fails because the message format is wrong, fix the message

and retry.

1. If the commit fails because the staged path set or staged content violates

repository policy, stop and explain the blocker instead of restaging.

Decision Rules

• The staged set must stand on its own as one commit.
• Shared directory, subsystem, or command surface is not enough to make two

changes one concern.

• If the staged set mixes multiple concrete implementations, bug fixes, or

independently testable behaviors, stop and tell the user the index should be split before committing.

• Do not broaden the story of the commit just because the staged set is mixed.
• Do not silently commit an obviously non-atomic index just to finish.

Fresh-Context Message Drafting

For Codex, the equivalent of Claude's dedicated message-drafter agent is a read-only subagent briefed with the same constraints as the shared commit-message-drafter asset. Prefer that pattern by default once the staged diff is complete.

If you spawn a subagent for message drafting:

1. Spawn it only after the staged diff for the current commit is complete.
2. Tell it not to stage, edit, or commit anything.
3. Give it a self-contained briefing that includes:

• the relevant state before the patch, with supporting code locations
• whether this is a single commit or part of a series
• the exact change, with supporting source evidence
• the supplied motivation, observations, assessments, and relevant history,

retaining their degree of certainty and who made relevant choices; identify supplied context separately from independently verified source facts; keep your inferences separate from the caller's actual claims

• whether the patch adds machinery or makes behavior run in a caller
• only the dependencies needed to explain the patch's design or scope
• the series goal as background, without assigning a role to its position
• the repository-specific message rules already discovered
• any preferred prefixes established by history
• the exact files staged for this commit

1. Tell it to inspect only what it needs, typically:

• git diff --cached --stat
• git diff --cached
• git log --pretty=oneline -- <path> for representative staged paths
• CONTRIBUTING.md when present
• .git/hooks/commit-msg when present

1. Require it to return:

• one proposed commit message
• a short checklist confirming the prefix, declarative body prose, necessary

reasoning, and the particular fact each cross-commit reference explains

• any specific uncertainty about source evidence or supplied context

The shared commit-message-drafter asset is the canonical source for those constraints. Do not activate another skill solely for message isolation; spawn a subagent and inline the needed briefing instead.

Review the draft in the main skill before committing. If it no longer matches the staged diff or repository rules, fix it in the main skill rather than pushing the problem back to the user.

Before committing, edit the draft into one alternative using the same source evidence and supplied context. Keep the first body sentence as a longer, non-imperative version of the summary. Preserve the intended behavior, supported judgments, actual uncertainty, and necessary scope.

Edit the summary and its expanded first sentence too when their wording hides the action in an abstract label. Keep the expanded sentence first, and use it to state the actual change in ordinary words.

After that opening, edit as if a colleague has asked why we need the change. Put the action or need in ordinary verbs. Let a short judgment stand on its own. Remove a sentence that merely labels the change or repeats a consequence the surrounding prose already makes clear. Keep inspection notes in CHECKS.

Compare the reasoning and how naturally it is expressed. A wording improvement may keep every fact and causal step unchanged; it does not need a new reason or extra detail to earn its place. Preserve useful causal links instead of replacing them with a list of operations. Check local references from the prose alone. Unpacking an unexplained reference is a real improvement even when it takes more words. A descriptive label or a related word used earlier does not establish its meaning. Prefer stating the condition and action when that saves the reader from having to reconstruct the relationship. Keep the original if the alternative is less natural, loses needed reasoning, or offers no improvement. Let difficult interactions take room and direct reasons stay brief. Length, contractions and first person do not decide which version is better.

Repeat the edit-and-compare step using the best version so far. Make at most three comparisons in total, including the first. Stop after two consecutive comparisons offer no clear improvement. Keep wording that already works; an extra comparison does not require accepting an edit. Fix factual errors and repository-rule violations before committing, regardless of that limit.

Write and choose in the main skill's existing review. The comparison is internal; use the selected message for the commit.

Verify the final wording with the accuracy check in the writing guidance below before committing. Repeat that check after any further wording edits.

Commit Message Shape

Follow repository-specific rules first. If no repository guidance overrides this, use:

prefix: Summary under 72 chars
 
[A plain-language statement of the changed behavior, followed by the
concrete old behavior and how the change addresses it. Use declarative
narrative present tense and the explanation the reader needs.]

Explain the Change

The first body sentence is a longer, non-imperative version of the summary line. State the same change in plain language as an indicative, declarative sentence, with enough detail to make the outcome clear. Keep that opening before the background and reasoning.

Explicitly attribute newly introduced behavior to the current commit, using This commit ... or an equally clear construction. Describe existing behavior in present tense from the state before the patch. Leading with the outcome does not change that temporal viewpoint. For example, This commit adds pattern matching to the command identifies the patch as the cause; The command now accepts patterns can blur the change with the status quo.

Use straight quotes and apostrophes in commit message prose. Avoid em dashes. Use commas, parentheses, or separate sentences where needed.

In prose, prefer periods to semicolons.

After the opening, explain the decision as you would to another maintainer who has not investigated the problem. Use ordinary verbs and familiar terms, with contractions when they fit. Let the reader follow the thought: a reasonable assumption, the catch, and the consequence that makes the change worth doing. Include those turns when the reasoning needs them; a direct fix may need only its direct reason.

Match the firmness of each claim to its basis. State a demonstrated failure, unnecessary restriction, or supported cost plainly. Preserve uncertainty about people's behavior, predictions, and design judgments where the evidence leaves room. A message can explain the code confidently and qualify an inference about its users in the next sentence.

State established behavior directly, with the condition that matters. Use "can" or "may" for meaningful capability, contingency, or uncertainty, not automatic precision. Check changed implications against the evidence.

Write decisions from inside the project. When relevant context explains who made an earlier choice and why, retain that ownership and reasoning. "We" can describe a shared decision or need; a component name is often clearer for an operation. First person does not establish personal experience or project history that the evidence does not supply.

Caller-supplied motivation, observations, assessments, and relevant history can explain the change even when absent from the diff. Carry their meaning and degree of certainty through the drafting handoff. In the message, combine clarifications that explain the same fact. Include history when it helps explain the present decision. Keep provenance and verification limits outside the commit message. Report contradictions with source there and avoid relying on a contradicted account as fact. Never claim independent verification merely because context was supplied.

Supplied context establishes meaning, not a list of points to cover. Treat a wording clarification as a constraint on the relevant claim. Do not turn it into a separate explanation of a hypothetical misunderstanding.