playbooks

home / skills / dmitriiweb / extract-emails / git-commit-assistant

git-commit-assistant skill

/.codex/skills/git-commit-assistant

This skill generates high-quality conventional git commit messages and, with your approval, performs the commit to keep clean history.

npx playbooks add skill dmitriiweb/extract-emails --skill git-commit-assistant

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.2 KB
---
name: git-commit-assistant
description: Generate high-quality conventional git commit messages and, with user approval, run the commit. Use when drafting or refining commit messages, validating commit quality, or committing staged work while avoiding noisy histories.
---

# Git Commit Assistant

## Quick start
- Review staged changes and ensure they cover a single concern.
- Choose `<type>(optional-scope)` and write an imperative 50-72 character summary.
- Add body for why/decisions/trade-offs; footers for breaking changes or issue references.
- Show the message in a fenced code block, ask for approval to commit, then commit only if approved.
- See `references/commit_rules.md` for full rules and examples.

## Workflow
1) Inspect changes  
   - Check `git status` and `git diff --cached` to confirm what will be committed.  
   - If changes mix concerns or include formatting noise, ask to split or stage appropriately.

2) Select type/scope  
   - Allowed types: feat, fix, refactor, docs, test, chore, build, ci, perf, style.  
   - Scope is optional; keep it short (e.g., `api`, `auth`, `deps`).

3) Draft the message  
   - Summary: imperative, no trailing period, describe what/why, not implementation detail.  
   - Body (only if valuable): why the change was needed, key decisions, trade-offs; wrap to ~72 chars.  
   - Footers (when relevant): breaking changes, migration notes, issue references (e.g., `Closes #123`).

4) Quality gate  
   - Message intent must match the staged diff; avoid kitchen-sink commits.  
   - Do not mix formatting-only changes with functional work.  
   - Avoid noisy summaries like `update`, `fix stuff`, `changes`, `wip`.

## Confirmation and commit
- Present the message in a fenced code block and ask the user to accept.  
- On approval:  
  - Confirm staged changes are correct; surface unstaged items before committing.  
  - Run `git commit -m "<summary>"` with additional `-m "<body>"` / `-m "<footers>"` as needed.  
  - If the commit fails, report the error and pause for guidance.  
- If the user declines, revise the message or wait for more information.

## Reference
- `references/commit_rules.md`: conventional format, output pattern, quality gate, example output.

Overview

This skill generates clear, conventional git commit messages and, with your approval, runs the commit for staged changes. It enforces a quality gate so commits stay focused, descriptive, and machine-readable. Use it to draft, improve, or apply commits while avoiding noisy or mixed-history commits.

How this skill works

The skill inspects the staged diff and git status to determine what will be committed and whether changes represent a single concern. It proposes an imperative-summary, optional scope, body, and footers following conventional commit rules, presents the full message for approval, and only runs git commit after you confirm. If the commit fails or unstaged changes exist, it reports details and awaits further instructions.

When to use it

  • Draft a concise conventional commit for staged work.
  • Validate that staged changes match the intended commit intent and scope.
  • Split or refuse commits that mix formatting/noise with functional changes.
  • Run a vetted commit after reviewing the suggested message.
  • Enforce consistent commit formatting across a team or CI workflow.

Best practices

  • Stage only related changes; keep each commit to a single concern.
  • Write a 50–72 character imperative summary without a trailing period.
  • Include a short optional scope like api, auth, or deps when helpful.
  • Add a body only for rationale, decisions, and trade-offs; wrap lines ~72 chars.
  • Use footers for breaking changes and issue references (e.g., Closes #123).

Example use cases

  • You have staged code fixing an auth bug and want a well-formed commit message before committing.
  • A teammate submitted a mixed diff; use the assistant to detect and advise splitting concerns.
  • Prepare release commits with clear breaking-change footers and issue links for changelogs.
  • Automate message drafting in a pre-commit workflow while requiring human approval to commit.

FAQ

Will the skill commit without my confirmation?

No. The skill always shows the proposed message and asks you to approve before running git commit.

What commit types are supported?

Supported types include feat, fix, refactor, docs, test, chore, build, ci, perf, and style.

What if the commit fails?

The skill reports the git error and the staged/unstaged status, then pauses for your guidance or revision.

How does it handle mixed or noisy changes?

It flags mixed concerns and formatting-only noise, recommends splitting or restaging, and will not proceed until the commit intent aligns with the staged diff.