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

usage-monitor-release

Skill19 starsChanged 50 days agoMITView on GitHub

Cut and publish a stable usage-monitor release: pick the version, verify locally, create the annotated tag and follow the GitHub Actions workflow that publishes Windows, Linux and macOS artifacts. Use to cut, ship, publish or troubleshoot a release.

  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

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

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

    line 12
  2. Very specific:

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

    line 18
  3. Distinctive:

    Keep release-related packaging aligned:

    line 36
  4. Distinctive:

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

    line 41
  5. Very specific:

    Do not package locally as a release gate.

    line 43
  6. Very specific:

    create the annotated tag with the temporary agent git identity: git -c user.name=claude -c user.email=claude@anthropic.com tag -a vX.Y.Z -m …

    line 54
  7. Distinctive:

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

    line 68
  8. Distinctive:

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

    line 69
  9. Very specific:

    Do not forget that release artifacts are published by CI from v* tags.

    line 70
  10. Distinctive:

    Do not reintroduce local packaging as a release gate.

    line 71
  11. Distinctive:

    Do not forget that the GitHub Release body should show the commit summary for the new version.

    line 72
  12. Very specific:

    Do not treat a macOS-only job failure as acceptable: the build-macos matrix blocks publish-release, and a green release without both DMGs …

    line 73
  13. Very specific:

    Prefer current code and workflow files over older notes in .agents, .claude, or docs/research.md when they disagree.

    line 74

≈ “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 Release

Release this repository in a way that stays aligned with the current build, installer, and GitHub Actions workflow.

Workflow

  1. Read AGENTS.md, README.md, build.gradle.kts, and .github/workflows/release-linux.yml first.
  2. Invoking this skill already means "cut and publish the release". Do not ask for confirmation to commit, tag, or push — go through the whole flow, including step 8, and only report the result.
  3. Confirm the release type from the request:
    • patch
    • minor
    • major
  4. Verify that main is clean and matches origin/main — the tag must point to a commit that is already on the remote main, or verify-version refuses the release:
    • git fetch origin && git status --short --branch
    • git log --oneline -5
  5. Pick the version. There is no version bump commit (#344): the version comes from the tag.
    • Current version: git describe --tags --abbrev=0 --match "v[0-9]*" --exclude "*-beta*"; compute the next X.Y.Z from the release type. Beta tags (vX.Y.Z-beta.N, issue #355) are never the base: without --exclude a beta would become the "current" stable version. If an open beta series vX.Y.Z-beta.N exists, releasing it as stable means tagging that same X.Y.Z. Beta releases have their own skill, usage-monitor-release-beta.
    • Open beta series? (git -c versionsort.suffix=- tag --sort=-version:refname --list "v*-beta.*" | head -n 1 with no stable of the same X.Y.Z). Promoting it is usage-monitor-release-beta promote. A stable lower than the series (a patch of the previous stable while X.Y.Z-beta.N is open) is fine for everyone else but never reaches the testers — X.Y.Z-beta.N is higher. Say so in the report, and if the fix matters to them, follow it with a next beta.
    • build.gradle.kts resolves version from -PappVersion (the release workflow passes the tag) and, without it, from that same git describe — never edit a version literal there or in src/installer/UsageMonitor.nsi (its !ifndef default only serves direct makensis runs).
  6. Keep release-related packaging aligned:
    • The Gradle buildNsisInstaller task passes /DPRODUCT_VERSION=$appVersion to NSIS.
    • The local helper build-with-icon.ps1 is Windows-only and exists for icon-patched local packaging.
    • The official GitHub release artifacts come from the tag-driven workflow in .github/workflows/release-linux.yml, which builds Linux, Windows, and macOS.
    • macOS .dmg files come from the build-macos job (macos-latest for arm64, macos-15-intel for x64). They are unsigned: no Apple Developer ID, no notarization. packageDmg cannot run on Windows or Linux, so there is no local validation path for it.
  7. Run the local verification that must pass before the tag exists:
    • gradlew.bat allTests — mandatory. The tag is what triggers the release; a broken suite discovered after the push means a burned tag on the remote.
    • Do not package locally as a release gate. build-windows already runs packageInstaller, and build-linux/build-macos cover the other two OSes. Local packaging duplicates CI and proves only one platform.
    • gradlew.bat packageInstaller only when the task is debugging the installer itself (see the usage-monitor-nsis-installer skill).
    • Window hosts changed? Stop before the tag (#342). 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, no test covers what broke in #340 — the window system. List the rows of docs/hud-notch.md › "Fora do alcance dos testes" that the change touches and ask the maintainer whether the build was opened on Linux (X11). This is the only confirmation this skill asks for: without it, v41.0.0 shipped a HUD that was broken on Linux for three releases. If nothing in the list changed, continue without asking.
  8. Publish. Invoking this skill is the request to publish — never stop to ask for confirmation:
    • create the annotated tag with the temporary agent git identity: git -c user.name=claude -c user.email=claude@anthropic.com tag -a vX.Y.Z -m "vX.Y.Z" (annotated is mandatory — verify-version rejects lightweight tags)
    • push only the tag: git push origin vX.Y.Z. Nothing is pushed to main, so a release no longer triggers CI or CodeQL there.
  9. Watch the GitHub Actions workflow Release Desktop Packages and report the outcome. verify-version checks that the tag is vX.Y.Z, annotated and on main; verify runs allTests and the installer scenarios in parallel with the builds; publish-release requires both. To rebuild an existing tag without publishing, dispatch the workflow with publish: false. The published release must carry every artifact family:
    • Windows: UsageMonitor-Setup-X.Y.Z.exe, the only Windows artifact. The .msi was dropped after v37 — both installers wrote to the same %LOCALAPPDATA%\Usage Monitor and an MSI install could never update itself.
    • Linux: .deb, .rpm, and usage-monitor_X.Y.Z_linux_x64.tar.gz
    • macOS: usage-monitor_X.Y.Z_macos_arm64.dmg and usage-monitor_X.Y.Z_macos_x64.dmg A release missing either DMG is incomplete and must be reported as such.
  10. The published GitHub Release should include a short changelog built from commits between the previous v* tag and the new tag. That changelog is generated by the workflow's Generate release notes step; do not create it manually with gh release create.

Guardrails

  • 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 skill invocation is the authorization; asking again is unwanted friction. The one exception is step 7: a window host changed since the last tag (#342).
  • Do not forget that release artifacts are published by CI from v* tags.
  • Do not reintroduce local packaging as a release gate; CI owns packaging for all three OSes.
  • Do not forget that the GitHub Release body should show the commit summary for the new version.
  • Do not treat a macOS-only job failure as acceptable: the build-macos matrix blocks publish-release, and a green release without both DMGs means the workflow was edited or skipped.
  • Prefer current code and workflow files over older notes in .agents, .claude, or docs/research.md 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.