Git Commits

Git Commits

Write clear, structured commit messages that explain what changed and why.

Goal

Help readers and tools quickly understand commit intent, impact, and context.

Canonical rules table

Use this table as the single source of truth.

| ID | Scope | Requirement | | -------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FMT-1 | Message shape | Commit message MUST follow: [optional scope]: , optional body, optional footer(s), with blank lines between sections. | | FMT-2 | Allowed types | Type MUST be one of: feat, fix, docs, refactor, chore, revert. | | FMT-3 | Header length | Header SHOULD be with migration impact. | | FMT-6 | Scope | Scope is optional and SHOULD be used when it improves clarity. | | FMT-7 | Unsupported type requests | If the requested type is outside the allowed set, output MUST map to the closest allowed type. In rewrite and review modes, output MUST explicitly explain the mapping; in draft mode, explanation SHOULD be omitted unless the user asks for rationale. | | FMT-8 | Non-subject line length | Every commit message line after the header SHOULD be trailers when multiple people co-authored the change. | | REV-1 | Reverts | revert commits SHOULD repeat reverted header and body SHOULD include This reverts commit . | | HYG-1 | Atomicity | Commits SHOULD be small, logical, and atomic; avoid mixing unrelated changes. | | HYG-2 | Whitespace changes | Significant whitespace-only changes SHOULD be in a separate commit. | | HYG-3 | Tests | If code changes require test updates, include test updates in the same commit. |

Semver intent by type

• feat -> minor version intent
• fix -> patch version intent
• docs -> patch version intent
• refactor -> no release bump intent
• chore -> no release bump intent
• revert -> depends on reverted change impact

Input model

[optional scope]: 

[optional body]

[optional footer(s)]

Output contract

Choose exactly one mode based on user intent:

1. draft

• Output only one final commit message, ready to paste into git commit.
• Do not add explanatory prose unless the user explicitly asks for explanation.

1. rewrite

• Output one rewritten commit message first.
• Then provide a short Why this is better list focused on violated rule IDs.

1. review

• Output Findings first, ordered by severity and linked to rule IDs.
• If fixes are needed, include Proposed message after findings.

Unsupported type mapping

If a user asks for a non-supported type, keep the intent but map to allowed types:

• feature -> feat
• bugfix, hotfix -> fix
• perf -> refactor
• style, test, ci, build -> chore

When mapping is used in rewrite or review, explicitly state: Mapped requested type to to satisfy FMT-2.

Type compatibility with other skills

• This skill enforces a strict output type set (feat, fix, docs, refactor, chore,

revert) per FMT-2.

• This restriction applies to messages authored/rewritten by this skill, not to historical commits

that may already use broader Conventional Commit variants.

• The common-changelog skill MAY ingest broader input types from history (perf, style, test,

ci, build) and classify them for changelog purposes.

Authoring workflow

1. Identify the smallest logical change set; recommend split commits if input is too broad.
2. Choose type (and optional scope) by user impact.
3. If requested type is unsupported, apply Unsupported type mapping.

Explain mapping in rewrite/review; in draft, explain only when user asks for rationale.

1. Draft concise imperative subject.
2. Add body only when extra context is needed; explain why and behavior delta.
3. Add footers/trailers (See:, Co-authored-by:, BREAKING CHANGE:) as needed.
4. Run Quality checklist.

Quality checklist

• Validate all applicable FMT-*, BODY-*, FTR-*, REV-*, and HYG-* rules.
• Ensure final message is copy-paste ready for git commit.
• Ensure unsupported type requests are mapped and explained when required by output mode.
• For detailed conventions and more examples, verify against references/git-commit.md.

Prompt templates

• Write a Conventional Commit message for these staged changes.
• Rewrite this commit message to follow Conventional Commits and explain why your version is better.
• Split this change into 2-3 atomic commits and propose a commit message for each.

References

• references/git-commit.md (local detailed guide and examples)
• https://conventionalcommits.org
• https://git-scm.com/docs/git-interpret-trailers

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: octivi
• Source: octivi/skills
• License: MIT

Install and usage instructions live in the source repository linked above.