macOS App Skills：AI Coding Agent でネイティブ Mac アプリを作るための Skill パック

Claude Code で macOS アプリを書いたら、2 万行超の code のうち手書きは 1,000 行未満だった。なぜそんなことができるのか。Indragie は 2025 年の実践記事で、答えをかなり具体的に書いています。Agent がネイティブ Mac アプリを書くと、Swift Concurrency の混乱、新旧 framework の混在、deprecated API の呼び出し、window management の誤解、release pipeline の抜け漏れという 5 つの罠に入りやすい。要するに、Agent は macOS のネイティブ pattern を知らず、Mac を Web ページのように書いてしまうのです。

macos-app-skills は、その問題のための AI Agent 向け Skill パックです。WWDC video、断片的な docs、間違えやすい macOS pattern を 7 つの module に固めています。build、ネイティブ pattern reference、settings window、auto update、notch UI、release pipeline、install integration です。各 module には、what it is、what it solves、typical usage、command、flow、limitation、FAQ という細かな契約表があります。これにより、Agent は最初の一手から外しにくくなります。以下では module ごとに分解し、fireworks-macapp-creator、claude-swift-skills とも比較します。

インストール接続：Agent に Skill パックを読み込ませる

インストール command はシンプルです。

npx skills add fayazara/macos-app-skills -g -y

-g は global install、-y は確認 prompt の skip です。install 後に Agent を再起動すると、skills directory の中身を自動で読み込みます。以前 OpenCode でこの package を試したときは、再起動後の skills list に macos-app-skills の module が追加されていました。build、macos-patterns、settings-ui、auto-update、notch-ui、release です。

前提条件は先にそろえておきます。macOS 14+、Xcode 15+、Swift 5.9+。Liquid Glass のような macOS 26 feature を使いたいなら Xcode 26 beta が必要です。古い version では graceful degradation になり、基本機能はそのまま使えます。

Agent の読み込み確認には注意点があります。Claude Code など一部の Agent は、skills directory path を手動で設定する必要があります。OpenCode は ~/.config/opencode/skills/ を自動認識します。Cursor では project root に .agents/skills/ を置く形です。確認方法は、Agent に loaded skills を列挙させること。あるいは「macos-app-skills の build module を知っている？」と聞き、内容を参照できるか見ます。

よくある失敗は、network と permission の 2 種類です。GitHub assets への access が遅い network では、proxy を使うか数回 retry します。permission 問題は、多くの場合 npx cache directory に書けないことが原因です。sudo npx より、skills directory を手動コピーするほうが安全です。もう 1 つは version mismatch。project は 2026-05 に作られており、skill の数や名前が変わる可能性があります。install 前に GitHub README の最新 list を見てください。

サブモジュール分解

サブモジュール	何か	何を解決するか	典型的な使い方	command	flow	制限	FAQ
install command	npx で Skill パックを global install	Agent が macOS development skill を呼べるようにする	1 行 command で install	npx skills add fayazara/macos-app-skills -g -y	command 実行 → Agent 再起動 → loading 確認	npx と network に依存	network が遅いときは？ proxy か retry
prerequisite check	macOS/Xcode/Swift の version requirement	skill 内の code を実行できる environment か確認	system version、Xcode version、Swift version を確認	sw_vers、xcodebuild -version、swift --version	version 確認 → README requirement と比較 → 足りなければ upgrade	macOS 14+、Xcode 15+、Swift 5.9+	古い version でも使える？ 一部機能は降格
Agent loading verification	Agent が skills を読み込んだか確認	install が有効か検証	Agent に skills list を出させる、または reference test	標準 command はなく Agent 実装に依存	再起動 → loading status を質問 → reference test	Agent ごとに config path が違う	読み込まれないときは？ config path を確認
common failures	network、permission、version の 3 種類	排障 checklist で素早く原因を切り分ける	proxy、permission、version check	固定 command はなく checklist に従う	network 確認 → permission 確認 → version 確認	GitHub access が遅い地域がある	sudo は安全？ できれば使わず手動コピー

build module：command line から macOS project を build する

build module は xcodebuild を使い、任意の macOS Xcode project を command line から build します。つまり Agent が Xcode GUI をクリックせず、terminal command で compile できるようにする module です。

具体的には、project discovery（.xcodeproj や .xcworkspace を探す）、scheme detection（どの target があるか確認する）、beta toolchain handling（Xcode beta の path 問題）、common build failures（scheme not found、signing error など）を扱います。AI が macOS app を書くときの error は、この段階でよく起きます。Agent が渡す parameter を知らなかったり、iOS scheme を macOS scheme として扱ったりするためです。

典型的な使い方は、Agent に build を実行させる前にこの skill を load させることです。project file の探し方、scheme の選び方、error handling を Agent に伝えます。command example：

xcodebuild -project MyApp.xcodeproj -scheme MyApp -configuration Release

workspace を使う場合：

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release clean build

流れはだいたい、project discovery → scheme detection → build execution → error inspection → iterative fix です。Agent はまず .xcodeproj または .xcworkspace を探し、available scheme を list し、適切な scheme を選んで build します。error が出たら skill の troubleshooting checklist に沿って処理します。

制限もはっきりしています。Xcode project 向けであり、SwiftPM-only project には向きません。pure SwiftPM project なら Xcode project に変換するか、別の skill を使う必要があります。beta toolchain にも注意が必要です。Xcode beta の version number や path は標準的でないため、skill には専用の handling logic があります。

FAQ で多いのは「scheme が見つからないときどうするか」です。多くの場合、project に scheme が定義されていないか、scheme name と target name が一致していません。skill は xcodebuild -list で available scheme を先に調べるよう Agent に教えます。もう 1 つは beta toolchain の扱いです。skill は Xcode beta path（通常 /Applications/Xcode-beta.app）を指定し、platform を明示する -destination parameter を渡します。

サブモジュール分解

サブモジュール	何か	何を解決するか	典型的な使い方	command	flow	制限	FAQ
what it is	xcodebuild で macOS project を build	GUI なしで command line compile	Agent が build する前にこの skill を load	下の code block を参照	project discovery → scheme detection → build → error handling	Xcode project のみ	SwiftPM project は？ Xcode project に変換
what it solves	project/scheme/toolchain/failure handling	Agent が正しい parameter を知らない問題	先に project file を探し、次に scheme を選ぶ	xcodebuild -list で scheme を先に確認	execute → error check → iterative fix	beta toolchain path が標準でない	beta toolchain は？ path と destination を指定
typical usage	build 前に Agent に skill を load させる	Agent の parameter guessing を避ける	build skill を先に load	固定 command なし、Agent が skill を使う	load skill → build → error handling	skill は knowledge であって magic ではない	Agent が load しない？ 手動 load か config 確認
command	xcodebuild の standard command	Agent に実行可能な command example を渡す	xcodebuild に直接渡す	xcodebuild -project MyApp.xcodeproj -scheme MyApp	parameter 付きで実行 → 結果待ち → error parse	parameter format が正しい必要あり	scheme name は？ -list で確認
flow	build → check error → fix	standard build flow	手順通り実行	固定 command なし、logic としての flow	discover → detect → build → inspect → fix	flow を飛ばさない	build failure は？ skill の checklist を見る
limitation	Xcode project support scope	適用条件を明示	Xcode project にだけ使う	なし	なし	SwiftPM は直接 support しない	なぜ SwiftPM 非対応？ xcodebuild 前提の skill だから
FAQ	scheme not found、beta toolchain	common question の answer	available scheme を調べ、beta path を指定	xcodebuild -list	check → query → specify	beta toolchain には追加設定が必要	beta かどうかは？ version と path で判断

macos-patterns module：Agent が Mac を Web として書くのを防ぐ

macos-patterns module は、この Skill パックの中心です。macOS の native pattern を参照可能な形にし、Agent が Web 的な発想で Mac app を書くのを防ぎます。多くの SwiftUI Agent skill には似た問題があります。Agent は Web 風 UI を書けても、menu bar、window hierarchy、screen geometry といった macOS 固有概念を理解していないのです。

具体的な pain point は次のとおりです。

1. menu bar app の 3 方式：MenuBarExtra（SwiftUI native）、NSStatusItem（古い AppKit）、NSPopover（pop-up window）。Agent は混同しやすく、選び方を間違えると macOS らしくない UI になります。
2. activation policy：Dock icon toggle、LSUIElement config、NSApplication.setActivationPolicy()。知らないと background app を foreground app のように書いてしまいます。
3. NSPanel vs NSWindow：floating window（Inspector などの NSPanel）と normal window（NSWindow）の違い。ここを間違えると window behavior が期待とずれます。
4. window level と collection behavior：CGShieldingWindowLevel、NSWindow.Level、collectionBehavior（multi-screen、full-screen behavior）。知らないと window が変な layer に出たり、screen をまたいで崩れたりします。
5. screen geometry：frame vs visibleFrame（Dock/menu bar を含むか）、Y axis flip（macOS coordinate は左下原点）、multi-screen handling。WWDC video には出てくる細部ですが、Agent が知っているとは限りません。
6. keyboard shortcut の 3 段階：SwiftUI .keyboardShortcut()（simple）、NSEvent monitor（global）、Carbon hotkey（system-level）。Agent は適切な tier を選び間違えがちです。
7. その他の pattern：file picker（NSOpenPanel）、clipboard（NSPasteboard）、drag and drop（NSDragging）、NavigationSplitView + inspector、launch at login（LaunchAgent）、Quick Look（QLPreviewPanel）、NSWorkspace、ScreenCaptureKit、UserDefaults/@AppStorage persistence。

典型的な使い方：macOS UI を書かせる前に、この skill を明示的に load します。menu bar app を作りたいなら、「macos-patterns ではどの menu bar 方式を推奨している？」と聞きます。MenuBarExtra は SwiftUI native の推奨、NSStatusItem は AppKit の古い選択肢だと返せるはずです。

pattern list は長いので、skill は各 pattern を recommendation/alternative/use case/code example/limitation の 5 列に分けます。高頻度のものをいくつか見ます。

menu bar app comparison

方式	推奨/代替	適用場面	code example	制限
MenuBarExtra	推奨	SwiftUI native、simple case	MenuBarExtra("App", systemImage: "app") { ContentView() }	macOS 13+
NSStatusItem	代替	complex customization または AppKit interop	NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)	lifecycle を手動管理
NSPopover	補助	click 後に開く popover window	NSPopover() + NSStatusItem	NSStatusItem と組み合わせる必要あり

activation policy comparison

policy	推奨場面	configuration	code	制限
NSApplication.ActivationPolicy.regular	foreground app、Dock icon あり	Info.plist に LSUIElement を設定しない	default behavior	最も一般的
NSApplication.ActivationPolicy.accessory	background app、Dock icon なし、menu bar あり	Info.plist に LSUIElement=true を設定	NSApplication.shared.setActivationPolicy(.accessory)	menu bar は表示される
NSApplication.ActivationPolicy.prohibited	完全 background、UI なし	LaunchAgent configuration	NSApplication.shared.setActivationPolicy(.prohibited)	Dock なし、menu bar なし

window level comparison

type	level value	適用場面	code	制限
NSWindow.Level.normal	0	normal window	default	最も一般的
NSWindow.Level.floating	3	floating window、Inspector など	window.level = .floating	他 app を強く覆わない
CGShieldingWindowLevel	highest	shielding layer、notch UI など	window.level = CGShieldingWindowLevel()	すべてを覆うため慎重に使う

制限：macOS 専用で、iOS は扱いません。cross-platform pattern が必要なら、claude-swift-skills の cross-platform module など別の skill を使います。

FAQ で多いのは、Dock icon をどう切り替えるかです。NSApplication.setActivationPolicy() を動的に使います。multi-screen はどう扱うか。NSScreen.screens で全 screen を列挙し、visibleFrame で Dock/menu bar を除いた usable area を取得します。Y axis flip はどうするか。macOS coordinate は左下原点（0 が左下）です。Agent は Web の左上原点に引きずられやすいため、手動変換が必要です。

settings-ui module：settings window と Liquid Glass

settings-ui module は 2 つの問題を扱います。macOS settings window の正しい実装方法と、Liquid Glass（macOS 26 の新 material）config です。要するに、Agent に SwiftUI の Window scene を雑に使わせず、macOS convention に沿った settings window を書かせるための module です。

具体的な pain point は、SwiftUI の Window scene が fullSizeContentView を support しないことです。そのため settings window の transparent background extension が効きません。Liquid Glass の config を間違えると material も正しく表示されません。Agent が知らないと、system settings window と違う見た目になります。

典型的な使い方：NSWindowController + .fullSizeContentView + NavigationSplitView。skill は complete Swift file を提供しており、project にそのままコピーできます。flow：

1. NSWindowController を作成
2. fullSizeContentView を config
3. NavigationSplitView（sidebar + detail）を追加
4. transparent background を設定
5. Liquid Glass（macOS 26+）を統合

code example（skill には complete file があります）：

// SettingsWindowController.swift
class SettingsWindowController: NSWindowController {
    convenience init() {
        let window = NSWindow(
            contentRect: NSRect(x: 0, y: 0, width: 600, height: 400),
            styleMask: [.titled, .closable, .resizable],
            backing: .buffered,
            defer: false
        )
        window.title = "Settings"
        window.fullSizeContentView = true // 重要な設定
        self.init(window: window)
    }
}

制限：Liquid Glass は macOS 26+ でのみ使えます。古い version では通常の material に graceful fallback します。Liquid Glass が不要なら、この部分は無視して standard SwiftUI WindowGroup を使えます。

FAQ：古い version ではどう fallback するか。skill は system version を check し、material を切り替える fallback code を提供します。sidebar をどう追加するか。NavigationSplitView を使います。skill に complete example があります。

auto-update module：Sparkle auto update integration

auto-update module は、Sparkle auto update integration の timing 問題を解きます。SPUStandardUpdaterController は applicationDidFinishLaunching が戻る前に作成する必要があります。そうしないと update check が失敗することがあります。この detail は Sparkle docs にありますが、Agent はよく見落とします。その結果、user に auto update prompt が出ません。

典型的な使い方：UpdaterManager singleton + Info.plist config + EdDSA key generation。skill は UpdaterManager.swift を提供しており、そのまま使えます。

flow：

1. SPM dependency（Sparkle）を追加
2. UpdaterManager singleton を作成
3. Info.plist（SUFeedURL、SUPublicEDKey）を config
4. Sparkle sign_update で EdDSA key を生成
5. UI（settings toggle + menu bar button）を追加

code example（skill には complete file があります）：

// UpdaterManager.swift
class UpdaterManager {
    static let shared = UpdaterManager()
    private var updaterController: SPUStandardUpdaterController!

    init() {
        // applicationDidFinishLaunching が戻る前に作成する必要があります
        updaterController = SPUStandardUpdaterController(
            startingUpdater: true,
            updaterDelegate: nil,
            userDriverDelegate: nil
        )
    }
}

制限：Mac App Store 外で配布する app 向けです。App Store に出す場合、Sparkle は使えません。App Store の built-in update mechanism を使います。

FAQ：EdDSA key はどう生成するか。Sparkle の sign_update tool を使います。skill には詳細手順があります。update test はどうするか。local feed server を立てるか、release 後に manual update check を trigger します。

notch-ui module：notch area の Dynamic Island 風 UI

notch-ui module は、MacBook の notch area に Dynamic Island 風 floating UI を作るためのものです。普通の window を上端に置くのではなく、iPhone 14 Pro のような notch UI に近い挙動を書かせる module です。

pain point は、特定の NSPanel config（borderless、CGShieldingWindowLevel）、notch 位置を計算する screen geometry math、凹んだ Bezier の「耳」curve を持つ custom shape です。Agent が知らないと、位置がずれたり、形が合わなかったりします。Notch UI macOS SwiftUI project でもよく起きる問題です。

典型的な使い方：borderless NSPanel + CGShieldingWindowLevel + NotchShape。skill は NotchWindow.swift と NotchShape.swift を提供しており、そのままコピーできます。

flow：

1. borderless NSPanel を作成
2. CGShieldingWindowLevel を設定
3. NotchShape（凹 Bezier の「耳」curve）を実装
4. spring animation を追加
5. notch のない Mac には fallback pill mode を用意

code example（skill には complete file があります）：

// NotchWindow.swift
class NotchWindow: NSPanel {
    init() {
        super.init(
            contentRect: calculateNotchFrame(),
            styleMask: [.borderless],
            backing: .buffered,
            defer: false
        )
        level = CGShieldingWindowLevel() // 重要な設定
        backgroundColor = .clear
    }
}

制限：MacBook notch 向けです。iMac や Mac mini など notch のない Mac では fallback pill mode を使います。notch UI が不要なら、この module は無視できます。

FAQ：notch のない Mac ではどうするか。skill は top center に表示する fallback pill mode を提供します。位置調整はどうするか。screen size と notch position から計算します。skill には math formula があります。

release module：complete release pipeline

release module は macOS release pipeline の複雑さを扱います。8+ の manual step は抜け漏れや順序ミスが起きやすい。version bump、Archive、Notarize、Export、DMG creation、EdDSA signing、appcast.xml update、GitHub release。Agent が理解していないと、どれかを飛ばして release failure になったり、update delivery が壊れたりします。

典型的な使い方：release.json を追加し、Go CLI を実行します。skill はそのまま使える Go CLI tool を提供しています。

flow（8 step）：

1. version bump：Info.plist と project file の version を更新
2. Archive：xcodebuild archive で package
3. Notarize：notarytool で公証 submit
4. Export：xcodebuild -exportArchive で .app を export
5. DMG creation：create-dmg で installer を作成
6. EdDSA signing：Sparkle sign_update で署名
7. appcast.xml update：Sparkle generate_appcast で feed を更新
8. GitHub release：gh release create で GitHub に公開

command example：

# Go CLI
go run github.com/fayazara/macos-app-skills/release/cli@latest

または各 step を手動で実行します。skill には complete command list があります。

# Archive
xcodebuild -project MyApp.xcodeproj -scheme MyApp archive

# Notarize
notarytool submit MyApp.zip --apple-id YOUR_ID --password YOUR_PASSWORD --team-id YOUR_TEAM

# Export
xcodebuild -exportArchive -archivePath MyApp.xcarchive -exportOptionsPlist ExportOptions.plist -exportPath .

# DMG
create-dmg --volname "MyApp" --volicon "icon.icns" MyApp.app MyApp.dmg

# EdDSA signing
sign_update MyApp.dmg

# appcast.xml
generate_appcast MyApp.app

# GitHub release
gh release create v1.0.0 MyApp.dmg --title "v1.0.0" --notes "Release notes"

制限：GitHub CLI と Sparkle EdDSA key が必要です。gh を config していないと最後の step で止まります。EdDSA key がないと signing step で止まります。

FAQ：release.json はどう config するか。skill は template を提供し、version number、公証 credential、DMG config などを指定できます。公証 failure はどう扱うか。notarytool の error log を見ます。skill には troubleshooting checklist があります。

サブモジュール分解

サブモジュール	何か	何を解決するか	典型的な使い方	command	flow	制限	FAQ
what it is	complete release pipeline + Go CLI	macOS release の 8 step flow を automate	release.json + Go CLI	go run github.com/fayazara/macos-app-skills/release/cli@latest	version bump → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	GitHub CLI + Sparkle key が必要	GitHub CLI がない？ GitHub に手動 release
what it solves	8+ manual step の抜け漏れ	Agent の step omission による release failure	skill を load し、flow に従う	固定 command なし、step checklist に従う	各 step 実行 → error check → iterative handling	flow を飛ばさない	どこか失敗した？ checklist を見る
typical usage	release.json + Go CLI	standard release implementation	release.json を追加し CLI を実行	上の code block を参照	config → run → result check	release.json は手動 config が必要	release.json は？ skill に template あり
CLI	Go CLI tool	release flow を automate	1 command で release	go run github.com/.../cli@latest	CLI 実行 → 完了待ち → result check	Go environment	Go がない？ 各 step を手動実行
flow	8 step release flow	明確な step checklist	手動または CLI で実行	固定 command なし、logic としての flow	bump → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	step order を変えない	order は変えられる？ 推奨しない
limitation	GitHub CLI + Sparkle key	prerequisite を明示	gh と key config を確認	gh --version、sign_update --help	check → config → execute	tool が欠けると止まる	Sparkle key は？ sign_update tool を使う
FAQ	release.json config、公証 failure	common question の answer	skill template と troubleshooting checklist を使う	固定 command なし	template 確認 → config → error handling	公証は複数回失敗することがある	公証失敗？ notarytool log を確認

3 つの類似 project 比較：どの Skill パックを選ぶか？

macos-app-skills のほかに、似た Skill パックとして fireworks-macapp-creator と claude-swift-skills があります。3 project は position がかなり違い、向いている scenario も変わります。

positioning の違い

project	position	module 数	特徴
macos-app-skills	機能 module 型、macOS 固有 scenario に集中	7 modules	build、macos-patterns、settings-ui、auto-update、notch-ui、release、install integration
fireworks-macapp-creator	architecture + style system + scaffold tool	8 styles	Python scaffold tool、SwiftUI-first + AppKit interop、style-driven UI
claude-swift-skills	Swift full-stack + iOS/macOS + WWDC 2025	22 skills	Swift 6.2、SwiftUI、SwiftData、Liquid Glass、Foundation Models、iOS/macOS cross-platform

use case comparison

scenario	macos-app-skills	fireworks-macapp-creator	claude-swift-skills
macOS-only app	推奨	使える	重い。iOS も含む
macOS + iOS cross-platform	iOS は support しない	iOS は support しない	推奨
release pipeline が必要	release module あり	あるが macos-app-skills ほど詳しくない	macos-distribution あり
style system が必要	style system なし	8 preset styles	style system なし
WWDC 2025 feature が必要	一部あり（Liquid Glass など）	一部あり	WWDC 2025 を広く cover
scaffold tool が必要	scaffold なし	Python tool で SwiftPM project を生成	scaffold なし

recommendation

選び方は主に 3 つです。platform scope、feature needs、WWDC feature coverage。

macOS-only app：macos-app-skills または fireworks-macapp-creator。release pipeline と notch UI が必要なら macos-app-skills。complete scaffold と style system が必要なら fireworks です。

macOS + iOS cross-platform：claude-swift-skills。ここで唯一 iOS を cover し、Foundation Models（local LLM）、tech-stack validator、PRD architecture tool など 22 skills を含みます。

WWDC 2025 feature が必要：claude-swift-skills。Liquid Glass、Swift 6.2、SwiftData new features などを広く cover しています。

この 3 package は以前試したことがありますが、長所と短所ははっきりしています。macos-app-skills は最も軽く、すぐ始めやすい。fireworks-macapp-creator は新規 project に向けて最も complete。claude-swift-skills は cross-platform と WWDC feature まで含む最も広い選択肢です。最終判断は、やはり project の要件次第です。

まとめ

macos-app-skills は、AI Agent でネイティブ macOS app を作るときの実用的な toolkit です。build、macos-patterns、settings-ui、auto-update、notch-ui、release、install integration という 7 module を細かな contract table に落とし、Agent が最初からつまずく可能性を下げます。実際に導入するなら、ローカルの Xcode、Swift、signing、公証、Sparkle key、Agent model 自体を確認する必要があります。skills を automatic release guarantee として扱ってはいけません。

選択の目安：macOS-only app なら macos-app-skills または fireworks。macOS + iOS cross-platform なら claude-swift-skills。release pipeline が必要なら macos-app-skills。style system が必要なら fireworks。WWDC 2025 feature が必要なら claude-swift-skills です。

次の action：npx skills add fayazara/macos-app-skills -g -y で macos-app-skills を install し、project の要件に合わせて類似 package を選びます。AGENTS.md の best practice も確認してください。問題が出たら、skill 内の FAQ と troubleshooting checklist から見ていくのが早いです。