Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

commit-message

Git commit message conventions: structure, formatting, scoping, body content, breaking changes, trailers.

xobotyi · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add xobotyi/cc-foundry --skill commit-message

About this skill


name: commit-message description: >- Git commit message conventions: structure, formatting, scoping, body content, breaking changes, trailers. when_to_use: >- Invoke whenever a commit message is touched at all — writing, reviewing, validating, amending, or correcting one the validator rejected. Also invoke on the symptoms: a body that walks the reader through the new code, a subject that sells the change, a message that records the test results of the session. Covers the message text; splitting the work into units belongs to the commit skill. user-invocable: false compatibility: Uses Claude Code frontmatter beyond the Agent Skills spec (when_to_use, user-invocable)

Commit Message Format

A commit message is a factual record of one change. It tells the reader why the change happened. The reader has the diff and the docs. The message adds only what the diff and the docs cannot show.

What Makes a Good Message

Structure

[scope] subject

body

trailers
  • Subject — what changed.
  • Body — the reason for the change, and the procedure that verifies it.
  • Trailers — structured metadata such as references and authorship.

ASCII Symbols

  • No em dash and no en dash (—, –). Use -- or -.
  • No arrows (→, ←, ↔). Use ->, <-, and <->.
  • No bullet symbols (•, ▸). Use - or *.
  • No fancy quotes (“”, ‘’). Use straight quotes.
  • No emoji (🐛, ✅, 🚀), unless the project conventions make them necessary.
  • No other decorative symbols (©, ™, §, ¶, ∞).

Some environments break these symbols, and the symbols add no information.

Subject Line

  • With a scope, for a monorepo: [scope] <verb> <description>
  • Without a scope, for a single-purpose repo: <verb> <description>

Scope (Optional)

  • [parser] — a top-level project
  • [core/auth] — a nested path
  • [web/api] — a component in a project

Derive the scope from the file paths, not from the file contents. Use the common parent directory, or the most significant component that you changed. Use one spelling for one component. [myapp/backend] and [myapp/b] in the same log break the filtering that the scope exists for.

A path can hold a version directory such as v2. Omit the segment while one version is alive: write [core/engine], because the reader has one candidate. Write [core/engine/v1] and [core/engine/v2] when both versions are alive, because the segment is then the distinction that matters.

Body

  • Why the change was necessary.
  • What the subject cannot hold, such as a behavior change that surprises the reader.
  • How a reader verifies it later, when that is not obvious. Give the steps that the reader repeats (run X, confirm Y). Never give the results that you produced in this session.

Wrap each body line at 72 characters. This is a hard limit. Git tools such as log, format-patch, and email expect 72-character body lines. Trailers are the only exception.

Shape

Each paragraph after the first earns its lines, or it goes. A paragraph earns its lines when it records a fact that the diff and the docs cannot show:

  • A second reason that the first paragraph does not carry.
  • A BREAKING: declaration, or a step of the migration path.
  • A behavior change that the subject cannot predict, such as the new meaning of an absent value.
  • A one-line note about the work that follows in the chain. Name that work. Do not write "more changes coming".

The reason itself depends on the kind of change:

  • A bug fix — why the defect existed, not only what you corrected.
  • A feature — the use case.
  • A refactor — the motivation.
  • A breaking change — the migration path.

The length follows the number of reasons, not the size of the diff. A refactor of 2000 lines with one reason gets one paragraph. A migration with 6 steps gets the 6 steps. A body of 20 lines is correct only when 20 lines of reasons, declarations, and steps exist. Such a body usually holds a walkthrough, or a second unit that belongs in its own commit.

More than one behavior change. One unit can change several behaviors. Give one line to each change, in one list. Do not give a paragraph to each change:

- <behavior that the caller sees, present
Read the complete source ↗