How to use the macOS App Release Helper agent skill (release-mac-app)

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that an AI agent reads to learn a fixed procedure. This skill covers the release work for macOS apps that use Sparkle for updates: status checks, release notes, appcast generation and verification, and asset checks. Its name is release-mac-app and its SKILL.md lists the commands the agent should run through the bundled scripts/mac-release helper.

The skill is a workflow guide plus helper scripts. It is not a general app builder, and it does not create signing credentials for you.

• Reads the repo's .mac-release.env manifest before doing anything else.
• Runs scripts/mac-release for shared release, appcast and verify work.
• Keeps app-specific build, package and signing behaviour in your repo scripts.
• Avoids deleting or retagging a release after a failure; the agent is told to inspect existing state and resume the failed step.

Install the release-mac-app skill

Download the ZIP for the skill from this page and unzip it. To make it available to Claude Code for all your projects, place the folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal, all projects: ~/.claude/skills/
• Single project: <your-project>/.claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

Prepare your app repo

The skill assumes a specific setup. Each app repo needs a .mac-release.env file at its root. The file is the repo-owned release manifest and must contain no secrets.

The required entries are MAC_RELEASE_APP_NAME, MAC_RELEASE_REPO, MAC_RELEASE_BUNDLE_ID, MAC_RELEASE_VERSION_FILE, MAC_RELEASE_APPCAST, MAC_RELEASE_FEED_URL, MAC_RELEASE_DOWNLOAD_URL_PREFIX and MAC_RELEASE_APP_ZIP. You also need either MAC_RELEASE_INFO_PLIST or MAC_RELEASE_SUPUBLIC_ED_KEY.

MAC_RELEASE_PACKAGE_CMD is required only for the release command. Status, notes, changelog-html, verify-appcast and check-assets do not need it.

• MAC_RELEASE_APP_NAME
• MAC_RELEASE_REPO
• MAC_RELEASE_BUNDLE_ID
• MAC_RELEASE_VERSION_FILE
• MAC_RELEASE_APPCAST
• MAC_RELEASE_FEED_URL
• MAC_RELEASE_DOWNLOAD_URL_PREFIX
• MAC_RELEASE_APP_ZIP
• MAC_RELEASE_INFO_PLIST or MAC_RELEASE_SUPUBLIC_ED_KEY

Trigger the skill with a natural request

You do not need to type commands yourself. Open your app repo, start the agent and describe the task in plain language, naming the skill or the kind of work. The agent should read .mac-release.env first and then use the matching helper command.

Good requests say what you want checked or produced, for example a status check before a release, release notes for a version, or verification of the published appcast.

• "Use release-mac-app to check the release status of this app."
• "Use release-mac-app to draft release notes for the next version."
• "Use release-mac-app to verify the appcast for the current version."
• "Use release-mac-app to check the assets on the latest GitHub Release."

Know the commands the agent will run

The skill lists these mac-release subcommands. You can read them to understand what the agent is about to do. Each command is run from the skill's scripts folder, and the agent should execute mac-release directly rather than through plain bash.

verify-appcast uses only SUPublicEDKey. It needs no private key, Keychain or 1Password access.

• status
• notes [version] [output.md]
• changelog-html <version> [CHANGELOG.md]
• make-appcast <zip> [feed-url]
• verify-appcast [version]
• check-assets [tag]
• release
• codesign-run [--with-package-secrets] -- <command> [args...]
• package-run -- <command> [args...]

Understand the signing and credential rules

For the EdDSA key that signs Sparkle updates, the skill prefers MAC_RELEASE_SPARKLE_OP_REF when the key lives in 1Password. Otherwise it prefers Keychain Sparkle signing. SPARKLE_PRIVATE_KEY_FILE is only an explicit local override. The helper resolves the 1Password reference in a shared tmux session, writes a temporary key file with mode 0600 and deletes it afterwards.

Non-interactive Developer ID signing needs a dedicated, replaceable release keychain separate from your default keychain. The skill says the keychain must contain exactly one signing private key. The skill is written so that secrets stay out of printed output.

• Prefer MAC_RELEASE_SPARKLE_OP_REF for headless signing when the key is in 1Password.
• Use Keychain Sparkle signing otherwise.
• MAC_RELEASE_SIGNING_KEY_FILE is a local fallback path only.
• Set MAC_RELEASE_CODESIGN_PASSWORDLESS=1 only for a canonical passwordless, never-locking release keychain.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The release path can publish a GitHub Release and an appcast, and a bad or unsigned release reaches users, so review what the agent proposes before it runs release. The skill's own rules say uploads go to a draft before publication and that a failed release must be preserved rather than deleted.

Do not use the skill without an existing Developer ID signing setup and release keys. It cannot create them, and misuse could publish a bad or unsigned release.

• Uses the network: yes. Runs scripts: yes.
• Upload app and dSYM assets to a draft before publication.
• After a failure, inspect existing state and resume the failed step.
• Never print private key material.
• Do not retry 1Password reads in a fresh shell; rerun only from the same tmux session after explicit direction.