Index of every page on this site: llms.txt
All skills
dimillian avatar

/macos-spm-app-packaging

@05ba982 official
by Thomas Ricouarddimillian/skills4k stars
208
Run it yourself

Scaffold, build, and package SwiftPM-based macOS apps without an Xcode project. Use when you need a from-scratch macOS app layout, SwiftPM targets/resources, a custom .app bundle assembly script, or signing/notarization/appcast steps outside Xcode.

Use this Skill: https://skilld.dev/gh/dimillian/skills/macos-spm-app-packaging

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈68 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈979 more on demand in 4 files.

Description uses 3.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈274 characters, or 3.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

macOS SwiftPM App Packaging (No Xcode)

Overview

Bootstrap a complete SwiftPM macOS app folder, then build, package, and run it without Xcode. Use assets/templates/bootstrap/ for the starter layout and references/packaging.md + references/release.md for packaging and release details.

Two-Step Workflow

  1. Bootstrap the project folder

    • Copy assets/templates/bootstrap/ into a new repo.
    • Rename MyApp in Package.swift, Sources/MyApp/, and version.env.
    • Customize APP_NAME, BUNDLE_ID, and versions.
  2. Build, package, and run the bootstrapped app

    • Copy scripts from assets/templates/ into your repo (for example, Scripts/).
    • Build/tests: swift build and swift test.
    • Package: Scripts/package_app.sh.
    • Run: Scripts/compile_and_run.sh (preferred) or Scripts/launch.sh.
    • Release (optional): Scripts/sign-and-notarize.sh and Scripts/make_appcast.sh.
    • Tag + GitHub release (optional): create a git tag, upload the zip/appcast to the GitHub release, and publish.

Minimum End-to-End Example

Shortest path from bootstrap to a running app:

# 1. Copy and rename the skeleton
cp -R assets/templates/bootstrap/ ~/Projects/MyApp
cd ~/Projects/MyApp
sed -i '' 's/MyApp/HelloApp/g' Package.swift version.env

# 2. Copy scripts
cp assets/templates/package_app.sh Scripts/
cp assets/templates/compile_and_run.sh Scripts/
chmod +x Scripts/*.sh

# 3. Build and launch
swift build
Scripts/compile_and_run.sh

Validation Checkpoints

Run these after key steps to catch failures early before proceeding to the next stage.

After packaging (Scripts/package_app.sh):

# Confirm .app bundle structure is intact
ls -R build/HelloApp.app/Contents

# Check that the binary is present and executable
file build/HelloApp.app/Contents/MacOS/HelloApp

After signing (Scripts/sign-and-notarize.sh or ad-hoc dev signing):

# Inspect signature and entitlements
codesign -dv --verbose=4 build/HelloApp.app

# Verify the bundle passes Gatekeeper checks locally
spctl --assess --type execute --verbose build/HelloApp.app

After notarization and stapling:

# Confirm the staple ticket is attached
stapler validate build/HelloApp.app

# Re-run Gatekeeper to confirm notarization is recognised
spctl --assess --type execute --verbose build/HelloApp.app

Common Notarization Failures

Symptom Likely Cause Recovery
The software asset has already been uploaded Duplicate submission for same version Bump BUILD_NUMBER in version.env and repackage.
Package Invalid: Invalid Code Signing Entitlements Entitlements in .entitlements file don't match provisioning Audit entitlements against Apple's allowed set; remove unsupported keys.
The executable does not have the hardened runtime enabled Missing --options runtime flag in codesign invocation Edit sign-and-notarize.sh to add --options runtime to all codesign calls.
Notarization hangs / no status email xcrun notarytool network or credential issue Run xcrun notarytool history to check status; re-export App Store Connect API key if expired.
stapler validate fails after successful notarization Ticket not yet propagated Wait ~60 s, then re-run xcrun stapler staple.

Templates

  • assets/templates/package_app.sh: Build binaries, create the .app bundle, copy resources, sign.
  • assets/templates/compile_and_run.sh: Dev loop to kill running app, package, launch.
  • assets/templates/build_icon.sh: Generate .icns from an Icon Composer file (requires Xcode install).
  • assets/templates/sign-and-notarize.sh: Notarize, staple, and zip a release build.
  • assets/templates/make_appcast.sh: Generate Sparkle appcast entries for updates.
  • assets/templates/setup_dev_signing.sh: Create a stable dev code-signing identity.
  • assets/templates/launch.sh: Simple launcher for a packaged .app.
  • assets/templates/version.env: Example version file consumed by packaging scripts.
  • assets/templates/bootstrap/: Minimal SwiftPM macOS app skeleton (Package.swift, Sources/, version.env).

Notes

  • Keep entitlements and signing configuration explicit; edit the template scripts instead of reimplementing.
  • Remove Sparkle steps if you do not use Sparkle for updates.
  • Sparkle relies on the bundle build number (CFBundleVersion), so BUILD_NUMBER in version.env must increase for each update.
  • For menu bar apps, set MENU_BAR_APP=1 when packaging to emit LSUIElement in Info.plist.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides templates, scripts, and documentation to scaffold, build, and package SwiftPM-based macOS apps without Xcode. All scripts utilize standard development tools (such as swift build, codesign, and openssl) for local development workflows. No security issues, malicious behaviors, or data exfiltration risks were detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    12/15 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 05ba982. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 9 months ago
  • macos
  • swift
  • spm
  • packaging
  • code-signing
  • notarization
  • app-bundle
  • sparkle

README badge

README badge for dimillian/skills/macos-spm-app-packaging

Scaffolds, builds, and packages SwiftPM-based macOS apps without Xcode, including bundle assembly, code signing, notarization, and Sparkle appcast generation. Targets developers who want to manage macOS app distribution via shell scripts and SwiftPM instead of an Xcode project.

Generated from the current SKILL.md.

Does this skill work with Xcode projects?
No. This skill is designed for SwiftPM-based macOS apps built without an Xcode project file. It provides templates and scripts for bootstrapping, building, and packaging from the command line.
How do I notarize and distribute the app?
Use the included `sign-and-notarize.sh` script to notarize with Apple, staple the ticket, and zip the app. Then create a GitHub release and optionally generate a Sparkle appcast with `make_appcast.sh` for automatic updates.
What if notarization fails with 'Invalid Code Signing Entitlements'?
Audit the `.entitlements` file to remove unsupported keys and ensure they match Apple's allowed set. The skill includes a troubleshooting table with recovery steps for common notarization failures.
Can I use this for menu bar apps?
Yes. Set `MENU_BAR_APP=1` when running the packaging script to emit the `LSUIElement` key in Info.plist.
Do I need Xcode installed to use this skill?
No, except for the optional `build_icon.sh` template, which requires Xcode to generate .icns files from an Icon Composer file.

Generated from the current SKILL.md. These answers refresh after source changes.