conventional-commit

Conventional Commit

Purpose

Draft Conventional Commit messages that the user reviews and edits in their own git commit editor. Use this skill for staged changes, for rewording or amending the last commit, and for splitting uncommitted work into commits. Use fixup-plan for changes that belong in existing branch commits and pull-request for PR text.

Constraints

• Run only read-only commands: git status, git diff, git log, git show, git config lookups, and cz check. Never run git add, git commit, git stash, git restore, git reset, or anything else that changes the index, working tree, or history. The user signs commits with a hardware key and edits every message before committing, so they run those commands themselves.
• Run every git command as git --no-pager <command>. PAGER=cat is ignored when core.pager is set, and a pager blocks agent terminals.

Workflow

1. Gather context

Run these at the start of every invocation, even if they ran earlier in the session:

git --no-pager status --untracked-files=all
git --no-pager diff --cached --stat
git --no-pager log --no-merges --format=%s -30 --author="$(git config user.name)" --invert-grep --grep='^bump:'

Then run git --no-pager diff --cached. If --stat shows more than 500 changed lines, instead diff only the paths that inform the message with git --no-pager diff --cached -- <path>, and skip lockfiles, generated files, and vendored code.

• If the prompt already provides git status and diff output (for example, from a wrapper script) or says not to run commands, use the provided context and run no commands in any step.
• In a repository without commits, git log fails; continue without history.
• To read a staged file, use git --no-pager show :<path>; the working-tree copy may contain unstaged edits. Describe only changes that appear in the diff.

2. Select the mode

Use the first row that matches:

An empty staged diff means nothing is staged; it says nothing about whether the repository has commits.

• Staged: the staged diff is authoritative; ignore unstaged and untracked changes. If the staged changes match a group you proposed earlier in this conversation, reuse that group's message verbatim.
• Amend: the message must describe everything the amended commit will contain. Also run:

  git --no-pager log -1 --format=%B
  git --no-pager diff --cached HEAD~1

If HEAD has no parent, use git --no-pager show HEAD plus the staged diff instead. Treat the current message as a draft: keep what is accurate and correct the rest.

• Group: also run git --no-pager diff --stat and git --no-pager diff (for all changes, git --no-pager diff HEAD --stat and git --no-pager diff HEAD), read untracked files whose contents affect grouping or the message, then follow step 3.

3. Group changes

Group mode only:

1. Put changes in the same commit when reverting one without the other would leave the repository broken or inconsistent, such as a feature with its tests and docs. Otherwise, separate them.
2. Include untracked files; git diff does not show them.
3. When one file holds changes for more than one group, stage it with git add -p -- <shell-quoted-file> and name the hunks that belong to each group by their @@ header or enclosing function.
4. Order groups so each commit works on its own, prerequisites first.
5. If the grouping is genuinely ambiguous, ask one focused question before producing commands. If you cannot ask, use the fewest commits that satisfy rule 1 and state that assumption in one line.

4. Classify

Type. Decide in order:

1. If the change modifies code beyond comments (source, scripts, or AI instruction files such as prompts, skills, agent definitions, and *.instructions.md), classify by effect, not by file extension:

• feat: adds a capability
• fix: corrects wrong behavior
• perf: same behavior, faster or cheaper
• style: formatting or whitespace only
• refactor: same behavior, restructured

Tests, docs, and dependency changes that accompany the code do not change its type.

1. Otherwise, use the category of the primary change:

• test: tests only
• docs: human-facing documentation only, such as READMEs, guides, and code comments
• build: build system, packaging, dependency manifests and lockfiles, dev containers, and repository tooling config such as .gitignore, .editorconfig, linter and formatter config, and release config (.cz.yaml)
• ci: CI workflows, git and pre-commit hooks, Dependabot or Renovate config, and version bumps inside any of these

Never use chore. Mark a change as breaking only when existing users or consumers must change something: add ! before the colon and a BREAKING CHANGE: <what breaks and how to migrate> footer.

Scope. Optional; never more than one:

1. The scope used most often for the primary path in git --no-pager log -20 --format=%s -- <path>, or in the provided recent subjects when commands are not allowed. Use its most frequent spelling.
2. Otherwise, the component or directory name that best identifies what changed, such as parser or skills.
3. Omit the scope when the change spans several areas.

Match the wording and scope names of the recent subjects, but follow these rules where they disagree.

5. Write the message

• Header: type(scope): description, with ! before the colon for breaking changes.
• Keep the whole line at 72 characters or fewer, including type and scope; aim for 60.
• Use the imperative mood, a lowercase first word unless it is an identifier or proper noun, and no trailing period.
• State the primary purpose; do not list files.
• Body: add one only when the reason is not obvious from the header or there are two or more notable changes. Separate it from the header with a blank line and use - bullets, at most five, wrapped at 72 characters. Explain what changed and why, not file by file. Use no markdown headings, and start no line with #.
• Footer: only BREAKING CHANGE: and issue references such as Refs: #123 or Closes #123. Take issue numbers only from the user, the branch name, or the diff; never invent them. Never add Co-authored-by, Signed-off-by, or tool attribution trailers; GPG signing is not a sign-off.
• Validate: when commands are allowed, shell-quote the generated header as one argument and run cz check -m <shell-quoted-header>, revising the header until it passes. Skip this if cz is not installed.

6. Output

Use raw mode when the invoking prompt asks for it, for example a script that passes the output to git commit -F. Otherwise, use chat mode.

Chat mode

• Staged and Amend: output exactly one text fenced block containing the complete message: header, body, and footer. Output nothing else, except at most one line after the block, starting with Note:, when:
• the staged changes look like more than one logical change,
• a path has both staged and unstaged changes, or
• in Amend mode, git status says the branch is up to date with or behind its upstream, so amending requires a force push.
• Group: for each group, in order:

1. One line: Commit <n> of <total>: <why these changes belong together>, naming any partial-file hunks.
2. One bash fenced block with the staging commands: git add -- <shell-quoted-path>... for whole files and git add -p -- <shell-quoted-file> for selected hunks. Shell-quote every path as one argument using POSIX single-quote escaping, including paths without whitespace. When grouping all changes and the index is not empty, start Commit 1's block with git restore --staged -- :/.
3. One text fenced block with the complete message.

Never include git commit commands.

• Stop: one sentence stating the reason.

Raw mode

• Output the complete message as plain text: no fences, labels, notes, or commentary.
• Only Staged and Amend modes produce a message. In any other mode, or when no message can be drafted, output exactly one line: NO_COMMIT_MESSAGE: <short reason>.

Examples

Staged mode, chat mode:

fix(parser): handle empty quoted values

• treat "" as an empty string instead of a missing value
• add regression tests for empty and whitespace-only values

Group mode, chat mode:

Commit 1 of 2: the empty-value fix and its regression test; in `src/parser.py`, stage only the hunk in `parse_quoted()`.

git add -- 'tests/test_parser.py' git add -p -- 'src/parser.py'

fix(parser): handle empty quoted values

Commit 2 of 2: the remaining `src/parser.py` hunk renames an internal helper and is independent of the fix.

git add -- 'src/parser.py'

refactor(parser): rename tokenize helper to split_tokens

References

• Conventional Commits