| name | atomic-commit |
| description | Compressed commit message generator. Cuts noise from commit messages while preserving intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why" isn't obvious. Use when user says "write a commit", "commit message", "generate commit", or invokes /atomic-commit. Auto-triggers when staging changes.
|
- "write a commit", "commit message", "generate commit"
- Staging changes for commit
- Ship verbs delegating message format
Write commit messages terse and exact. Conventional Commits. No fluff. Why over what.
Rules
Subject line:
<type>(<scope>): <imperative summary> — <scope> optional- Types:
feat, fix, refactor, perf, docs, test, chore, build, ci, style, revert
- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
- ≤50 chars when possible, hard cap 72
- No trailing period
- Match project convention for capitalization after the colon
Body (only if needed):
- Skip entirely when subject is self-explanatory
- Add body only for: non-obvious why, breaking changes, migration notes, linked issues
- Hard cap: 4 lines / 2 bullets. One why-sentence beats a paragraph.
- Never restate what the diff shows — file lists, renamed symbols, mechanical changes
- Wrap at 72 chars
- Bullets with
-, not *
- Reference issues/PRs at end:
Closes #42, Refs #17
Omit from commit messages:
- "This commit does X", "I", "we", "now", "currently" — the diff says what
- "As requested by..." — use
Co-authored-by: trailer instead
- "Generated with Claude Code" or any AI attribution
- Emoji (unless project convention requires)
- Restating the file name when scope already says it
Examples
Diff: new endpoint for user profile with body explaining the why
-
Bad: feat: add a new endpoint to get user profile information from the database
-
Good:
feat(api): add GET /users/:id/profile
Mobile client needs slim profile payload to cut LTE bandwidth on
cold-launch screens.
Closes #128
Diff: breaking API change
Auto-Clarity
Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context. The body cap still applies: 2-3 lines stating the break/risk and the migration path, not a narrative.
Supplemental input: session reports
When the invoking ship verb passes session-report content (markdown files from .claude/.scratchpad/session-reports/<branch>/), treat it as why-context for the message. The diff still drives what; the reports drive why. Specifically:
- Read the report bodies in chronological order.
- Distill all "Why" sections into at most one sentence in the body. If the why doesn't survive compression to one sentence, it wasn't load-bearing.
- Pull the "Open threads" sections forward only if they describe a known limitation worth recording (rare).
- Never paragraph-quote a report. The body cap (4 lines) applies regardless of how much report content exists.
If no reports are passed in, behave as before — diff alone drives synthesis.
Supplemental input: doc-skip trailers
When the invoking ship verb passes doc-skip: <reason> lines (collected by /documentation's skip-with-reason path or by a ship verb's doc-check step), include them verbatim in the commit's trailer block. The trailer block sits after the body's terminating blank line, in git interpret-trailers --parse range. One line per skip.
They sit alongside other trailers like Co-authored-by: and Closes #N. Do not paraphrase, do not merge multiple skips into one line, do not move them into the body. Emit doc-skip: lines in the order received; place them adjacent to other trailers without enforcing a fixed position relative to Co-authored-by: or issue refs.
Boundaries
Generates the commit message only. Does not run git commit, does not stage files, does not amend, does not read or delete session-report files (that is the invoking ship verb's job). Output the message as a code block ready to paste.
