Skip to main content
skill CX Codex

new-mac-app — Claude Code skill: what it does, how to install

new-mac-app is a Claude Code skill that scaffolds a native SwiftUI macOS app from a working template. It starts when a new Mac app or project skeleton is requested.

MIT 1,000 installs ★ 1,933 updated 2026-11-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill new-mac-app -a claude-code
Open on GitHub

What new-mac-app does

new-mac-app creates a native SwiftUI macOS app without the Xcode GUI. It copies a Swift package with one executable target, fills in the app name and bundle ID, initializes git, and creates the first commit. The template includes SwiftData, build.sh, icon tooling, settings, navigation, tests, and interface snapshot mode.

The workflow builds an .app, signs it, opens it from ~/Applications, then runs swift test, self-checks, and light and dark snapshots. It needs Swift 6.2 or later and macOS 26. On macOS 15, Package.swift must use .macOS(.v15), Info.plist.in must set minimum version 15, and Liquid Glass APIs must be skipped.

The Swift package covers apps that do not need an Xcode project. App Intents, extensions, widgets, or an asset catalog require switching to XcodeGen and xcodebuild. Signing uses the first “Apple Development” certificate in the keychain, or an ad hoc signature when that certificate is unavailable.

What it helps with

  • scaffold a native SwiftUI macOS app
  • turn a Swift package into a signed .app
  • create and inspect the app icon
  • run tests, self-checks, and interface snapshots

Example prompts for the agent

  • Create a macOS app named Tasks with bundle ID com.yourname.tasks inside ~/Developer.
  • Scaffold a new SwiftUI Mac project from the template and open it after building.
  • Set up a SwiftData app with settings plus light and dark interface snapshots.

How to install new-mac-app

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill new-mac-app -a claude-code

2Manually: put the files in place

~/.claude/skills/new-mac-app/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/new-mac-app/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about new-mac-app

How do I install new-mac-app in Claude Code?

Run npx skills add daveebbelaar/bama --skill new-mac-app -a claude-code, then check ~/.claude/skills/new-mac-app/SKILL.md.

What does new-mac-app do?

It scaffolds a SwiftUI macOS app from a working Swift package and includes app bundling, icon generation, SwiftData, git setup, tests, and interface checks.

What does new-mac-app require?

It requires Swift 6.2 or later and macOS 26. Signing uses an “Apple Development” certificate, with ad hoc signing available when that certificate is absent.

Source text

SKILL.md · MIT
---
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.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Frontend and UI →

From the same set21

The whole set →
user-stories Turns app briefs, research, or screen indexes into prioritized user stories with checkable acceptance criteria. It runs after app-brief or clone, or when asked to plan features and choose what to build first. CX Codex +1 1,000installs swift-swiftui The swift-swiftui Claude Code skill sets Swift 6 and SwiftUI practices for macOS apps. It activates while writing, reviewing, or debugging Swift code, including concurrency and Sendable errors. CX Codex +1 1,000installs design-kit design-kit — a skill for Claude Code and Cursor builds a custom macOS SwiftUI design system with tokens and components. Runs when you need a brand look or custom controls. CX Codex +1 1,000installs design-system The design-system Claude Code skill organizes a macOS app’s accent color and design tokens. It activates for requests about themes, shared screen styles, or a style guide. CX Codex +1 1,000installs test-mac-app The test-mac-app Claude Code skill lays out a testing flow for macOS apps, from Swift tests to controlling a running app. It activates when adding logic, fixing bugs, or checking a release. CX Codex +1 1,000installs ux-design The ux-design skill for Claude Code runs a UX pass for a macOS app feature before coding, covering terminology, flows, surface selection, and accessibility. Runs before coding a story that adds a screen, an action, or text. CX Codex +1 1,000installs bama The bama skill for Claude Code picks the next step in building a native macOS app. It routes work from an initial idea through research, implementation, and verification. CX Codex +1 1,000installs clone This Claude Code skill explores an existing app and documents its screens for a rebuild. It starts when asked to clone, replace, or recreate an app’s design. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open