Git Commit Message

Git commit messages

Caller mode: commit by default, pr-title when requested by create-pull-request, or draft for message-only requests.

Convention precedence

1. Current user request
2. Target repository AGENTS.md, CLAUDE.md, contribution docs, and tooling
3. First and subsequent commit defaults in this skill
4. Dominant style in recent relevant history

Always inspect branch history before composing a message. Repository rules override this skill when they require a different format.

Conventional Commits

The type(scope): prefix in this skill is a default, not a requirement. Repository rules outrank it.

Before composing any subject, confirm the repo's stance:

1. Check AGENTS.md, CLAUDE.md, if not loaded yet, and contribution docs already in context. A repo that bans the prefix usually says so explicitly
2. Nothing in context: run git log --oneline -3 and read the subjects
3. History uses type(scope):: apply the prefix. History uses bare imperative subjects: do not

Keep the result in context for the rest of the session. Do not re-run git log for the same repository.

Hard rules

• Never commit without an explicit user request
• Permission applies to one commit action; autonomous mode does not waive the gate
• Never rewrite history: no git rebase, commit --amend, push --force, or --force-with-lease
• Never use git checkout, git revert, or git reset to undo existing work
• Treat branch history as disposable because PRs squash-merge; push it as-is

Current state is authoritative

• Derive the commit from the actual index and working tree at commit time
• Treat plans, task file lists, and earlier status snapshots as intent only
• Read full diffs; filenames and diff statistics are insufficient
• If the index contains changes, compose for the staged diff only
• If the index is empty, select paths from current changes and the requested scope
• If the staged set differs from the requested scope, stop the commit workflow until the set or requested scope is corrected
• Do not add unrelated staged or unstaged changes
• Recheck status and the staged diff immediately before committing
• Regenerate the message and commands when the commit set changed

Branch position

Resolve the base branch and run git rev-list --count <base>..HEAD before each commit:

• Count 0: the next commit is the first commit; use the strict format below
• Count greater than 0: use the subsequent commit format below
• On main or master: treat each commit as a first commit

Read recent target-branch subjects and all existing feature-branch commits. Use them for context and to avoid repeating intent. Do not let later commits override the first-commit format.

First commit format

Resolve the Conventional Commits question above before using this format. A repo that bans the prefix uses a bare imperative subject with the same body rules.

type(scope): subject

Explain why the change matters and its impact.

- Describe reviewer-relevant behavior
- Call out important constraints or decisions

• Subject: imperative, lowercase after the colon, no more than 72 characters in total
• Body: use concise prose, bullets, or both
• Prefer a bullet when it conveys the same fact with fewer words
• Paragraphs: no more than 25 words each
• First paragraph: state only context that is clearer than a bullet
• Second paragraph: add only mandatory, important information not captured in the first paragraph or bullets
• Never add a second paragraph for padding, hedging, or unnecessary explanation
• Third paragraph: add only mandatory, important information not captured in the first two paragraphs or bullets
• Put one blank line between paragraphs and before the bullet list
• Keep bullet items consecutive, without blank lines between them
• Bullets: no more than 10 words
• State each fact once: in prose or a bullet, never both
• Omit standard, expected, or self-evident information
• Omit verification, test commands, pass claims, commands, and tool output
• Body lines: wrap at about 72 characters per line for readability; this is a stylistic per-line guide, not a total body character limit
• Standard Markdown only: no em-dashes, curly quotes, or special characters
• Single-change commit: subject only

Type

Infer the type from the diff. Ask when the type is unclear.

Common types: feat, fix, refactor, docs, test, chore, perf, build, ci, and style.

Scope

Use this priority:

1. User-provided scope
2. Repository convention
3. Jira key matching [A-Z]{3}-[0-9]+ from the branch name
4. Branch name, excluding main and master
5. Affected module or folder

Ask when no scope is available. Do not force a scope when repository rules ban one.

Subsequent commit format

• Bare imperative subject only
• No type(scope): prefix
• No body
• No more than 72 characters
• One change per commit

GitHub references

Put issue and PR references in body bullets:

• Resolved issue: Fixes #123
• Superseded PR: Closes #456
• Non-closing link: Related: #789
• Cross-repository link: org/repo#123

Use closing keywords only when the commit resolves the referenced work.

Composition

• Describe the coherent change represented by the commit
• Use issue-closing syntax only when the commit resolves that issue
• Include required sign-offs or trailers only when the target repository or user requires them
• Use branch history to avoid repeating intent already captured by earlier commits

In pr-title mode, compose the squash commit title for the complete branch change. Apply the first-commit subject, type, and scope rules. Do not copy the last commit blindly.

Commit templates

A repository template outranks the formats in this skill. Check once per repository, before composing:

git config --get commit.template

A path means the repo ships a template. Read it and follow its structure, section order, and required trailers.

No commit.template setting: check the standard locations GitHub and most tooling use.

• .gitmessage or .gitmessage.txt at the repository root
• .github/.gitmessage
• .github/COMMIT_TEMPLATE.md
• .github/commit_template.txt

Commented lines starting with # are instructions to you, not message content. Strip them from the final message.

Keep the result in context. Do not re-check for the same repository.

Workflow

Commit mode

1. Read target repository instructions, commit template, and detected commit tooling
2. Resolve the base branch, count branch commits, and read commit history
3. Inspect git status, staged changes, unstaged changes, and untracked paths
4. Resolve the exact commit set from current state and requested scope
5. Read the full diff for that set
6. Compose the message for its branch position
7. Show the exact message and commands, then get approval
8. Recheck status and the staged diff after approval
9. Run the approved staging and commit commands with the message unchanged
10. Use git commit -F- with a quoted heredoc for multiline messages

Never emit placeholder paths or reuse a file list copied from a plan. Omit the staging command when the intended commit set is already staged. Shell-quote every actual path and message for the active shell.

PR-title mode

1. Read the same target-repository convention sources
2. Resolve the PR base branch and current branch name
3. Read the complete branch diff and commit range against that base
4. Resolve type and scope from the complete branch change
5. Return only the squash commit title

Do not select index paths or generate staging or commit commands in this mode.

Commit message file

When .git/COMMIT_EDITMSG is selected:

• Use the verbose diff already present in the file
• Ignore spell and lint findings in generated diff content
• Replace only the message section at the top
• Do not run git commit

Draft mode

Return the message without running staging or commit commands.