agentleFS
edilsonvilarinhoedilsonvilarinho/usage-monitor/.claude/skills/usage-monitor-release-beta/SKILL.md

usage-monitor-release-beta

Skill19 starsChanged 50 days agoMITView on GitHub

Beta channel of usage-monitor — publish a vX.Y.Z-beta.N prerelease for opted-in users, fix it with the next beta, promote the series to stable, or withdraw/restore a beta. Use for any beta release task; plain stable releases use usage-monitor-release.

  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. About 0 are common, 9 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the whole life of a beta for the users who opted into the beta channel (issue #355).

    line 8
  2. Very specific:

    Read AGENTS.md, build.gradle.kts and .github/workflows/release-linux.yml first.

    line 48
  3. Distinctive:

    If the request is ambiguous and there is no open series, ask which type.

    line 58
  4. Very specific:

    Verify that main is clean and matches origin/main — the tag must point to a commit already on the remote main, or verify-version refuses it:

    line 60
  5. Distinctive:

    Run the local verification that must pass before the tag exists:

    line 71
  6. Distinctive:

    Do not package locally as a gate.

    line 80
  7. Very specific:

    every artifact family is there, each with a sha256: digest (auto-update refuses assets without it): UsageMonitor-Setup-X.Y.Z-beta.N.exe.

    line 90
  8. Very specific:

    default — the current origin/main (the beta code plus whatever was merged after it).

    line 113
  9. Very specific:

    Run the stable flow of usage-monitor-release from its step 4 (clean main = origin/main, allTests, the #342 window-host question, annotated …

    line 118
  10. Distinctive:

    If the maintainer really wants it, tell them the command and let them run it.

    line 152
  11. Distinctive:

    If a newer beta or the stable of the series already exists, restoring an older beta changes nothing for anyone — say so instead of …

    line 160
  12. Very specific:

    Never publish a stable version from this skill except through promote, which runs the stable flow of usage-monitor-release with the version …

    line 165
  13. Very specific:

    Never turn a beta release into a stable or Latest one by editing it.

    line 167
  14. Very specific:

    Never delete a release or a tag.

    line 169
  15. Very specific:

    Never tag a suffix other than -beta.N.

    line 170
  16. Very specific:

    Never tag a beta whose X.Y.Z is already released as stable.

    line 171
  17. Distinctive:

    Do not release from a dirty tree unless the user explicitly wants that risk.

    line 172
  18. Distinctive:

    Do not ask the user to confirm the tag or the push.

    line 173
  19. Distinctive:

    Prefer current code and workflow files over older notes when they disagree.

    line 174

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Usage Monitor Beta Release

Run the whole life of a beta for the users who opted into the beta channel (issue #355). Publishing is the stable release flow (usage-monitor-release) with a different tag and a different promise: a beta never becomes latest, so nobody outside the channel receives it.

Operations (the argument picks one)

ArgumentWhat it doesSection
patch / minor / majorPublish beta.1 of a new series for the next stable of that typeWorkflow
nextPublish beta.N+1 of the open series (the way to fix a bad beta)Workflow
promotePublish the stable vX.Y.Z of the open series — the beta "goes to main/master"Promote
withdraw [tag]Hide a beta: nobody new is offered it (reversible)Withdraw
restore [tag]Undo a withdrawRestore

There is no "move the beta to main": the tag already points to a commit on main — verify-version refuses anything else. The code is merged before the beta exists; what "going to stable" means is publishing a new, stable build of that code (promote). There is also no rollback for testers who already installed a beta: the app never downgrades. They leave the beta when a higher version reaches them — the next beta or the stable.

How the channel works (read before tagging)

  • Tag format: vX.Y.Z-beta.N, N ≥ 1. Nothing else is accepted — verify-version rejects -rc.1, -beta without a number and any other suffix, and the Linux updater refuses them too.
  • The workflow sets prerelease: true and make_latest: false for -beta.N tags. Clients outside the channel read /releases/latest, which the GitHub API never answers with a prerelease — that is the whole protection, and it also covers app versions older than the channel.
  • Clients inside the channel list /releases?per_page=20 and take the highest non-draft version by SemVer precedence: 42.0.0-beta.1 < 42.0.0-beta.2 < 42.0.0. The stable 42.0.0 therefore reaches every beta tester of the 42.0.0 series. Turning the channel off never downgrades.
  • X.Y.Z is the next stable version the beta previews. Never tag a beta for a number that is already released as stable: 41.0.0-beta.1 after v41.0.0 is lower than the running stable and is never offered to anyone.
  • Packaging: Exe/Dmg carry only X.Y.Z (jpackage rejects the suffix), Deb/Rpm carry X.Y.Z~beta.N; CURRENT_APP_VERSION, the NSIS installer name, the tarball and the release assets keep the full X.Y.Z-beta.N.

Workflow

  1. Read AGENTS.md, build.gradle.kts and .github/workflows/release-linux.yml first.
  2. Invoking this skill already means "cut and publish the beta". Do not ask for confirmation to tag or push — go through the whole flow and report the result. The only question allowed is the one in step 6 (window hosts).
  3. Pick the operation from the request (see the table above). promote, withdraw and restore have their own sections below; this workflow is for publishing a beta:
    • patch / minor / major — start a new series for the next stable of that type: N = 1.
    • next (or no type while a series is open) — continue the open series: N + 1.
    • If the request is ambiguous and there is no open series, ask which type.
    • An open series is vX.Y.Z-beta.* with no stable vX.Y.Z yet.
  4. Verify that main is clean and matches origin/main — the tag must point to a commit already on the remote main, or verify-version refuses it:
    • git fetch origin --tags && git status --short --branch
    • git log --oneline -5
  5. Compute the version. There is no version bump commit — the version comes from the tag.
    • Last stable: git describe --tags --abbrev=0 --match "v[0-9]*" --exclude "*-beta*".
    • Betas of the series: git tag --list "vX.Y.Z-beta.*", highest N by numeric sort (git -c versionsort.suffix=- tag --sort=-version:refname --list "vX.Y.Z-beta.*" | head -n 1).
    • New series: X.Y.Z = last stable bumped by the type; refuse if vX.Y.Z already exists.
    • Continue: same X.Y.Z, N + 1; refuse if the stable vX.Y.Z already exists (the series is closed — start a new one).
  6. Run the local verification that must pass before the tag exists:
    • gradlew.bat allTests — mandatory. A beta is still a public tag; a broken suite discovered after the push is a burned tag.
    • Window hosts changed? Stop before the tag (#342), exactly as in the stable skill: run git diff --name-only $(git describe --tags --abbrev=0)..HEAD and look for HudWindow.kt, DesktopWindowFrame.kt, Main.kt or any *WindowHost*.kt. If one changed, list the rows of docs/hud-notch.md › "Fora do alcance dos testes" the change touches and ask the maintainer whether the build was opened on Linux (X11). A beta is a good place to find such bugs, but the testers still run it as their daily app.
    • Do not package locally as a gate; CI owns packaging for the three OSes.
  7. Publish:
    • annotated tag with the temporary agent git identity: git -c user.name=claude -c user.email=claude@anthropic.com tag -a vX.Y.Z-beta.N -m "vX.Y.Z-beta.N"
    • push only the tag: git push origin vX.Y.Z-beta.N.
  8. Watch Release Desktop Packages and report the outcome. Then confirm on the published release:
    • it is marked Pre-release: gh release view vX.Y.Z-beta.N --json isPrerelease → true (gh has no isLatest field);
    • it is not Latest — /releases/latest still points to the last stable: gh api repos/edilsonvilarinho/usage-monitor/releases/latest --jq .tag_name;
    • every artifact family is there, each with a sha256: digest (auto-update refuses assets without it): UsageMonitor-Setup-X.Y.Z-beta.N.exe; .deb, .rpm and usage-monitor_X.Y.Z-beta.N_linux_x64.tar.gz; usage-monitor_X.Y.Z-beta.N_macos_arm64.dmg and usage-monitor_X.Y.Z-beta.N_macos_x64.dmg. gh release view vX.Y.Z-beta.N --json assets --jq '.assets[] | [.name, .digest] | @tsv' A beta missing an artifact family, or published as Latest, is a failed release and must be reported as such. If it went out as Latest, edit it back with gh release edit vX.Y.Z-beta.N --prerelease --latest=false and report it — every user outside the channel was being offered the beta.
  9. The release notes come from the workflow's Generate release notes step: a beta diffs against the previous tag (beta or stable); the stable release later diffs against the previous stable, so it lists the whole series. Do not write them by hand.

Promote — the open series becomes the stable release

The stable is a new tag and a new build, never the beta release edited into a stable one. The beta binaries carry X.Y.Z-beta.N in CURRENT_APP_VERSION, in the installer name and in the receipt; an edited release would hand every user a build that calls itself beta. Never run gh release edit ... --prerelease=false or --latest on a beta.

  1. Find the open series: git -c versionsort.suffix=- tag --sort=-version:refname --list "v*-beta.*" | head -n 1 gives vX.Y.Z-beta.N. Refuse if vX.Y.Z already exists (nothing to promote) or if there is no beta tag.
  2. Decide what becomes stable:
    • default — the current origin/main (the beta code plus whatever was merged after it). Say in the report which commits are new since the last beta: git log --oneline vX.Y.Z-beta.N..origin/main.
    • promote exact — the very commit the testers ran: tag vX.Y.Z on vX.Y.Z-beta.N^{commit}. verify-version accepts it, because that commit is on main.
  3. Run the stable flow of usage-monitor-release from its step 4 (clean main = origin/main, allTests, the #342 window-host question, annotated tag, push only the tag, watch the workflow, check every artifact) with the version fixed to X.Y.Z — do not bump it by type. For promote exact, create the tag on the beta commit: git -c user.name=claude -c user.email=claude@anthropic.com tag -a vX.Y.Z vX.Y.Z-beta.N^{commit} -m "vX.Y.Z".
  4. Confirm: gh release view vX.Y.Z --json isPrerelease → false, and /releases/latest → vX.Y.Z. The stable notes diff against the previous stable, so they list the whole beta series.
  5. Result: users outside the channel receive X.Y.Z as a normal update; testers on X.Y.Z-beta.N receive it too (beta.N < X.Y.Z) and see its "Novidades". The series is closed — the next beta starts a new one.

Withdraw — a bad beta stops being offered

Withdrawing hides the release; it does not delete anything and it is reversible (restore). The client ignores drafts, and anonymous API calls — the ones the app makes — do not see them.

  1. Target: the tag in the request, or the highest v*-beta.*. Refuse a stable tag: withdrawing a stable is not this skill's job.
  2. gh release edit vX.Y.Z-beta.N --repo edilsonvilarinho/usage-monitor --draft=true
  3. Confirm it is hidden from what the app reads: gh api "repos/edilsonvilarinho/usage-monitor/releases?per_page=20" --jq '.[] | select(.draft == false) | .tag_name' must not list it (this call is authenticated and sees drafts only with draft: true), and /releases/latest is unchanged.
  4. Report what it does not undo, every time:
    • testers who already installed that beta stay on it — there is no downgrade. They move when a higher version reaches them;
    • an auto-update already downloaded but not yet applied is still applied on the next exit.
  5. What to do next — say it in the report:
    • fix forward (the normal path): merge the fix and run this skill with next — vX.Y.Z-beta.N+1 is offered to everyone in the channel, including those stuck on the bad one;
    • abandon the series: promote a stable that does not include the bad change, or start a new series later. Never reuse a withdrawn tag name — a client may already know it.
  6. The tag stays on the remote. Deleting the release or the tag (gh release delete --cleanup-tag) is permanent and not part of this skill: it gains nothing over the draft and loses the record. If the maintainer really wants it, tell them the command and let them run it.

Restore — undo a withdraw

  1. gh release edit vX.Y.Z-beta.N --repo edilsonvilarinho/usage-monitor --draft=false --prerelease --latest=false — the three flags together, so it comes back exactly as a beta and never as Latest.
  2. Confirm isPrerelease: true, /releases/latest unchanged, and that the channel sees it again (the non-draft listing above lists it).
  3. If a newer beta or the stable of the series already exists, restoring an older beta changes nothing for anyone — say so instead of restoring.

Guardrails

  • Never publish a stable version from this skill except through promote, which runs the stable flow of usage-monitor-release with the version fixed to the open series.
  • Never turn a beta release into a stable or Latest one by editing it; restore always passes --prerelease --latest=false.
  • Never delete a release or a tag; withdraw hides it as a draft.
  • Never tag a suffix other than -beta.N.
  • Never tag a beta whose X.Y.Z is already released as stable.
  • Do not release from a dirty tree unless the user explicitly wants that risk.
  • Do not ask the user to confirm the tag or the push; the one exception is step 6 (#342).
  • Prefer current code and workflow files over older notes when they disagree.

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.