agentleFS
oleg-vasilyevoleg-vasilyev/FoolProof/.claude/skills/write-a-commit/SKILL.md

write-a-commit

Skill2 starsChanged 52 days agoMITView on GitHub

Write a commit message or a release message in this repository's voice — the title, the body that explains why the previous shape was wrong, the gate numbers a phase-final commit carries, and the exact npm version command a release uses. Stage 7 — use before any commit, and before cutting a release tag.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every gate is named even when skipped, carrying its reason (gallery not opened: no SVG changed) rather than silence.

    line 50

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing a commit message

Stage 7 of how a change becomes a release.

Two kinds exist here, and nothing else: a working commit on main, and a release made by npm version. Both are prose in the project's voice — no conventional-commit prefixes, no scopes, no bullet-list changelogs, no file lists. The diff already says what changed; a message that repeats it has wasted the reader's one visit.

The working commit

Title: one imperative sentence about behaviour, written for the person the change serves — a player, the operator, a future reader. It survives being read alone in git log --oneline.

  • Count the chats, not just the games, and lock the report to one reader
  • Say where the two numbers about the site are read

Not: Update status handler, feat(diagnostics): add chat summary, Fix tests. A title that names files or layers has already failed — name what the bot now does differently.

Body: paragraphs, not bullets. Its one obligation is the thing a diff cannot show — why the previous shape was wrong, and what was decided along the way: the alternative rejected, the constraint that forced the shape, the number that was measured rather than guessed. Write it the way the README is written: plain claims, each carrying its reason.

A phase-final commit ends with the Gates paragraph, in one fixed shape, so two phases can be compared without re-parsing prose. check:phase writes the first line into reports/gates/gates-paragraph.txt, stamped for the commit-msg hook — paste it, never retype it; the history holds dozens of hand wordings of that line alone:

Gates: <the line check:phase wrote to reports/gates/gates-paragraph.txt, pasted as is>
Copy: <what was read and when, or why nothing was>.
Gallery: <one specific claim about what was seen, or why it stayed shut>.
Review: <N> findings, <their fate in a clause>.
Retro: <the counted answers that were not none> → <the file each default landed in>,
or that the phase went straight and had nothing to count.
Tag: <the version, or that this rides the next one and why>.

Every gate is named even when skipped, carrying its reason (gallery not opened: no SVG changed) rather than silence.

The Retro: line is here because this paragraph is the only thing that asks. Gates 1 to 5 are pulled in by the work: nothing ships without compiling, passing and being reviewed. The retrospective is the one gate whose whole value goes to the next phase, so this phase never needs it and never notices its absence. The proof is a phase that skipped it: the same paragraph, lacking a retro line but carrying a gallery one, produced a written verdict on the gallery — "not opened, no renderer changed" — and total silence about the retrospective. The template asked about one and not the other, and that alone decided which happened.

And it carries counts because the same failure works one level down. The retrospective asks six questions; a single slot took one verdict, so five of them could go unanswered and the line still read as finished. It compresses the block retrospective produces — it may not report a verdict that block never reached, and a phase whose answers were all none says that rather than staying quiet. Coverage is four numbers in statements/branches/functions/lines order. A mutation survivor left alive on purpose gets its own sentence after the paragraph, naming the mutant and why its death is not worth buying.

Trailer, always the last line:

Co-Authored-By: Claude <the model that wrote it> <noreply@anthropic.com>

The model name in the trailer is whichever Claude actually wrote the commit.

The release

Not every phase gets one — finish-phase has the test and the reason. When it says no, the phase still ends in the working commit above; there is simply no npm version after it, and the Tag: line says which tag will carry the work instead.

A release starts from a green main: after pushing the phase commits, wait for the push CI (gh run watch --exit-status, about a minute) and fix a red check:push before cutting anything — a tag must not point at a commit the site is failing on.

A release is npm version with -m, so the commit and the tag carry the same message; %s becomes the version. check:release runs after the tag and before the push, detached — the pre-push hook reads its stamp, and a red run leaves the tag here:

npm version minor -m "Release %s

A minor: <one paragraph — what this tag gives the player or the operator,
in plain words, no gate numbers, no file names>.

Co-Authored-By: Claude <the model that wrote it> <noreply@anthropic.com>"
npm run check:release
git push --follow-tags

The title is always Release X.Y.Z. The body opens by naming the bump — A minor:, A patch: — and says what somebody running the previous version gets by taking this one. Gate numbers stay in the phase commits underneath; the release message is the shop window, not the ledger. Patch versus minor is the Bot API user's view: new commands or screens are a minor, a fix to existing behaviour is a patch.

Judging one before it lands

  1. Could the title be pasted into /help as a claim about the bot? If it only makes sense to somebody holding the diff, rewrite it.
  2. Does the body say anything the diff does not? If not, it is missing its reason for existing.
  3. Would the numbers in a phase-final commit let a reader two months from now notice a regression? Absent numbers are a gap, not a style choice.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.