dev-git-commit-message

Git Commit Message Generator

Default posture: subject line first; body only when risk, rationale, or breaking-change detail is needed; standard types only unless the repo already defines custom ones; never claim behavior not visible in the diff.

Rule: rules/common/git.md loads this invariant in every coding session.

Quick Reference

Need	Default	Reference
Pick a type	feat/fix/perf/refactor/docs/test/build/ci/chore/style/revert	Type Selection table below
Format a subject	type(scope): imperative summary, ≤72 chars (50 ideal), no trailing period	Repo Policy Checks below
Mark a breaking change	! after type/scope, or a BREAKING CHANGE: footer	Breaking Change Format table below
Decide on a body	Only for risk, non-obvious rationale, or breaking-change detail	Body Required? table below
Handle AI-authored commits	No attribution in subject or body; Assisted-by: trailer is the default, Claude-Session: and Audit-* also accepted	AI-Authored Commits below
Pick a release/changelog tool	release-please for reviewed PR releases; semantic-release for full automation; changesets for monorepos	references/changelog-generation-guide.md
Scope a monorepo commit	package/app/service directory name, one level deep, stable over time	references/monorepo-commit-conventions.md
Validate a message locally	python scripts/commit_validator.py validate --message "..."	Scripts section below

Decision Tables

Mode Selection

Trigger	Mode	Action
User provides staged diff or asks to commit	Generate	Inspect staged surface, produce primary + alternatives
User provides an existing message string	Validate	Check rules, return PASS/WARN/FAIL + exact rewrite
Staged diff mixes unrelated areas	Split	Recommend split commits before generating
No staged changes	Stop	Report "no staged changes"

Type Selection

feat and fix have SemVer meaning in the specification; other types and release behavior depend on the repository's tooling. Read its preset and release rules before claiming a bump. Scope and style rules below are local defaults, not requirements of the specification.

Change	Type	Notes
New user- or API-visible capability	feat	Triggers MINOR bump
Incorrect behavior corrected	fix	Triggers PATCH bump
Measurable speed or memory improvement	perf	PATCH with semantic-release's default rules; verify repo rules
Structure improved, behavior unchanged	refactor	No release by default
Documentation only	docs	No release by default
Tests only	test	No release by default
Build tooling or packaging	build	No release by default
CI/CD workflow	ci	No release by default
Repo hygiene, no product change	chore	No release by default
Whitespace or formatting only	style	No release by default
Reverting a prior commit	revert	Release effect is tool-specific; the spec leaves revert handling open
Security fix	fix(security):	Prefer standard type + scope over custom security: type
Prompt/skill/YAML behavioral change	feat or fix	Do not classify by file extension alone

Scope Selection

Situation	Action
Repo has a scope map in config.yaml	Use mapped scope
One directory or package clearly dominates	Use that name, lowercase kebab-case
Change spans 2+ stable areas equally	Use broader parent scope or omit
Repository-wide change	Omit scope
Monorepo with independently versioned packages	See references/monorepo-commit-conventions.md

Body Required?

Condition	Include body?
Subject is self-explanatory	No
Reason is non-obvious from subject	Yes — one sentence why
Security-sensitive or risky change	Yes — risk/rollback note
Breaking change	Include migration detail when needed; ! alone is valid if the subject describes the break
Caller requests detailed template	Yes — use assets/template-commit-message.md

Breaking Change Format

Signal	Format
Inline marker	feat(api)!: change auth to OAuth2
Footer	BREAKING CHANGE: <migration summary>
Both	Acceptable; footer body gets the detail

Before/After Examples

BAD:  update
GOOD: docs(readme): add deployment instructions

BAD:  fix stuff
GOOD: fix(cart): prevent negative quantity on rapid add

BAD:  feat: added user dashboard (past tense)
GOOD: feat(dashboard): add analytics overview panel

BAD:  feat: add search (generated by Copilot)
GOOD: feat(search): add full-text product search

BAD:  feat(api): add comprehensive user search endpoint with full-text search across all profile fields including bio and location
GOOD: feat(api): add full-text user search endpoint

BAD:  feat: add dashboard, fix auth bug, update deps  (mixed concerns)
GOOD: (3 separate commits)
      feat(dashboard): add analytics overview panel
      fix(auth): correct token refresh race condition
      chore(deps): update react to 18.3.0

Workflow

1. Decide mode from the Mode Selection table above.
2. For generate mode, inspect staged changes in this order:
   • git diff --staged --name-status
   • git diff --staged --stat
   • git diff --staged --unified=1 only when type, scope, or risk is ambiguous
3. Classify type and scope using the tables above.
4. Detect scope from config.yaml first, then from the nearest stable directory.
5. Generate: one primary suggestion, up to two alternatives when scope or emphasis is ambiguous, short rationale.
6. Validate: apply Repo Policy Checks, return PASS/WARN/FAIL with exact rewrite on failure. The bundled validator checks its defaults; review target-repository overrides separately.
7. If the diff mixes unrelated work, recommend split commits before offering a combined message.

Index is the commit boundary

Generate the message from the staged diff, not the working-tree diff. Before writing, inspect git diff --cached --name-status and git diff --cached; separately inspect git diff --name-status so unstaged edits cannot leak into the summary. If the index is empty, stop instead of describing uncommitted work. If a file is partially staged, describe only the staged hunks and flag that the same path has remaining unstaged changes.

For generated files, lockfiles, and migrations, name the behavioral change that caused them rather than listing them as independent accomplishments. Validate the proposed subject against the staged patch again immediately before commit because the index can change between drafting and execution.

Output Contract

Generate

[NOTE] Suggested commit messages (3 files changed)

PRIMARY:
fix(auth): reject expired refresh tokens

ALTERNATIVES:
1. fix(api): reject expired refresh tokens
2. fix: reject expired refresh tokens during rotation

RATIONALE:
- Type: fix
- Scope: auth
- Signals: token validation path, regression test update, no new feature surface

Validate

VALIDATION: WARN

Message:
feat: update stuff

Issues:
- `update stuff` is too vague
- summary should name the changed behavior or surface

Suggested fix:
feat(auth): add refresh token rotation

AI-Authored Commits

The commit message describes the change, not the tool that produced it. Apply the same rules regardless of whether a human or an AI agent drafted the code.

Banned in subject and body prose: generated by, via copilot, via claude, chatgpt, ai assistant, bot. Attribution belongs only in the final trailer block.

When AI-assisted work needs an audit trail, the recommended default is an Assisted-by: trailer. Co-authored-by: <ai-tool> is not the default and still fails validation. Keep trailers out of the subject line. Example:

feat(search): add full-text product search

Assisted-by: LLM

Accepted AI trailers, all in one final paragraph with no blank line between them:

• Assisted-by: recommended default; the kernel form lists tools after the model (Assisted-by: LLM coccinelle sparse)
• Claude-Session: a session link some agent runtimes append
• Audit-* (for example Audit-Batch: and Audit-Skill:) audit-program provenance

Any other trailer that names an AI tool fails. Trailers placed in an earlier paragraph are invisible to git interpret-trailers, so the validator warns.

Use the exact format the target project documents; formats differ between projects. Assisted-by: is a distinct trailer from Co-Authored-By:. Upstream projects have not converged on one format, and their policies change, so read the target project's current contribution policy before adding any AI trailer. Policies worth checking: the Linux kernel's coding-assistants document (an Assisted-by: trailer listing the LLM and tools; AI agents must not add Signed-off-by:, because only a human can certify the DCO), LLVM's AI tool policy (Assisted-by: given as an example trailer), Apache's generative-tooling guidance (Generated-by:), and QEMU's code-provenance policy (declines AI-generated contributions). If a repo already uses Co-Authored-By: <ai-tool> by convention, do not silently rewrite it to Assisted-by: — flag the distinction and let the maintainer choose; changing trailer conventions after history exists breaks blame/provenance tooling that greps for the old trailer.

Repo Policy Checks

Block or rewrite messages that:

• omit the type prefix (unless the repo's convention is plain imperative subjects, as its contribution guide or AGENTS.md states; then generate Imperative summary with no prefix and validate with --no-type-prefix, which skips only this rule)

• omit the space after : or use an empty scope; scope defaults to lowercase kebab-case

• use vague summaries: update, fix stuff, change code, WIP, misc

• include assistant/tool attribution outside the accepted trailers (see above)

• overstate impact not visible in the diff

• use past tense or gerund after the type prefix

• exceed 72 characters on the subject line

• end the subject line with a period

• Mark breaking changes with !, BREAKING CHANGE:, or BREAKING-CHANGE:; a footer is optional with !.

• Conventional Commits v1.0.0 is the referenced specification.

• commitlint's supported Node range and config format change between major versions; check its docs (see data/sources.json) before writing a config file.

• For legacy standard-version setups, read its repository notice before proposing migration; it points to release-please or the community fork commit-and-tag-version.

• release-please-action ships breaking major versions (runner-runtime and input changes). Check its releases page for the current major and its runtime requirement before pinning a workflow, and pin by commit SHA.

• Do not cite a major version for semantic-release or any release tool from memory; check its releases page first.

Scripts

Script	Purpose
scripts/commit_validator.py	Validate a single message, lint a history file, or generate a Markdown quality report

# Validate one message
python scripts/commit_validator.py validate --message "feat(auth): add refresh token rotation"

# Lint a batch history file
python scripts/commit_validator.py lint --input data/sample-commit-history.json

# Generate a full Markdown report
python scripts/commit_validator.py report --input data/sample-commit-history.json --output report.md

See scripts/README.md for the full quick-start, input format, and rule reference.

History input must be a nonempty array of objects with a string message; optional hash, author, and date must also be strings. Both history commands reject empty input and malformed records before producing output; file errors name the input or output path. The validator uses bundled policy defaults and does not load config.yaml.

Worktree PR Loop

Use this skill as the commit step inside the broader worktree-first delivery loop defined by ../dev-git-workflow/SKILL.md.

In that loop: create or enter feature worktree → make code changes → stage intentionally → use this skill → run repo gate → open PR.

If the staged diff mixes several unrelated surfaces, stop and recommend split commits before the PR step.

Known Traps

• Inferring scope from filenames alone, producing scopes that do not match the repo's bounded-context map.
• Compressing unrelated changes into one "clean" conventional commit, destroying revert and release-note usefulness.
• Treating AI-generated summaries as authoritative when the diff still contains hidden migrations or breaking changes.
• Optimizing for lint-pass format while losing the operational intent maintainers need for incident archaeology.
• Using ! or BREAKING CHANGE casually and creating noisy downstream automation.

Navigation

• config.yaml — repo-specific scope mapping and validation defaults
• assets/template-commit-message.md — optional detailed body template for complex commits
• assets/template-security-commits.md — wording guidance for security-sensitive commits
• references/conventional-commits-guide.md — full spec v1.0.0, type definitions, breaking changes, tooling setup
• references/commit-message-antipatterns.md — anti-pattern catalog, regex detection patterns, commitlint config, CI examples
• references/monorepo-commit-conventions.md — scope strategy, per-package changelog generation, affected-package CI routing
• references/changelog-generation-guide.md — release tooling comparison (standard-version is deprecated; default to release-please for GitHub release PRs, changesets for per-package monorepo changelogs)
• data/sources.json — curated primary sources for tool verification
• data/sample-commit-history.json — 20-commit sample dataset for lint and report subcommands
• Related: ../dev-git-workflow/SKILL.md — branching, hooks, PR workflow, release automation; use dev-git-workflow for branching/PR strategy, this skill for commit-message standards

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.