dev-git-commit-message

Git Commit Message Generator

Generate or validate Conventional Commits for the staged surface.

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.

Quick Reference

Decision Tables

Mode Selection

Type Selection

Scope Selection

Body Required?

Breaking Change Format

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, missing scope)
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

Pre-Commit Message Checklist

• Starts with a valid type prefix (feat, fix, docs, test, refactor, perf, build, ci, chore, style, revert)
• Subject is 72 characters or fewer (50 preferred)
• Imperative mood: "add" not "added", "fix" not "fixing"
• No trailing period on subject line
• Scope, if used, matches repo conventions (lowercase kebab-case)
• Single logical change; unrelated concerns split into separate commits
• No tool/assistant attribution in subject or body
• No generic placeholders: "update", "fix stuff", "WIP", "misc"
• Breaking changes marked with ! or BREAKING CHANGE: footer
• Body present only when needed; answers "why", not "what"

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: run all checklist items, return PASS/WARN/FAIL with exact rewrite on failure.
7. If the diff mixes unrelated work, recommend split commits before offering a combined message.

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: generated by, co-authored-by: <ai-tool>, via copilot, via claude, chatgpt, ai assistant, bot.

If your team requires an audit trail for AI-assisted code, add an Assisted-by: trailer as an opt-in team policy (not a default). Keep it out of the subject line. Example:

feat(search): add full-text product search

Assisted-by: claude-sonnet-4-6

This is an organizational opt-in pattern, not a general requirement. The default rule remains: no attribution.

Assisted-by: is a distinct trailer from Co-Authored-By: — several large open-source projects (Linux Kernel, Apache Software Foundation, LLVM, QEMU) have converged on Assisted-by: through 2026 specifically because Co-Authored-By: implies authorship/copyright standing that an AI tool cannot hold or sign a CLA for. 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
• use vague summaries: update, fix stuff, change code, WIP, misc
• include assistant/tool attribution (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

Scripts

# 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.

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 (current stable), 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 deprecated since 2022; prefer release-please or changesets)
• 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

Fact-Checking

• Conventional Commits spec is v1.0.0 (stable as of July 2026; no v2 released).
• commitlint is at v21.x (21.2.1 as of July 2026); requires Node 22+; config uses ESM (export default { extends: [...] }).
• standard-version is deprecated, not archived — the repo carries a deprecation notice pointing to release-please (GitHub-native) or the community fork commit-and-tag-version. Do not recommend it for new projects either way.
• release-please-action is at v5 (Node 24 runtime, April 2026 breaking change); the underlying release-please package is at v17.x. Re-check the major tag before pinning a workflow — this skill will drift again.
• semantic-release is at v25.x as of mid-2026 and actively maintained (recent work adds npm trusted publishing).
• For current tooling, hook behavior, or release-automation recommendations, verify against primary sources in data/sources.json and use web search when available — pinned major-version numbers in this skill are a snapshot, not a guarantee.
• If browsing is unavailable, mark volatile tool guidance as unverified.

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

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.