macos-app-scaffold
Skill14 starsChanged 6 months agoMITView on GitHub
Scaffold a production-ready native macOS app project (SwiftUI + SwiftData + SPM) with auto-update via GitHub Releases, dev/release build scripts, in-app localization, menu-bar persistence, and a landing-page template. Use when the user says: "new macos app", "scaffold mac app", "create macos app", "swiftui scaffold", "新建 mac 应用", "脚手架", "生成 macOS 项目", "搭一个 swift app", or asks to start a fresh native macOS app project.
In this repository14 other files it gives its agents.
- app-icon-generatorSkill
- break-itSkill
- debug-modeSkill
- dev-launcherSkill
- diagram-proSkill
- image-uploadSkill
- localizeSkill
- mac-app-uninstallSkill
- mac-cleanup-diskSkill
- mac-cleanup-memorySkill
- mac-cleanup-processSkill
- npm-safetySkill
- root-causeSkill
- skill-scanSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Verify the development environment before starting.
- Distinctive: line 105
After appInfo: About, Check for Updates, Support the Developer (heart icon)
- Very specific: line 113
Only the menu bar's "Quit" button sets shouldReallyQuit = true
- Distinctive: line 200
All copy managed via a JS object, swap page text dynamically on switch
- Very specific: line 203
Default follows system (prefers-color-scheme), switches automatically
- Distinctive: line 206
Use CSS variables for color themes so every element (backgrounds, text, cards, code blocks, etc.) adapts
- Very specific: line 242
Run ./scripts/build-dev.sh to verify the project builds and launches
- Distinctive: line 245
Create a GitHub repo if needed
- Distinctive: line 246
Add SwiftData models under Models/
- Distinctive: line 247
Add views and business logic
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Create a macOS App Project
Generates a production-grade native macOS app scaffold based on best practices distilled from shipped projects like TaskTick.
Pre-flight Checks
Verify the development environment before starting. Stop and guide the user to install anything that's missing:
xcodebuild -version 2>/dev/null | head -1
swift --version 2>/dev/null | head -1- Xcode >= 16 (i.e.
xcodebuild -versionreportsXcode 16.xor higher). The scaffold usesswift-tools-version: 6.0; Xcode 15 will fail SPM resolution. Xcode 15 users should upgrade, or confirm they're OK downgrading the generated project to Swift 5.9. - Swift >= 6.0 (same reason as above)
- Generation location defaults to the user's home directory. Confirm with the user first if they want a different location.
Usage
/macos-app-scaffold <AppName> [--bundle-id com.example.app] [--github user/repo]AppName: required, PascalCase (e.g.MyApp)--bundle-id: optional, defaults tocom.example.<AppName>(please change to your own reverse domain on first use)--github: optional, GitHub repo used for auto-update, format<owner>/<repo>
Generated Output
Generates the project structure below. Ask the user for the creation location first (default: ~/<AppName>-app/).
Project Structure
<AppName>-app/
├── Package.swift
├── Sources/
│ ├── App/
│ │ ├── <AppName>App.swift # @main, multi-window Scene, ModelContainer
│ │ ├── AppDelegate.swift # Cmd+Q → hide to menu bar, shouldReallyQuit
│ │ └── Localization.swift # L10n.tr() helper + LanguageManager
│ ├── Engine/
│ │ ├── UpdateChecker.swift # GitHub Releases API, DMG download/install/restart
│ │ └── NotificationManager.swift
│ ├── Models/
│ │ └── (empty directory, user adds SwiftData models here)
│ ├── Views/
│ │ ├── Main/
│ │ │ └── MainWindowView.swift # NavigationSplitView layout
│ │ ├── MenuBar/
│ │ │ └── MenuBarView.swift # MenuBarExtra popover content
│ │ ├── Settings/
│ │ │ └── SettingsView.swift # TabView: General, Updates, About
│ │ └── Components/
│ │ ├── GlassCard.swift # macOS 26 liquid glass + fallback
│ │ └── PointerCursor.swift # .pointerCursor() pointing-hand modifier
│ ├── Localization/
│ │ ├── en.lproj/
│ │ │ └── Localizable.strings
│ │ └── zh-Hans.lproj/
│ │ └── Localizable.strings
│ └── Resources/
│ └── AppIcon.icns # placeholder icon, user replaces
├── Tests/
│ └── <AppName>Tests.swift
├── scripts/
│ ├── build-dev.sh # dev build: grayscale icon, separate bundle ID
│ └── release.sh # release: arm64 + x86_64 DMG, upload to GitHub Release
├── docs/
│ └── index.html # static landing page, auto-deployed via GitHub Pages
├── .gitignore
├── LICENSE # ask user which open-source license to use
├── CLAUDE.md # Claude Code project documentation
└── .claude/
└── skills/
└── release/
└── SKILL.md # /release <version> release skillImplementation Rules
Strictly follow these rules when generating code:
Package.swift
- swift-tools-version: 6.0
defaultLocalization: "en"platforms: [.macOS(.v14)]- Resources:
.process("Localization")
App Entry Point (<AppName>App.swift)
- Multi-window:
Window(main window) +MenuBarExtra+Settings+ editor windows, etc. ModelContainerdatabase isolation: dev bundle ID →<appname>-dev.store, release →default.store- Complete
.commands {}menu structure:- After appInfo: About, Check for Updates, Support the Developer (heart icon)
- newItem: app-specific actions
- After toolbar: Refresh
- help: GitHub homepage, Report Issue
AppDelegate
shouldReallyQuitstatic flagapplicationShouldTerminate: if shouldReallyQuit is false → close windows, hide to menu bar, return.terminateCancel- Only the menu bar's "Quit" button sets
shouldReallyQuit = true
UpdateChecker (auto-update)
- Polls GitHub Releases API:
https://api.github.com/repos/<owner>/<repo>/releases/latest - Compares semver versions, shows UpdateDialogView: Skip This Version / Remind Me Later / Install Now
- Download DMG → mount → copy .app to /Applications → unmount → relaunch via
open - Dev builds (bundle ID ending in
.dev) skip update checks - Configurable check interval (defaults to 24 hours)
Localization
L10n.tr("key")andL10n.tr("key", arg)helpersLanguageManagersingleton, uses@AppStorage("appLanguage").localized()view modifier, triggers re-render on language change- Bundle.module case-insensitive
.lprojfolder lookup - Two languages: en, zh-Hans. Every string must be present in both files.
SettingsView (settings window)
TabViewwith each tab usingForm { ... }.formStyle(.grouped).frame(width: 460).fixedSize(horizontal: false, vertical: true)for fixed width and adaptive height- Tabs: General (appearance, language, launch at login), Updates (auto-check, frequency, check now), About (version, build, links, copyright)
General Tab — Appearance:
- Appearance mode picker: Follow System / Light / Dark
- Persisted via
@AppStorage("appearanceMode") - Calls
NSApp.appearance = NSAppearance(named:)on change for instant effect
General Tab — Language:
- Language picker: lists all supported languages (en, zh-Hans)
- Bound to
LanguageManager.shared.current - Most UI updates immediately after switching (via
.localized()modifier) - Help text below explains the switching behavior
GlassCard
- macOS 26+: uses
.glassEffect()(when available) - Fallback for older versions:
.background(.ultraThinMaterial)with rounded corners and thin border
PointerCursor
- ViewModifier that sets
NSCursor.pointingHandon hover - Applied to all buttons, links, and clickable list rows
Dev Build Script (build-dev.sh)
- Builds debug config to
.dev-build/ - Creates .app with dev bundle ID (
<bundle-id>.dev) - Uses sips to convert original icon to grayscale for visual distinction
- Dev app name:
<AppName> Dev - Kills any old instance and relaunches after build
- Signs with
codesign --force --deep --no-strict --sign - - Resource bundles placed at .app root (not Contents/Resources/) to match SPM Bundle.module
Release Script (release.sh)
- Accepts version number as argument
- Builds release configs for arm64 and x86_64 separately
- Creates .app bundle with proper Info.plist (version injected)
- Produces DMGs:
<AppName>-<version>-arm64.dmgand<AppName>-<version>-x86_64.dmg - Creates GitHub tag + release, uploads DMGs as assets
- Resource bundle layout matches the dev build
.gitignore
.build/
.dev-build/
.release/
.swiftpm/
*.xcodeproj
*.xcworkspace
DerivedData/
.DS_Store
# AI tools
.claude/
.cursor/
.windsurf/
.copilot/
CLAUDE.mdLanding Page (docs/index.html)
- Static single-page, placed in
docs/ - Deployed via GitHub Pages (Settings → Pages → Source: Deploy from branch, Branch: main, Folder: /docs)
- Auto-deploys on push, no extra CI needed
- Modern minimalist style; you can use the
/frontend-designskill to generate high-quality UI
i18n language support:
- Minimum coverage: Chinese (zh), English (en), Japanese (ja), Korean (ko), French (fr), German (de), Spanish (es)
- Language switcher in the top nav bar, using a dropdown or toggle button
- Auto-detect browser language (
navigator.language), default to the closest match - Persist language choice to
localStorage - All copy managed via a JS object, swap page text dynamically on switch
Dark / Light mode:
- Default follows system (
prefers-color-scheme), switches automatically - Manual toggle button (sun/moon icon) in the nav bar
- User's manual selection persisted to
localStorage, takes precedence over system preference - Use CSS variables for color themes so every element (backgrounds, text, cards, code blocks, etc.) adapts
Page content structure:
- Hero section: app name, tagline, download button
- Screenshots: carousel or grid
- Features: grid of cards highlighting core features
- Sponsor section (standalone): heading + description + sponsorship methods (WeChat/Alipay QR codes, PayPal button, etc.)
- Install methods: Homebrew command + manual download
- Tech stack & open-source info
- Footer: copyright, GitHub link
Top nav bar:
- App name / logo
- Anchor links to feature sections
- Sponsor link (heart icon + text), prominent but not intrusive
- Language switcher
- Dark / light toggle
- GitHub icon link
LICENSE
- You MUST ask the user first which open-source license they want — do not pick a default
- Common options for reference: GPL-3.0, MIT, Apache-2.0, BSL, proprietary
- Generate the appropriate LICENSE file based on the user's choice
CLAUDE.md
Generate a standard project documentation file that includes:
- Build and run commands
- Architecture overview
- Key design patterns
- Anti-crash rules (no force-unwrap, NSView lifecycle gotchas)
- Compatibility requirements
- Localization usage notes
After Scaffolding
- Initialize git:
git init && git add -A && git commit -m "Initial project scaffold" - Run
./scripts/build-dev.shto verify the project builds and launches - Tell the user what was created and the next steps:
- Replace AppIcon.icns with your own icon (or use
/app-icon-generatorto generate one) - Create a GitHub repo if needed
- Add SwiftData models under Models/
- Add views and business logic
- Replace AppIcon.icns with your own icon (or use
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

