SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdev-git-commit-message

dev-git-commit-message

General & other

View repository

Updated 10-15 23:41

About this skill

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

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.