macos-app-skills로 AI 에이전트가 네이티브 Mac 앱을 만드는 방법

Claude Code로 2만 줄이 넘는 macOS 앱을 만들면서 손으로 작성한 코드는 1천 줄도 안 될 수 있었던 이유는 무엇일까요? Indragie는 2025년 실전 글에서 Swift Concurrency 혼란, 신구 프레임워크 혼용, 폐기된 API 호출, 잘못된 창 관리, release 단계 누락이라는 다섯 가지 함정을 꼽았습니다. 에이전트가 네이티브 macOS 패턴을 모르고 Mac을 웹 페이지처럼 다루기 때문입니다.

macos-app-skills는 이 문제를 해결합니다. 흩어진 WWDC 지식, 불완전한 문서, 실수하기 쉬운 macOS 패턴을 build, 네이티브 패턴, 설정 창, 자동 업데이트, notch UI, release, 설치의 7개 모듈로 묶습니다. 각 모듈에는 정의, 해결 문제, 사용 예, 명령, 흐름, 제한, FAQ가 있습니다. 에이전트가 시행착오 대신 더 나은 기준에서 시작할 수 있습니다. 아래에서 각 모듈을 살펴보고 fireworks-macapp-creator, claude-swift-skills와 비교합니다.

설치: 에이전트에 skill 패키지 로드하기

설치 명령은 짧습니다.

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

-g는 전역 설치, -y는 대화형 확인 생략입니다. 설치 후 에이전트를 재시작해 skills 디렉터리를 로드합니다. OpenCode에서 시험했을 때 재시작 뒤 build, macos-patterns, settings-ui, auto-update, notch-ui, release가 목록에 나타났습니다.

먼저 macOS 14+, Xcode 15+, Swift 5.9+를 준비합니다. Liquid Glass 같은 macOS 26 기능에는 Xcode 26 beta가 필요합니다. 이전 버전은 기본 흐름을 유지하면서 대체 동작을 사용합니다.

로딩 방식은 에이전트마다 다릅니다. Claude Code는 skills 경로를 수동으로 설정해야 할 수 있습니다. OpenCode는 ~/.config/opencode/skills/를 인식하고 Cursor는 프로젝트 루트의 .agents/skills/를 사용합니다. skills 목록을 요청하거나 build 모듈을 아는지 질문해 확인합니다.

일반적인 문제는 네트워크, 권한, 버전입니다. GitHub assets가 느리면 프록시나 재시도를 사용합니다. npx 캐시에 쓸 수 없다면 sudo npx보다 디렉터리를 직접 복사하는 편이 안전합니다. 프로젝트는 2026년 5월에 만들어졌으므로 skill 이름과 수가 바뀔 수 있습니다. 설치 전에 최신 README를 확인합니다.

하위 모듈 정리

하위 모듈	정의	해결하는 문제	일반적인 사용	명령	흐름	제한	FAQ
설치	npx 전역 설치	에이전트에서 macOS skill 사용	한 명령으로 설치	npx skills add fayazara/macos-app-skills -g -y	실행 → 재시작 → 확인	npx와 네트워크 필요	느린 네트워크? 프록시 또는 재시도
사전 조건	macOS/Xcode/Swift 버전	실행 환경 확인	세 버전 확인	sw_vers, xcodebuild -version, swift --version	확인 → README 비교 → 업데이트	macOS 14+, Xcode 15+, Swift 5.9+	이전 버전? 일부 대체 동작
로딩 확인	에이전트가 skills를 로드했는지 확인	설치 검증	목록 또는 모듈 참조 테스트	표준 명령 없음	재시작 → 질문 → 테스트	에이전트마다 경로 다름	로드 실패? 경로 확인
일반적인 실패	네트워크, 권한, 버전	빠른 진단	프록시, 권한, 버전 확인	고정 명령 없음	네트워크 → 권한 → 버전	GitHub가 느릴 수 있음	sudo? 직접 복사 권장

build 모듈: 터미널에서 macOS 프로젝트 빌드하기

build는 xcodebuild로 macOS Xcode 프로젝트를 컴파일하며 Xcode GUI 조작을 줄입니다.

.xcodeproj와 .xcworkspace 탐색, scheme 확인, beta toolchain 경로, scheme 누락이나 서명 오류를 다룹니다. 에이전트는 매개변수를 추측하거나 iOS scheme을 macOS용으로 잘못 사용할 수 있습니다.

build 전에 skill을 로드합니다. 프로젝트와 scheme을 찾고 오류를 처리하는 방법을 제공합니다. 예:

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

workspace의 경우:

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

흐름은 프로젝트 탐색 → scheme 확인 → build → 오류 검사 → 수정입니다. 프로젝트를 찾고 scheme 목록을 확인한 뒤 적절한 항목을 선택하고 체크리스트로 오류를 처리합니다.

Xcode 프로젝트만 대상으로 하며 SwiftPM 전용 프로젝트는 직접 지원하지 않습니다. Xcode 프로젝트로 열거나 다른 skill을 사용해야 합니다. beta toolchain도 경로와 버전이 일정하지 않아 별도 처리가 필요합니다.

scheme이 없으면 공유되지 않았거나 target과 이름이 다를 수 있습니다. 추측 전에 xcodebuild -list를 실행합니다. beta는 보통 /Applications/Xcode-beta.app 경로와 -destination을 지정합니다.

하위 모듈 정리

하위 모듈	정의	해결하는 문제	일반적인 사용	명령	흐름	제한	FAQ
정의	xcodebuild로 macOS build	GUI 없이 컴파일	build 전에 로드	코드 블록 참고	프로젝트 → scheme → build → 수정	Xcode만	SwiftPM? Xcode 프로젝트로 전환
해결 범위	프로젝트, scheme, toolchain, 오류	매개변수 추측 방지	프로젝트 후 scheme 선택	먼저 xcodebuild -list	실행 → 검사 → 수정	beta 경로 비표준	beta? 경로와 destination 지정
일반 사용	build 전 skill 로드	무작정 실행 방지	컴파일 전에 build 로드	고정 명령 없음	로드 → build → 오류 처리	skill은 지식	로드 실패? 설정 확인
명령	표준 xcodebuild 명령	실행 예 제공	xcodebuild에 전달	xcodebuild -project MyApp.xcodeproj -scheme MyApp	실행 → 대기 → 오류 분석	정확한 매개변수	scheme? -list 사용
흐름	build → 검사 → 수정	표준 주기	단계 준수	고정 명령 없음	탐색 → build → 검사 → 수정	단계 생략 금지	실패? 체크리스트 사용
제한	Xcode 지원 범위	사용 조건 명확화	Xcode 프로젝트만	없음	없음	SwiftPM 직접 미지원	이유? xcodebuild 기반
FAQ	scheme과 beta	빈번한 질문	scheme 목록과 beta 경로	xcodebuild -list	확인 → 조회 → 지정	추가 설정 필요	beta 확인? 버전과 경로

macos-patterns 모듈: Mac을 웹처럼 만들지 않기

macos-patterns는 핵심 모듈입니다. 네이티브 패턴을 참조 가능하게 만들어 웹 UI 방식을 Mac에 적용하는 실수를 막습니다. 메뉴 막대, 창 계층, 화면 기하가 macOS에 특화되어 있습니다.

주요 문제는 다음과 같습니다.

1. 메뉴 막대 앱 3가지 방식: SwiftUI의 MenuBarExtra, AppKit의 NSStatusItem, 팝업 창용 NSPopover입니다.
2. 활성화 정책: Dock 아이콘, LSUIElement, NSApplication.setActivationPolicy()로 백그라운드 앱의 동작을 제어합니다.
3. NSPanel과 NSWindow: 떠 있는 inspector와 일반 창은 동작이 다릅니다.
4. 창 레벨과 collection behaviors: CGShieldingWindowLevel, NSWindow.Level, collectionBehavior가 레이어, 전체 화면, 여러 화면을 제어합니다.
5. 화면 기하: frame과 visibleFrame, Y축 반전, 다중 화면입니다. macOS 원점은 왼쪽 아래입니다.
6. 단축키 3단계: SwiftUI .keyboardShortcut(), NSEvent monitor, 시스템 수준 Carbon hotkey입니다.
7. 기타 패턴: NSOpenPanel, NSPasteboard, NSDragging, NavigationSplitView + inspector, LaunchAgent, QLPreviewPanel, NSWorkspace, ScreenCaptureKit, UserDefaults/@AppStorage입니다.

macOS UI를 요청하기 전에 skill을 로드합니다. 메뉴 막대 앱이라면 단순 SwiftUI에는 MenuBarExtra, 복잡한 AppKit 연동에는 NSStatusItem을 선택할 수 있습니다.

패턴은 권장, 대안, 사용 사례, 코드, 제한으로 정리되어 있습니다. 자주 쓰는 세 가지 비교입니다.

메뉴 막대 앱 비교

방식	권장 또는 대안	사용 사례	코드 예	제한
MenuBarExtra	권장	네이티브 SwiftUI, 단순한 경우	MenuBarExtra("App", systemImage: "app") { ContentView() }	macOS 13+
NSStatusItem	대안	복잡한 커스터마이징 또는 AppKit	NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)	수동 생명주기 관리
NSPopover	보완	클릭으로 열리는 팝업 창	NSPopover() + NSStatusItem	NSStatusItem과 함께 사용

활성화 정책 비교

정책	권장 시나리오	설정	코드	제한
NSApplication.ActivationPolicy.regular	Dock 아이콘이 있는 전면 앱	LSUIElement를 설정하지 않음	기본 동작	가장 일반적
NSApplication.ActivationPolicy.accessory	Dock 없이 메뉴 막대가 있는 백그라운드 앱	Info.plist에 LSUIElement=true	NSApplication.shared.setActivationPolicy(.accessory)	메뉴 막대 표시
NSApplication.ActivationPolicy.prohibited	UI 없는 백그라운드 프로세스	LaunchAgent 설정	NSApplication.shared.setActivationPolicy(.prohibited)	Dock과 메뉴 막대 없음

창 레벨 비교

유형	값	사용 사례	코드	제한
NSWindow.Level.normal	0	일반 창	기본값	가장 일반적
NSWindow.Level.floating	3	Inspector 같은 떠 있는 창	window.level = .floating	다른 앱을 강하게 덮지 않음
CGShieldingWindowLevel	최고	notch-ui 같은 보호 레이어	window.level = CGShieldingWindowLevel()	모든 것을 덮으므로 주의

이 모듈은 macOS만 다룹니다. 크로스 플랫폼 패턴은 claude-swift-skills의 해당 모듈 등을 사용합니다.

NSApplication.setActivationPolicy()로 Dock 아이콘을 바꿉니다. NSScreen.screens는 화면을 나열하고 visibleFrame은 Dock과 메뉴 막대를 제외합니다. macOS의 아래쪽 원점과 웹의 위쪽 원점 사이에서 Y축을 변환해야 합니다.

settings-ui 모듈: 설정 창과 Liquid Glass

settings-ui는 올바른 macOS 설정 창과 macOS 26의 Liquid Glass를 다룹니다. 에이전트가 관례와 맞지 않는 SwiftUI Window scene을 쓰는 일을 막습니다.

Window scene은 fullSizeContentView를 지원하지 않아 투명 배경이 제대로 확장되지 않습니다. Liquid Glass 설정이 잘못되면 시스템 설정과 다른 모양이 됩니다.

일반적인 조합은 NSWindowController + .fullSizeContentView + NavigationSplitView입니다. skill에 완전한 Swift 파일이 있습니다. 흐름:

1. NSWindowController 생성
2. fullSizeContentView 설정
3. sidebar와 detail이 있는 NavigationSplitView 추가
4. 투명 배경 설정
5. macOS 26+에서 Liquid Glass 통합

예:

// 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+가 필요합니다. 이전 시스템은 일반 재질을 사용합니다. 필요하지 않다면 표준 SwiftUI WindowGroup으로 충분합니다.

skill은 시스템 버전에 따라 재질을 선택하는 fallback과 NavigationSplitView sidebar 예를 제공합니다.

auto-update 모듈: Sparkle 업데이트 통합

auto-update는 timing 함정을 해결합니다. SPUStandardUpdaterController는 applicationDidFinishLaunching이 반환되기 전에 생성해야 하며 그렇지 않으면 업데이트 확인이 실패할 수 있습니다.

일반적인 구성은 UpdaterManager singleton, Info.plist, EdDSA 키입니다. UpdaterManager.swift가 제공됩니다.

흐름:

1. Sparkle SPM 의존성 추가
2. UpdaterManager singleton 생성
3. Info.plist에 SUFeedURL과 SUPublicEDKey 설정
4. sign_update로 EdDSA 키 생성
5. 설정과 메뉴 막대에 UI 컨트롤 추가

예:

// 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 Store에서는 Sparkle을 사용할 수 없으며 스토어 업데이트를 사용합니다.

EdDSA 키는 sign_update로 생성합니다. 로컬 feed 서버를 띄우거나 release 후 수동 확인으로 테스트합니다.

notch-ui 모듈: notch 주변의 Dynamic Island UI

notch-ui는 MacBook notch 주변에 Dynamic Island와 비슷한 플로팅 UI를 만듭니다. 화면 위에 일반 창을 놓는 방식이 아닙니다.

어려운 지점은 CGShieldingWindowLevel을 적용한 borderless NSPanel, 위치 계산, 오목한 Bézier 곡선입니다. 이 요소가 없으면 위치와 모양이 맞지 않습니다.

패턴은 borderless NSPanel + CGShieldingWindowLevel + NotchShape입니다. NotchWindow.swift와 NotchShape.swift가 제공됩니다.

흐름:

1. borderless NSPanel 생성
2. CGShieldingWindowLevel 설정
3. 오목한 곡선으로 NotchShape 구현
4. spring animation 추가
5. notch 없는 Mac용 pill 모드 제공

예:

// 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는 pill 모드를 사용합니다. 필요하지 않다면 이 모듈을 생략합니다.

notch가 없는 Mac에서는 상단 중앙에 pill을 표시합니다. 화면 크기와 notch 위치를 기준으로 계산합니다.

release 모듈: 전체 배포 파이프라인

release는 macOS 배포를 구조화합니다. 버전, Archive, Notarize, Export, DMG, EdDSA 서명, appcast.xml, GitHub release 등 8개 이상의 수동 단계를 놓치기 쉽습니다.

일반적인 사용은 release.json을 추가하고 포함된 Go CLI를 실행하는 것입니다.

8단계 흐름:

1. 버전: Info.plist와 프로젝트 파일 업데이트
2. Archive: xcodebuild archive로 패키징
3. Notarize: notarytool로 공증 제출
4. Export: xcodebuild -exportArchive로 .app 내보내기
5. DMG: create-dmg로 설치 파일 만들기
6. EdDSA 서명: Sparkle sign_update로 서명
7. appcast.xml: generate_appcast로 feed 업데이트
8. GitHub release: gh release create로 게시

예:

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

또는 각 단계를 실행합니다.

# 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 키가 필요합니다. gh가 없으면 마지막 단계가, 키가 없으면 서명이 중단됩니다.

release.json 템플릿은 버전, 공증 자격 증명, DMG 설정을 포함합니다. 실패하면 notarytool 오류 로그를 확인합니다.

하위 모듈 정리

하위 모듈	정의	해결하는 문제	일반적인 사용	명령	흐름	제한	FAQ
정의	전체 release 파이프라인 + Go CLI	8단계 자동화	release.json + CLI	go run github.com/fayazara/macos-app-skills/release/cli@latest	버전 → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	GitHub CLI + Sparkle 키	CLI 없음? 수동 게시
해결 범위	8개 이상의 취약한 단계	누락으로 인한 실패	skill을 로드하고 흐름 준수	단일 명령 없음	실행 → 검사 → 수정	단계 생략 금지	실패? 체크리스트 사용
일반 사용	release.json + CLI	표준 구현	파일 추가 후 실행	코드 블록 참고	설정 → 실행 → 확인	수동 설정 필요	release.json? 템플릿 사용
CLI	Go 도구	배포 자동화	한 명령 실행	go run github.com/.../cli@latest	실행 → 대기 → 확인	Go 환경	Go 없음? 수동 단계
흐름	8단계	명확한 체크리스트	수동 또는 CLI	고정 명령 없음	bump → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	순서 유지	순서 변경? 비권장
제한	GitHub CLI + Sparkle 키	필수 조건	gh와 키 확인	gh --version, sign_update --help	확인 → 설정 → 실행	도구 누락 시 중단	키? sign_update 사용
FAQ	release.json과 공증	일반 질문	템플릿과 문제 해결	고정 명령 없음	읽기 → 설정 → 수정	반복 실패 가능	실패? notarytool 로그

비교할 세 프로젝트: 무엇을 선택할까?

macos-app-skills 외에도 fireworks-macapp-creator와 claude-swift-skills를 비교할 수 있습니다. 세 프로젝트의 목표가 다릅니다.

포지셔닝 차이

프로젝트	포지셔닝	모듈 수	특징
macos-app-skills	macOS에 집중한 기능 모듈	7개	build, macos-patterns, settings-ui, auto-update, notch-ui, release, 설치
fireworks-macapp-creator	아키텍처 + 스타일 + scaffold	8개 스타일	Python scaffold, SwiftUI-first + AppKit, 스타일 기반 UI
claude-swift-skills	Swift 전체 + iOS/macOS + WWDC 2025	22개 skills	Swift 6.2, SwiftUI, SwiftData, Liquid Glass, Foundation Models, 크로스 플랫폼

사용 사례 비교

시나리오	macos-app-skills	fireworks-macapp-creator	claude-swift-skills
macOS 전용	권장	사용 가능	iOS까지 포함해 무거움
macOS + iOS	iOS 미지원	iOS 미지원	권장
release 파이프라인	release 모듈 있음	있지만 덜 상세함	macos-distribution 있음
스타일 시스템	없음	8개 스타일	없음
WWDC 2025 기능	Liquid Glass 등 일부	일부	폭넓게 지원
scaffold 도구	없음	Python으로 SwiftPM 생성	없음

추천

플랫폼 범위, 필요한 기능, WWDC 지원 범위가 선택을 결정합니다.

macOS 전용: macos-app-skills 또는 fireworks-macapp-creator를 선택합니다. release와 notch는 전자, scaffold와 스타일은 후자가 맞습니다.

macOS + iOS: claude-swift-skills를 선택합니다. iOS, Foundation Models, 기술 스택 검증, PRD 아키텍처 도구와 22개 skills를 제공합니다.

WWDC 2025 기능: Liquid Glass, Swift 6.2, 최신 SwiftData를 넓게 다루는 claude-swift-skills가 맞습니다.

실제로 macos-app-skills는 가장 가볍고 빠르게 시작할 수 있습니다. fireworks-macapp-creator는 새 프로젝트에 가장 완전한 scaffold를 제공합니다. claude-swift-skills는 크로스 플랫폼과 WWDC 범위가 가장 넓습니다. 최종 선택은 프로젝트 요구 사항에 달려 있습니다.

결론

macos-app-skills는 AI 에이전트가 네이티브 macOS 앱을 만들 때 쓰는 실용적인 도구 모음입니다. build, macos-patterns, settings-ui, auto-update, notch-ui, release, 설치의 7개 모듈이 첫 시도의 실수를 줄입니다. 그래도 Xcode, Swift, 서명, 공증, Sparkle 키와 에이전트 모델을 검토해야 합니다. skill이 자동 release를 보장하지는 않습니다.

간단한 기준은 macOS 전용이면 macos-app-skills 또는 fireworks, macOS + iOS면 claude-swift-skills, release면 macos-app-skills, 스타일이면 fireworks, WWDC 2025면 claude-swift-skills입니다.

다음 단계로 npx skills add fayazara/macos-app-skills -g -y를 실행하고 프로젝트 요구 사항에 맞춰 대안을 비교하며 AGENTS.md 모범 사례를 확인합니다. 문제가 생기면 skill의 FAQ와 문제 해결 체크리스트부터 봅니다.