| name | build-dmg |
| version | 1.0.1 |
| description | Build a distributable DMG installer for any macOS Xcode project. Handles archiving,
code signing, DMG creation with styled Finder window, and version management.
Trigger on: "build a DMG", "create DMG installer", "package as DMG", "build for distribution",
or when the user wants to distribute a macOS app outside the App Store.
|
| allowed-tools | ["Bash","Read","Write"] |
build-dmg
Build a styled DMG installer from any macOS Xcode project.
Before Running
Detect the project settings by reading available files:
- App name — from
package.json name, project.yml name, .xcodeproj directory name, or ask the user
- Scheme — run
xcodebuild -list to discover available schemes, or ask the user
- Project/Workspace — auto-detected if only one
.xcodeproj or .xcworkspace exists at root
- ExportOptions.plist — check if
scripts/ExportOptions.plist exists. If not, ask the user for the path or whether to create one
- VERSION file — check if a
VERSION file exists at project root
- xcodegen — check if
project.yml exists (indicates xcodegen usage)
- Team ID — check existing build settings or ask the user
Present the detected configuration to the user and confirm before building.
Running the Build
The build script is at .claude/skills/build-dmg/helpers/build-dmg.sh. Run it directly from the project root with the required env vars:
APP_NAME="<app>" SCHEME="<scheme>" bash .claude/skills/build-dmg/helpers/build-dmg.sh
The script uses the current working directory as the project root. Do NOT copy the script into the project.
Required Environment Variables
| Variable | Description |
|---|
APP_NAME | Display name for the .app and DMG volume |
SCHEME | Xcode scheme to build |
Optional Environment Variables
| Variable | Default | Description |
|---|
PROJECT | auto-detected | Path to .xcodeproj |
WORKSPACE | — | Path to .xcworkspace (takes precedence over PROJECT) |
INFO_PLIST | <SCHEME>/Info.plist | Path to Info.plist for version injection |
EXPORT_OPTIONS | scripts/ExportOptions.plist | Path to ExportOptions.plist |
TEAM_ID | — | Apple Development Team ID |
VERSION_FILE | VERSION | Path to VERSION file. Set to "none" to skip version management |
USE_XCODEGEN | 0 | Set to "1" to run xcodegen generate before building |
DMG_BACKGROUND | — | Path to a background image for the DMG window |
After the Build
- Success — report the DMG path, version, and build number from the script output
- Failure — extract the error lines from xcodebuild output and summarize what went wrong
- Version bump — if the script bumped the VERSION file, remind the user to commit it
ExportOptions.plist
If the project doesn't have one, create a minimal scripts/ExportOptions.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>method</key>
<string>development</string>
<key>signingStyle</key>
<string>automatic</string>
</dict>
</plist>
For distribution outside the App Store, change method to developer-id and ensure the team has a Developer ID certificate.
Do NOT create or modify ExportOptions.plist without asking the user first.
