sjs/gh-Dimillian-Skills
1
0
Fork 0
mirror of https://github.com/Dimillian/Skills.git synced 2026-03-25 08:55:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
gh-Dimillian-Skills/macos-spm-app-packaging/SKILL.md
Alan Pope 3db84e63d0
feat: improve 8 skills with targeted optimizations 
Hullo @dimillian 👋

I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the before/after:

| Skill | Before | After | Change |
|-------|--------|-------|--------|
| swiftui-ui-patterns | 81% | 100% | +19% |
| github | 85% | 100% | +15% |
| macos-spm-app-packaging | 86% | 100% | +14% |
| react-component-performance | 86% | 100% | +14% |
| swift-concurrency-expert | 88% | 100% | +12% |
| app-store-changelog | 93% | 100% | +7% |
| ios-debugger-agent | 94% | 100% | +6% |
| swiftui-view-refactor | 93% | 95% | +2% |
| swiftui-liquid-glass | 100% | 100% | — |
| swiftui-performance-audit | 100% | 100% | — |

<details>
<summary>Changes made</summary>

**swiftui-ui-patterns** — Expanded description with additional trigger terms (VStack/HStack, @State, @Binding, navigation hierarchies, custom view modifiers). Added explicit build validation checkpoints and error recovery guidance to the workflow steps.

**github** — Added explicit "Use when..." clause with natural trigger terms (check CI status, create PR, list issues). Added a structured "Debugging a CI Failure" numbered workflow organizing existing commands into a clear investigation sequence.

**macos-spm-app-packaging** — Added a minimum end-to-end example (bootstrap to running app). Added validation checkpoints after packaging, signing, and notarization with specific verification commands (codesign, spctl, stapler). Added a common notarization failures troubleshooting table.

**react-component-performance** — Added three concrete before/after code examples (isolate ticking state, stabilize callbacks with useCallback + memo, derived data with useMemo). Expanded profiling validation with explicit React DevTools Profiler steps.

**swift-concurrency-expert** — Expanded description with concrete actions (adding Sendable conformance, @MainActor annotations, resolving actor isolation warnings). Added verification step to workflow. Added three before/after Swift code examples covering @MainActor, protocol conformance isolation, and @concurrent.

**app-store-changelog** — Added commit-to-bullet transformation examples showing how raw commits map to user-facing App Store bullets, plus examples of internal-only commits that get dropped. Added a complete example "What's New" output block.

**ios-debugger-agent** — Added build failure handling and post-launch verification checkpoints to the core workflow (verify app launched via describe_ui or screenshot before proceeding to UI interaction).

**swiftui-view-refactor** — Tightened prose in sections 3, 3b, and large-view handling. Removed a redundant example. Converted workflow list to clean numbered format.

</details>

Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.

If you want to run reviews, evals and optimizations yourself, just `npm install @tessl/cli` then run `tessl skill review path/to/your/SKILL.md`, and click here (https://tessl.io/registry/skills/submit) to find out more.

Thanks in advance 🙏
2026-03-06 16:53:32 +00:00

4.7 KiB
Raw Blame History

name description
macos-spm-app-packaging 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.

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.