agentleFS
doublejdoublej/consult-user-mcp/.claude/skills/release-app/SKILL.md

release-app

Skill39 starsChanged 4 months agoMITView on GitHub

Cut a macOS or Windows release of Consult User MCP — version files, releases.json, generated changelog, tag, GitHub release with assets. Use when asked to "release", "cut a release", "ship a version", "tag a release", or "publish an update" for this project. Covers both platforms and the baseprompt-version gate.

  • Commits and pushes

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

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

    If macos-app/Sources/Resources/base-prompt.md changed, bump its version comment (first line).

    line 17
  2. Very specific:

    Add the release entry to docs/src/lib/data/releases.json.

    line 18
  3. Distinctive:

    Only the dmg is submitted.

    line 58
  4. Very specific:

    Update windows-app/VERSION, add the entry to releases.json, bun run changelog, commit, push.

    line 88

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

Release Consult User MCP

Two platforms, two procedures. They share docs/src/lib/data/releases.json as the single source of truth.

Never run gh release create without attaching assets. A release with no assets breaks the auto-updater for everyone already on the previous version.

macOS

Runs entirely on this machine.

  1. Update macos-app/VERSION.
  2. If macos-app/Sources/Resources/base-prompt.md changed, bump its version comment (first line). See .claude/rules/baseprompt.md.
  3. Add the release entry to docs/src/lib/data/releases.json. Write user-facing benefits, not commit messages — see .claude/rules/release-notes.md.
  4. bun run changelog — regenerates CHANGELOG.md. Never hand-edit it.
  5. bash scripts/validate-baseprompt-version.sh.
  6. Commit everything.
  7. bash scripts/release.sh --platform macos — builds, packages, tags, creates the GitHub release.

--dry-run validates preconditions without executing. Use it first when anything about the state is uncertain.

Two assets, both required

A macOS release ships a .dmg and a .zip, and neither is optional:

AssetConsumed by
Consult.User.MCP.dmga human downloading from the releases page — drag to /Applications
Consult.User.MCP.app.zipinstall.sh and the in-app updater, both of which pick the first .zip asset

make-dmg.sh builds and signs the dmg; dropping the zip breaks the auto-updater for everyone already installed.

The zip must contain no AppleDouble members. ditto -c -k encodes any extended attribute as a ._name entry, and update.sh extracting that adds an unsealed file to the bundle — the updated app then fails codesign --verify and will not launch. build-app.sh runs xattr -cr before signing and release.sh fails the release if any ._ entry survives. Both guards exist because one xattr, set just by having run the app, shipped a bricked updater in 2.6.5.

bash scripts/check-changelog-sources.sh confirms the change list the update prompt shows is actually fetchable. It needs at least one of the two sources in AppURLs.releasesJSONSources — the Pages copy comes from the docs deploy, so it lags a fresh release by a few minutes and the raw GitHub fallback covers the gap.

Signing and notarization

build-app.sh signs the bundle whenever a Developer ID Application identity is in the keychain, and skips silently when there is none — an unsigned build still works locally. release.sh then notarizes and staples, but only if the bundle actually came out Developer ID signed; otherwise it warns and ships unsigned rather than failing.

Only the dmg is submitted. The ticket Apple issues covers the app nested inside it, so both the dmg and the app staple from that one submission — and the zip is made after stapling, so the zipped app carries the ticket too.

One-time machine setup:

# 1. Certificate — Xcode ▸ Settings ▸ Accounts ▸ <paid team> ▸ Manage Certificates
#    ▸ + ▸ Developer ID Application.  Verify:
security find-identity -v -p codesigning

# 2. Notarization credentials — app-specific password from appleid.apple.com
xcrun notarytool store-credentials consult-user-mcp \
  --apple-id <apple-id> --team-id <TEAM_ID> --password <app-specific-password>

Overrides: CODESIGN_IDENTITY picks a specific identity, NOTARY_PROFILE a different stored profile.

Signing is deliberately part of bun run dev too — dev-install.sh swaps binaries into the installed bundle, which invalidates the signature, and a signed app with a broken seal will not launch at all. Dev builds sign without a secure timestamp so they stay fast.

Windows

.NET, WPF, and Velopack all require a real Windows environment. Steps 2–3 cannot run here.

On macOS:

  1. Update windows-app/VERSION, add the entry to releases.json, bun run changelog, commit, push.

On the Windows box (ssh user@192.168.178.197, repo at C:\Users\jurre\PycharmProjects\consult-user-mcp):

  1. Build the installer:
    git checkout main && git pull
    powershell -ExecutionPolicy Bypass -File scripts\build-windows-installer.ps1
  2. Tag and release from there, since gh is authenticated and the assets are local:
    git tag windows/vX.Y.Z HEAD && git push origin windows/vX.Y.Z
    gh release create windows/vX.Y.Z --title "Windows vX.Y.Z — ..." --notes "..." releases/windows/*

Full Windows toolchain details and gotchas: .claude/skills/windows-build/SKILL.md.

Version surfaces

FileCovers
macos-app/VERSIONmacOS app + bundled dialog CLI
windows-app/VERSIONWindows tray app + installer
macos-app/Sources/Resources/base-prompt.md (line 1)Baseprompt, versioned independently
docs/src/lib/data/releases.jsonBoth platforms; drives the docs page and CHANGELOG.md

These move independently. A baseprompt fix can ship without an app version bump, and vice versa.

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.