agentleFS
dativo-iodativo-io/talon/.claude/skills/cut-release/SKILL.md

cut-release

Skill18 starsChanged 24 days agoApache-2.0View on GitHub

Cut a Talon release the way the repository does it — changelog section and compare link, release branch and PR, annotated tag on merged main, release workflow verification, and the re-cut rule when a release job fails.

  • Commits and pushes

35 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use quota-axi, iterate-pr and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • layer5ioSkill

    quota-axi

    Report local Claude, Codex, Cursor, GitHub Copilot, and Grok quota windows via the quota-axi CLI - remaining percentages, reset times, and provider status read from local auth sources, with no routing, recommendation, or provider mutation. Use before deciding whether it is safe to keep spending a provider's quota, when the user asks about usage, rate limits, or remaining quota, or when comparing local provider headroom.

    Also in 4 projects that use this

  • SentrySkill

    iterate-pr

    Iterate on a PR until actionable CI passes and high/medium review feedback is addressed. Use for PR CI failures, review feedback, or green-check loops; do not wait for human approval, draft status, or merge gates.

    Also in 4 projects that use this

  • layer5ioSkill

    gh-axi

    Operate GitHub through the gh-axi CLI - issues, pull requests, workflow runs, workflows, releases, repositories, labels, Projects (v2), Actions secrets and variables, search, and raw API access. Use whenever a task touches GitHub: listing or filing issues, reviewing or merging PRs, checking CI runs, triggering workflows, cutting releases, managing Projects boards, or managing Actions secrets/variables.

    Also in 4 projects that use this

  • kunchenguidSkill

    chrome-devtools-axi

    Control a Chrome browser session through the chrome-devtools-axi CLI - navigate, snapshot, click, fill forms, run JavaScript, inspect console and network, take screenshots, audit performance. Use whenever a task needs a real browser: opening or testing a web page, clicking through a flow, extracting page content, or debugging a website.

    Also in 4 projects that use this

  • kunchenguidSkill

    lavish

    Turn complex or visual agent responses into rich, reviewable HTML artifacts (HTML files) the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.

    Also in 4 projects that use this

  • ThisIsSadeghiSkill

    verify-ui

    Verify UI implementation against Stitch design via a token audit (HTML ↔ Code, with X-component default-render checks) and an X-components compliance check.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 35 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every step marked [human] mutates GitHub, tags or registries and runs only on the user's explicit instruction.

    line 9
  2. Very specific:

    add the compare link at the bottom: [X.Y.Z]: https://github.com/dativo-io/talon/compare/vPREV...vX.Y.Z (the first release of a line uses …

    line 24
  3. Very specific:

    Run /verify-change at least to the static layer and go test ./tests.

    line 27

“Common” is measured: kept by at least 6 in 10 of the 35 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.

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

Cut release $ARGUMENTS (a semver X.Y.Z).

Every step marked [human] mutates GitHub, tags or registries and runs only on the user's explicit instruction; otherwise hand over the exact commands.

Preconditions

  1. main is green: CI, Docs, Security (govulncheck, gitleaks), CodeQL, Shortlist Demo, OpenShell Live (v0.1.3 required).
  2. ## [Unreleased] in CHANGELOG.md is complete and every entry meets the quality bar (problem, who cares, how to verify, upgrade impact, share artifact when applicable). Nothing in it describes unshipped behaviour.
  3. govulncheck ./... is clean; if it is not, the fix (toolchain or dependency bump) ships in this release and is named in the notes.
  4. Decide the version: patch for fixes and security, minor for features, following the previous section headers.

Prepare the release commit

  1. Branch from current main: release-vX.Y.Z.
  2. CHANGELOG.md:
    • rename the Unreleased content to ## [X.Y.Z] - YYYY-MM-DD and leave a fresh empty ## [Unreleased] (keep the "Release Note Quality Bar" block under it);
    • open the section with a one-paragraph theme when the release has one;
    • add the compare link at the bottom: [X.Y.Z]: https://github.com/dativo-io/talon/compare/vPREV...vX.Y.Z (the first release of a line uses releases/tag/vX.Y.Z).
  3. Nothing else carries the version: binaries use git describe (VERSION in the Makefile) and the release workflow derives the version from the tag.
  4. Commit: chore(release): cut vX.Y.Z — <one-line theme>.
  5. Run /verify-change at least to the static layer and go test ./tests; a release PR still passes the full CI.

Ship

  1. [human] Push the branch and open the PR; merge after green.
  2. [human] Tag the merged commit on main, not the branch commit: merges are rebase merges, so a tag on the branch is never an ancestor of main (that happened to v1.15.0 and v1.15.2; cosmetic but confusing). Annotated tag:
    git switch main && git pull --ff-only
    git tag -a vX.Y.Z -m "vX.Y.Z — <theme>" && git push origin vX.Y.Z
  3. The tag push runs .github/workflows/release.yml (build → verify → publish, #507): GoReleaser creates a draft release (linux archive, checksums.txt, the version-tagged images ghcr.io/dativo-io/talon:<X.Y.Z> and ghcr.io/dativo-io/talon-openshell-agent:<X.Y.Z>); the showcase bundle job reads talon back from that archive and writes its digest into the manifest; the darwin job adds its archives; release-verify checks every digest and runs the showcase customer path from the draft's assets, then publishes the release and moves :latest / :<X.Y>. A failed verification leaves a draft — fix forward, next patch version; never upload to or edit a published release (scripts/release-guard.sh refuses). A failure AFTER "Publish the release" (alias promotion, anonymous re-download) is recovered with gh workflow run release.yml -f tag=vX.Y.Z (audit mode: re-verifies, re-applies the movable image tags, rewrites nothing). When release.yml, .goreleaser.yml or the bundle script changed since the last release, tag vX.Y.Z-rc.1 first: the pre-release runs the whole path for real while releases/latest, install.sh and the movable tags ignore it.

Verify (CONTRIBUTING "Release Artifact Verification")

LATEST=$(gh release view --json tagName -q .tagName)
gh release view "$LATEST" --json isDraft,assets -q '"draft=\(.isDraft)", .assets[].name'
gh api "/repos/dativo-io/talon/actions/workflows/release.yml/runs?per_page=1" -q '.workflow_runs[0].conclusion'
scripts/verify-release.sh --tag "$LATEST" --install /tmp/talon-verify-install --all-archives   # the customer's check: PASS verify-release: <tag>
gh workflow run install-smoke.yml -f tag="$LATEST"   # the same on a clean runner (#359)
docker pull ghcr.io/dativo-io/talon:latest
gh workflow run release.yml -f tag="$LATEST"   # audit mode: re-verifies the published assets, changes nothing

The gated installer path is linux/amd64 (#359): a darwin job that never acquires a macOS runner no longer blocks publication, and a failed macOS build is reported as a build failure (error annotation, "Platform assets" on the release page) — file it and fix forward, never re-run the same tag. Read the "Platform assets" table in the job summary and the release notes. Record the digests verify-release.sh prints (archive, executable, bundle, manifest, both images) in the handoff.

Also check: draft=false; the showcase bundle, its .sha256 and its .manifest.json are among the assets and the manifest's artifacts.talon.sha256 equals the sha256 of the talon inside talon_<X.Y.Z>_linux_amd64.tar.gz; both GHCR packages are public — scripts/check-image-public.sh ghcr.io/dativo-io/talon:<X.Y.Z> ghcr.io/dativo-io/talon-openshell-agent:<X.Y.Z> (the verify job runs the same check; a private package fails the rehearsal, as v1.15.4-rc.1 did); the release notes link at least one share artifact.

When the release job fails after tagging

Do not delete or move the tag and do not re-run with the same version. Fix forward on main, cut the next patch version, and state in its CHANGELOG section that the earlier tag exists but published nothing (precedent: v1.15.1 → v1.15.2, where a timing-dependent test tripped the release gate).

Handoff

Report the tag, the release URL, which verification commands ran and their output, and anything still unverified (for example GHCR visibility or the clean-host showcase run).

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.