commit-message - SKILL.md Agent Skill

name: commit-message description: Conventions for drafting git commit messages. Load when asked to write a commit message, draft a commit, or run `git commit`. Covers subject-line bracket prefixes, NFC tagging, line-length and wrapping rules, imperative mood, body content focused on the why, and trailers like rdar:// references and `Assisted-by: Claude`.

Commit messages

Draft commit messages in this format. Do not run git commit — output the message and let the user commit. Commit signing prompts a GPG pinentry that hangs Claude Code.

Workflow

Run git status and git diff --staged (or git diff if nothing is staged) to see the actual change.
Run git log -n 10 --oneline in the same repo to match the local prefix conventions (component tags differ between repos — [lldb], [clang], [DWARFLinker], etc.).
Draft subject + body following the rules below.
Present the message to the user. Do not commit.

If the staged diff spans multiple unrelated logical changes, say so and suggest splitting before drafting — one logical change per commit.

Subject line

Format: [component] Imperative summary

Bracket prefix identifies the subsystem. Match what git log in the current repo uses.
One thing per bracket pair. Never [lldb, CMake]. Use separate pairs when nesting is genuinely needed: [lldb][CMake]. Prefer a single pair when one suffices.
Aim for 50 characters, hard cap ~72 including the bracket prefix. GitHub will append (#NNNNN) on squash-merge — that does not count against the limit.
Imperative mood, present tense. "Add", "Fix", "Support" — not "Added", "Fixes", "Adding".
Sentence case for the first word after the bracket. Capitalize proper nouns and identifiers as written in code.
No trailing period.
(NFC) suffix for non-functional changes (refactors, renames, comment-only, formatting). Use (NFCI) when the change is intended to be non-functional but you can't fully prove it (e.g. threading a parameter that should not change behavior). The suffix goes at the end of the subject, before any PR number.

Examples (good):

[lldb] Assert that CommandObject::DoExecute sets a return status
[lldb-dap] Make lldbDAP an OBJECT library (NFC)
[DWARFLinker] Emit DW_IDX_parent in the accelerator table
[lldb][CMake] Force OBJECT libraries to also be STATIC

Anti-patterns:

[lldb, dap] Fixed bug — comma-listed tags, past tense, vague.
Updates the linker to handle Swift modules. — no bracket, third-person, trailing period.
[lldb] Refactor — too vague; say what was refactored and how.

Body

Optional but usually present. Separate from the subject by one blank line. Wrap at 72 characters.

What goes in the body:

Why the change is needed. The diff shows what changed; the body explains motivation: the bug being fixed, the constraint being satisfied, the user-visible problem, the prior commit being undone.
Non-obvious context. Spec references, the alternative approach considered and rejected, an interaction with another commit, a follow-up that's coming.
Concrete observable evidence when it clarifies the problem — short transcripts of confusing output, an error message, a code snippet showing the bug. Use fenced blocks.

What stays out:

Restating what the diff already shows line by line.
Marketing language ("greatly improves", "robust", "comprehensive").
TODOs that belong in tracker tickets.

Imperative mood and present tense apply in the body too: "Pass STATIC alongside OBJECT so..." not "Passed STATIC...".

Trailers

Place at the end of the body, separated by one blank line. One trailer per line.

rdar://NNNNNNNNN — Apple-internal Radar reference, only include when the change is explicitly tied to a Radar.
Assisted-by: Claude — when Claude materially helped author the change (drafted code, designed the approach). Omit for purely mechanical assistance.
Fixes #NNNNN / Closes #NNNNN — only when the change actually closes a public GitHub issue.

Do not add Co-Authored-By: Claude or any other Claude attribution beyond Assisted-by: unless the user asks.

When the body should be empty

A bare subject is fine for changes whose subject is fully self-describing and whose motivation is obvious from the diff (mechanical fixes, test updates after a rename, reverting a clearly-named commit). When in doubt, write the body.

Output format

Return the message in a fenced block so the user can copy-paste:

[component] Imperative summary

Body paragraph explaining why, wrapped at 72 columns. Reference
prior commits by short SHA when relevant (e.g. a5a13ca29186).

rdar://NNNNNNNNN
Assisted-by: Claude

Do not prepend "Here is the commit message:" or similar — just the block.