cut-a-release
Skill1 starsChanged 3 months agoMITView on GitHub
Take vat from a green main to a signed, published release.
- Installs packages
- Commits and pushes
3 other projects use a version of this.
Adopted by
Most recently taken up by
- GCarin1/Doctrinatheir own version, first seen Nov 8, 2026
- henit-chobisa/decktheir own version, first seen Oct 19, 2026
- royalpinto007/ship-skillstheir own version, first seen Oct 13, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- henit-chobisa/deck★ 33same name
- GCarin1/Doctrina★ 1same name
- royalpinto007/ship-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-a-lint-ruleSkill
- change-a-command-contractSkill
- add-a-lint-ruleSkill
- change-a-command-contractSkill
- cut-a-releaseSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 2 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Run git fetch --tags. Every version this binary reports comes from git describe, so a checkout missing the last tag builds a binary that …
- Very specific: line 28
Run make check. The tag is the trigger and there is no gate after it: a tag pushed on a red tree publishes a red release.
- Very specific: line 53
Verify the release page carries, for every target, an archive and a .cdx.json, plus one checksums.txt and a provenance attestation.
- Distinctive: line 80
Do not repair either by moving the orphaned tags.
- Distinctive: line 119
Not for a typo.
- Very specific: line 123
Stop before pushing if make check is red, if the working tree is dirty, or if the version cannot be justified from the diff.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cut a release
When to use this
A version is going out. Not for a local multi-platform build — that is
make release-snapshot, which publishes nothing.
Inputs
main, clean, withmake checkpassingCHANGELOG.md.github/workflows/release.yml, which is what actually publishes
Before anything
Run git fetch --tags. Every version this binary reports comes from
git describe, so a checkout missing the last tag builds a binary that names an
older release: on the v0.5.1 commit with only v0.4.2 fetched, make check built
vat v0.4.2-7-gaae7c2b. That was cosmetic until requires.vat began comparing
versions, and it is not any more — a workspace pinned >=0.5.0 refuses that
binary, built from the exact commit that satisfies it.
Run make check. The tag is the trigger and there is no gate after it: a tag
pushed on a red tree publishes a red release.
Decide the version from what changed, under semantic versioning. vat is a
command-line contract, so a changed exit code, a removed flag, or a changed
on-disk format is a breaking change even when no Go symbol moved.
Steps
- Move the entries under
## [Unreleased]inCHANGELOG.mdbeneath a new## [X.Y.Z] - YYYY-MM-DDheading, and leave## [Unreleased]in place and empty above it. The heading carries nov; the tag does. - Commit:
chore: release vX.Y.Z. - Tag:
git tag vX.Y.Z. The workflow triggers onv*and on nothing else. git push origin mainand thengit push origin vX.Y.Z.Push the tag by name.
--follow-tagspushes only annotated tags, and every tag this repository has is lightweight, so it skipped the tag in silence: main moved, the workflow never triggered, and the push reported success. Confirm withgit ls-remote --tags origin | grep vX.Y.Zbefore believing the release happened.- The workflow then builds the five targets in its
TARGETSlist, writes a CycloneDX SBOM per target, generates the shell completions, packages and checksums the archives, attests them andchecksums.txt, and publishes with generated release notes. - Verify the release page carries, for every target, an archive and a
.cdx.json, plus onechecksums.txtand a provenance attestation.
When main's history has been rewritten
A force-push that rewrites commits leaves every tag on the old history, still valid and still pointing at commits nothing reaches. On 2026-09-04 a metadata rewrite of everything after v0.2.1 orphaned seven tags, v0.3.0 through v0.5.2. The trees were identical, so no release was owed — but two things change and neither announces itself.
git describe walks the surviving history, not the tag list. On the
rewritten main it answers v0.2.1-31-g6febbf2, so make check builds a binary
that names v0.2.1, and a workspace pinned requires.vat: >=0.5.0 refuses it.
That is the failure the fetch rule above describes, except no fetch repairs it:
the tag is present and simply is not an ancestor. Releases are unaffected —
release.yml stamps github.ref_name, the tag being pushed — so this is a
local-build trap, and the tell is a version number far below the last release.
The forge computes release notes from a commit range. The next tag cut from
the rewritten main has v0.2.1 as its most recent reachable predecessor, so the
generated notes and the vX.Y.Z-1...vX.Y.Z comparison span every commit since
then rather than the release. Write the notes from CHANGELOG.md instead of
accepting the generated ones, and say in the release body that history was
rewritten, so a reader comparing two tags is not left to conclude the release
contained work it did not.
Do not repair either by moving the orphaned tags. They are published: the rule below holds, and the old commits stay alive precisely because those tags point at them.
When a published release turns out to be defective
A published tag is frozen. Never move one, and never delete one.
proxy.golang.org caches a version's content the first time anyone fetches it
and offers no deletion, so go install module@vX.Y.Z will serve that code
forever. Re-pointing the tag leaves two different trees answering to one version
while the proxy keeps serving the first, and deleting the tag on the forge does
not reach the proxy at all.
The fix is two things, not one:
- Ship the correction as the next version. Never as the same one.
- Retract the defective version in
go.mod, with a comment saying what was wrong with it. Retraction is what keeps the toolchain from offering it:go getrefuses a retracted version,go list -m -versionshides it, and@latestskips past it.
retract (
// What was wrong with it, in enough detail to judge the risk.
v0.1.5
// A contiguous range, when several versions share one defect.
[v0.1.2, v0.1.4]
)A retraction only takes effect once it is published in a version above the ones it names, so the retraction and the fix ship together in the new tag.
Record it in CHANGELOG.md too. The retract block is read by the toolchain
and by nobody else; a person deciding whether they are running something unsafe
reads the release notes.
Retract for a defect that matters to somebody running it — a disclosed credential, a write outside the directory vat governs, a wrong version stamp. Not for a typo.
When it must stop
Stop before pushing if make check is red, if the working tree is dirty, or if
the version cannot be justified from the diff. Stop after pushing, too, until
git ls-remote --tags origin shows the tag: a push that moved main and left the
tag behind reports success and publishes nothing. None of those is recoverable
afterwards, because the push is the publication.
Deciding that a defect is severe enough to retract is a judgement about other people's installations. Say what the defect is and let a human make it.
Nothing in this repository updates the Homebrew tap. If a release needs to reach
brew install, that happens outside this repository and is not this skill's to
assume.
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
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.

