commit-messageSKILL.md · 1.5 KB
A git log you can read back.
Ask for a commit message and it runs git status, then reads git diff --cached — the staged changes are the commit, so the staged changes are what get described. What comes back is a subject line that stands on its own in git log --oneline, a sentence or two on why the change was needed, and bullets only where the change earns them.
The order is the point. A message written from the session you just had describes the session, false starts and all. A message written from the staged diff describes the commit — and leaves out the file you edited but never staged, which is not part of it.
cp -r commit-message ~/.claude/skills/What it does
Two rules, and the surprising one is about length.
The first two instructions are git status and git diff --cached, in that order, and the second one is what changed: the staged diff rather than everything since the last commit. What you have edited but not staged is not part of this commit, so it is not part of the message, and neither is anything untracked. Only when nothing is staged at all does it fall back to git diff HEAD.
Everything after that is a shape to pour the diff into, and the shape is a commit message rather than a pull request: a subject line under 72 characters, a blank line, then the body. No markdown headers — the subject is what git log --oneline prints, so it has to hold up beside every other line in the log. Imperative, too: “Add retry to upload handler”, not “Added retry” or “This adds retry”. And no feat: or fix: prefixes; nothing in it is there for a semver tool to parse.
The paragraph in the middle is the part no diff can supply, and it is why the message is worth keeping. “Mercury had no test infrastructure.” “The README and example config lacked a single factual snapshot of what fileorg can do today.” A year on, the diff is still there to read; the reason for it is not, unless someone wrote it down at the time.
Then the rule that does the work on a large change: message length does not scale with diff size. A 40-file change gets the same length message as a 4-file one — the bullets just get more general. Small changes get a subject line, or a subject and one sentence, and no bullets at all. Large ones get five bullets at most, grouped by theme rather than by file, because a bullet naming a single file is a bullet that has not been generalised yet. Nothing gets enumerated — not files, not functions, not line-level edits — since the diff already records all three. The message is there to say what they add up to.
Example messages
Three messages as the skill wrote them, from three different repos — a site, a weather app and a command-line tool.