new-mac-app
Create a native macOS SwiftUI app from a working template (Swift package, SwiftData, build script, icon script, snapshot mode, git), with no Xcode GUI. Use when the user wants to start a new Mac app or scaffold a macOS project.
Install
npx skills add https://github.com/daveebbelaar/bama/tree/main/skills/start/new-mac-app
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install daveebbelaar-bama@llmmart
git clone https://github.com/daveebbelaar/bama.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole daveebbelaar/bama collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
New Mac app
The template builds and runs as is. The first build proves the toolchain works before you write feature code.
What the template is
A Swift package with one executable target, plus a script that wraps the
binary in a real .app bundle. An agent can read and edit every file.
<AppName>/
Package.swift macOS 26, Swift 6.2 tools, main-actor default isolation
Info.plist.in bundle id, name, icon, minimum macOS
Icon/AppIcon.icon the app icon: Icon Composer file, JSON plus SVG layers
build.sh swift build -> .app bundle -> codesign -> ~/Applications
CLAUDE.md build, check, and design rules for agents
Sources/<AppName>/
App.swift window, menus, Settings, database location
Models.swift SwiftData models, sidebar pages, AppModel
ContentView.swift NavigationSplitView: sidebar, list, detail
Snapshot.swift APP_SNAPSHOT mode: PNG and layout file per page and Settings tab, light and dark
UI/Theme.swift accent colors, saved choice, accent tokens
SettingsView.swift Settings window: one tab per topic, sized to content
UI/AppearanceSettings.swift Settings: accent picker (mode follows the Mac)
UI/WindowBehavior.swift no focus ring on open, fit to content
UI/Grid.swift the 4 pt spacing scale, layout probes, grid overlay
tools/
grid-lint.sh flags spacing numbers off the 4 pt grid
check-layout.swift checks the layout files from snapshot mode
make_icon.sh Icon/AppIcon.icon -> Resources/Assets.car + AppIcon.icns (actool)
icon_review.sh renders every icon look into one PNG (ictool)
icon_sheet.swift joins the renders for icon_review.sh
Steps
Check the toolchain:
swift --version # Swift 6.2 or later sw_vers -productVersion # 26.0 or laterOn macOS 15, set
.macOS(.v15)inPackage.swiftandLSMinimumSystemVersionto 15 inInfo.plist.in, and skip Liquid Glass APIs.Pick the name (one UpperCamelCase word) and bundle id (reverse DNS). If
docs/BRIEF.mdexists, use its name.Run the script with the parent folder. It copies the template, fills in the name and bundle id, runs
git init, and commits. It keeps a folder that holds only a brief."${CLAUDE_SKILL_DIR}/scripts/new-app.sh" Tasks com.yourname.tasks ~/DeveloperIn a Dropbox or iCloud Drive folder the script can take minutes: run it in the background.
Build the app and its icon, then open it:
cd ~/Developer/Tasks && ./build.sh --openRun the checks the template ships with, then look at the snapshots (
build-and-verifyskill):swift test --scratch-path ~/Library/Developer/Tasks/test-build # Kit unit tests tools/selftest.sh # PASS per check, exit 0 tools/snap.sh # sample data, light and dark PNGsIf
docs/BRIEF.mdexists, renameItemto the brief's main type and the sidebar pages to the brief's pages. Nothing else: features go throughimprove-loop, one story at a time. Build, snapshot, commit.
When to switch to an Xcode project
The Swift package covers most personal apps. Switch to an XcodeGen project
(project.yml -> generated .xcodeproj, built with xcodebuild) when the
app needs App Intents for Shortcuts and Spotlight, an asset catalog, app
extensions, or widgets. Keep project.yml in git and the .xcodeproj out
of it. Put build output outside Dropbox with -derivedDataPath.
Signing
build.sh signs with the first "Apple Development" certificate in the
keychain, or ad hoc without one. Permissions (Accessibility, Screen
Recording, camera) are stored per signature and path. Ad hoc builds ask
again after every rebuild. A free Apple ID makes a certificate in Xcode >
Settings > Accounts > Manage Certificates. Install to the same path every
time.
A CLI for agents
To let Claude Code, Codex, or scripts read and change the app's data, call
the Skill tool with agent-cli. The app binary becomes its own CLI and
sends each command to the running app, so the database keeps one writer
and the window updates live.
When the build fails
cannot find 'X' in scopeafter adding a file: SwiftPM cached the file list. Runswift package clean --scratch-path ~/Library/Developer/<AppName>/build.binary is older than ...: a file did not compile. Read the first errors.- Concurrency errors: call the Skill tool with
swift-swiftui.
Done when the app opens from ~/Applications, the snapshots show every
page in light and dark, and the first commit exists.
Files (bama)
-
agents
-
openai.yaml 91 B
Loading…
-
-
scripts
-
new-app.sh 2.3 KB
Loading…
-
-
template
-
Icon
-
AppIcon.icon
-
Assets
-
back.svg 172 B · in bundle
-
front.svg 173 B · in bundle
-
-
icon.json 481 B
Loading…
-
-
-
Sources
-
__APP_NAME__
-
UI
-
AppearanceSettings.swift 6.1 KB · in bundle
-
Grid.swift 5.7 KB · in bundle
-
Theme.swift 6.1 KB · in bundle
-
WindowBehavior.swift 2.8 KB · in bundle
-
-
App.swift 3.3 KB · in bundle
-
ContentView.swift 2.9 KB · in bundle
-
Models.swift 1.6 KB · in bundle
-
SeedData.swift 1.5 KB · in bundle
-
SelfTest.swift 2.6 KB · in bundle
-
SettingsView.swift 1.6 KB · in bundle
-
Snapshot.swift 5.5 KB · in bundle
-
-
__APP_NAME__Kit
-
ItemTitle.swift 517 B · in bundle
-
-
-
Tests
-
__APP_NAME__KitTests
-
ItemTitleTests.swift 300 B · in bundle
-
-
-
tools
-
check-layout.swift 6.4 KB · in bundle
-
grid-lint.sh 1.2 KB
Loading… -
icon_review.sh 1023 B
Loading… -
icon_sheet.swift 1.6 KB · in bundle
-
make_icon.sh 1.2 KB
Loading… -
selftest.sh 340 B
Loading… -
snap.sh 778 B
Loading…
-
-
.gitignore 80 B · in bundle
-
build.sh 2.6 KB
Loading… -
CLAUDE.md 3.7 KB
Loading… -
Info.plist.in 926 B · in bundle
-
Package.swift 621 B · in bundle
-
-
SKILL.md 5.1 KB
--- name: new-mac-app description: Create a native macOS SwiftUI app from a working template (Swift package, SwiftData, build script, icon script, snapshot mode, git), with no Xcode GUI. Use when the user wants to start a new Mac app or scaffold a macOS project. argument-hint: "<AppName> <bundle-id> [parent-folder]" allowed-tools: Bash(*/new-app.sh *) Bash(git *) Bash(swift *) Read Write Edit --- # New Mac app The template builds and runs as is. The first build proves the toolchain works before you write feature code. ## What the template is A Swift package with one executable target, plus a script that wraps the binary in a real `.app` bundle. An agent can read and edit every file. ```text <AppName>/ Package.swift macOS 26, Swift 6.2 tools, main-actor default isolation Info.plist.in bundle id, name, icon, minimum macOS Icon/AppIcon.icon the app icon: Icon Composer file, JSON plus SVG layers build.sh swift build -> .app bundle -> codesign -> ~/Applications CLAUDE.md build, check, and design rules for agents Sources/<AppName>/ App.swift window, menus, Settings, database location Models.swift SwiftData models, sidebar pages, AppModel ContentView.swift NavigationSplitView: sidebar, list, detail Snapshot.swift APP_SNAPSHOT mode: PNG and layout file per page and Settings tab, light and dark UI/Theme.swift accent colors, saved choice, accent tokens SettingsView.swift Settings window: one tab per topic, sized to content UI/AppearanceSettings.swift Settings: accent picker (mode follows the Mac) UI/WindowBehavior.swift no focus ring on open, fit to content UI/Grid.swift the 4 pt spacing scale, layout probes, grid overlay tools/ grid-lint.sh flags spacing numbers off the 4 pt grid check-layout.swift checks the layout files from snapshot mode make_icon.sh Icon/AppIcon.icon -> Resources/Assets.car + AppIcon.icns (actool) icon_review.sh renders every icon look into one PNG (ictool) icon_sheet.swift joins the renders for icon_review.sh ``` ## Steps 1. Check the toolchain: ```bash swift --version # Swift 6.2 or later sw_vers -productVersion # 26.0 or later ``` On macOS 15, set `.macOS(.v15)` in `Package.swift` and `LSMinimumSystemVersion` to 15 in `Info.plist.in`, and skip Liquid Glass APIs. 2. Pick the name (one UpperCamelCase word) and bundle id (reverse DNS). If `docs/BRIEF.md` exists, use its name. 3. Run the script with the parent folder. It copies the template, fills in the name and bundle id, runs `git init`, and commits. It keeps a folder that holds only a brief. ```bash "${CLAUDE_SKILL_DIR}/scripts/new-app.sh" Tasks com.yourname.tasks ~/Developer ``` In a Dropbox or iCloud Drive folder the script can take minutes: run it in the background. 4. Build the app and its icon, then open it: ```bash cd ~/Developer/Tasks && ./build.sh --open ``` 5. Run the checks the template ships with, then look at the snapshots (`build-and-verify` skill): ```bash swift test --scratch-path ~/Library/Developer/Tasks/test-build # Kit unit tests tools/selftest.sh # PASS per check, exit 0 tools/snap.sh # sample data, light and dark PNGs ``` 6. If `docs/BRIEF.md` exists, rename `Item` to the brief's main type and the sidebar pages to the brief's pages. Nothing else: features go through `improve-loop`, one story at a time. Build, snapshot, commit. ## When to switch to an Xcode project The Swift package covers most personal apps. Switch to an XcodeGen project (`project.yml` -> generated `.xcodeproj`, built with `xcodebuild`) when the app needs App Intents for Shortcuts and Spotlight, an asset catalog, app extensions, or widgets. Keep `project.yml` in git and the `.xcodeproj` out of it. Put build output outside Dropbox with `-derivedDataPath`. ## Signing `build.sh` signs with the first "Apple Development" certificate in the keychain, or ad hoc without one. Permissions (Accessibility, Screen Recording, camera) are stored per signature and path. Ad hoc builds ask again after every rebuild. A free Apple ID makes a certificate in Xcode > Settings > Accounts > Manage Certificates. Install to the same path every time. ## A CLI for agents To let Claude Code, Codex, or scripts read and change the app's data, call the Skill tool with `agent-cli`. The app binary becomes its own CLI and sends each command to the running app, so the database keeps one writer and the window updates live. ## When the build fails - `cannot find 'X' in scope` after adding a file: SwiftPM cached the file list. Run `swift package clean --scratch-path ~/Library/Developer/<AppName>/build`. - `binary is older than ...`: a file did not compile. Read the first errors. - Concurrency errors: call the Skill tool with `swift-swiftui`. Done when the app opens from `~/Applications`, the snapshots show every page in light and dark, and the first commit exists.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.