Usar macos-app-skills para criar apps Mac nativos com agentes de IA

Como o Claude Code produziu um app macOS com mais de 20 mil linhas quando menos de mil foram escritas à mão? Em um relato prático de 2025, Indragie lista cinco armadilhas: confusão com Swift Concurrency, mistura de frameworks antigos e novos, APIs obsoletas, gerenciamento incorreto de janelas e etapas de release omitidas. Em resumo, o agente não conhece os padrões nativos do macOS e trata o Mac como uma página Web.

macos-app-skills enfrenta esse problema. O pacote transforma conhecimento disperso da WWDC, documentação incompleta e padrões macOS fáceis de aplicar incorretamente em 7 módulos: build, padrões nativos, ajustes, atualização, interface do notch, release e instalação. Cada módulo explica definição, problema, uso típico, comandos, fluxo, limites e FAQ. Assim, o agente começa com uma referência mais confiável. A seguir, os módulos são detalhados e comparados com fireworks-macapp-creator e claude-swift-skills.

Instalação: carregar o pacote no agente

O comando é curto:

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

-g instala globalmente e -y ignora a confirmação interativa. Reinicie o agente para carregar o conteúdo. Em um teste com OpenCode, build, macos-patterns, settings-ui, auto-update, notch-ui e release apareceram depois da reinicialização.

Prepare macOS 14+, Xcode 15+ e Swift 5.9+. Recursos do macOS 26, como Liquid Glass, exigem Xcode 26 beta. Versões anteriores recorrem a alternativas sem bloquear o fluxo básico.

O carregamento varia entre agentes. Claude Code pode exigir um caminho configurado manualmente. OpenCode reconhece ~/.config/opencode/skills/, enquanto Cursor espera .agents/skills/ na raiz. Peça a lista de skills ou pergunte pelo módulo build.

Os problemas comuns envolvem rede, permissões e versões. Se os assets do GitHub estiverem lentos, use proxy ou tente novamente. Se o cache do npx não permitir gravação, é mais seguro copiar o diretório do que usar sudo npx. O projeto foi criado em maio de 2026, então nomes e quantidade de skills podem mudar; confira o README atual.

Detalhamento dos submódulos

Submódulo	O que é	O que resolve	Uso típico	Comando	Fluxo	Limite	FAQ
Instalação	Instalação global via npx	Disponibiliza skills macOS	Instalar com um comando	npx skills add fayazara/macos-app-skills -g -y	Executar → reiniciar → verificar	Depende de npx e rede	Rede lenta? Proxy ou nova tentativa
Pré-requisitos	Versões de macOS/Xcode/Swift	Confirma o ambiente	Verificar as três versões	sw_vers, xcodebuild -version, swift --version	Verificar → comparar com README → atualizar	macOS 14+, Xcode 15+, Swift 5.9+	Versões antigas? Alternativas parciais
Verificação de carga	Confirma que o agente carregou os skills	Valida a instalação	Listar skills ou testar referência	Sem comando padrão	Reiniciar → perguntar → testar	Caminho varia por agente	Não carregou? Verificar caminho
Falhas comuns	Rede, permissões e versão	Acelera o diagnóstico	Proxy, permissões, versões	Sem comando fixo	Rede → permissões → versão	GitHub pode ser lento	sudo? Prefira cópia manual

Módulo build: compilar um projeto macOS no terminal

build usa xcodebuild para compilar qualquer projeto Xcode macOS sem operar a interface gráfica.

Ele cobre descoberta de .xcodeproj ou .xcworkspace, schemes, caminhos de toolchains beta e falhas como scheme ausente ou assinatura. Agentes frequentemente adivinham parâmetros ou tratam um scheme iOS como macOS.

Carregue o skill antes do build. Ele explica como encontrar projeto e scheme e lidar com erros. Exemplo:

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

Com workspace:

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

O fluxo é projeto → scheme → build → inspeção → correção. O agente encontra o arquivo, lista schemes, escolhe um e segue a checklist de solução.

O módulo atende projetos Xcode, não projetos somente SwiftPM. Nesse caso, abra como projeto Xcode ou use outro skill. Toolchains beta também precisam de tratamento especial porque caminhos e versões não são uniformes.

Um scheme ausente pode não estar compartilhado ou ter outro nome. Execute xcodebuild -list antes de adivinhar. Para beta, normalmente se usa /Applications/Xcode-beta.app com -destination.

Detalhamento dos submódulos

Submódulo	O que é	O que resolve	Uso típico	Comando	Fluxo	Limite	FAQ
Definição	Build macOS com xcodebuild	Compila sem GUI	Carregar antes do build	Ver blocos de código	Detectar projeto → scheme → compilar → corrigir	Somente Xcode	SwiftPM? Converter em projeto Xcode
Problemas	Projeto, scheme, toolchain e erros	Agente desconhece parâmetros	Primeiro projeto, depois scheme	xcodebuild -list antes	Executar → inspecionar → corrigir	Caminhos beta não padronizados	Beta? Informar caminho e destination
Uso típico	Skill antes do build	Evita parâmetros adivinhados	Carregar build antes de compilar	Sem comando fixo	Carregar → build → corrigir	Skill é conhecimento	Não carregou? Verificar configuração
Comando	Comandos xcodebuild padrão	Fornece exemplos executáveis	Passar ao xcodebuild	xcodebuild -project MyApp.xcodeproj -scheme MyApp	Executar → esperar → analisar	Parâmetros corretos	Scheme? Usar -list
Fluxo	Build → revisar → corrigir	Ciclo padrão	Seguir etapas	Sem comando fixo	Detectar → build → inspecionar → corrigir	Não pular etapas	Falhou? Usar checklist
Limite	Escopo Xcode	Define o uso	Só projetos Xcode	Nenhum	Nenhum	Sem SwiftPM direto	Por quê? Baseado em xcodebuild
FAQ	Scheme ausente e beta	Dúvidas recorrentes	Listar schemes e caminho beta	xcodebuild -list	Verificar → consultar → definir	Configuração extra	É beta? Ver versão e caminho

Módulo macos-patterns: não tratar o Mac como Web

macos-patterns é o núcleo. Ele torna padrões nativos consultáveis e evita que o agente transfira uma interface Web para o Mac. Barra de menus, hierarquia de janelas e geometria são específicas do macOS.

Os problemas incluem:

1. Três abordagens de barra de menus: MenuBarExtra em SwiftUI, NSStatusItem em AppKit e NSPopover para janelas pop-up.
2. Política de ativação: ícone do Dock, LSUIElement e NSApplication.setActivationPolicy() para apps em segundo plano.
3. NSPanel ou NSWindow: painéis flutuantes e janelas normais têm comportamentos diferentes.
4. Níveis e collection behaviors: CGShieldingWindowLevel, NSWindow.Level e collectionBehavior controlam camadas, tela cheia e vários monitores.
5. Geometria: frame ou visibleFrame, eixo Y invertido e múltiplas telas; macOS começa no canto inferior esquerdo.
6. Três níveis de atalhos: SwiftUI .keyboardShortcut(), monitor NSEvent e hotkey Carbon no sistema.
7. Outros padrões: NSOpenPanel, NSPasteboard, NSDragging, NavigationSplitView + inspector, LaunchAgent, QLPreviewPanel, NSWorkspace, ScreenCaptureKit e UserDefaults/@AppStorage.

Carregue o skill antes de pedir uma UI macOS. Para barra de menus, o agente pode recomendar MenuBarExtra em casos SwiftUI simples e manter NSStatusItem como alternativa AppKit.

A lista é organizada por recomendação, alternativa, cenário, código e limite. Estes são três exemplos frequentes.

Comparação de apps de barra de menus

Abordagem	Recomendação ou alternativa	Cenário	Exemplo de código	Limite
MenuBarExtra	Recomendado	SwiftUI nativo, casos simples	MenuBarExtra("App", systemImage: "app") { ContentView() }	macOS 13+
NSStatusItem	Alternativa	Personalização complexa ou AppKit	NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)	Ciclo de vida manual
NSPopover	Complemento	Janela pop-up ao clicar	NSPopover() + NSStatusItem	Combinar com NSStatusItem

Comparação de políticas de ativação

Política	Cenário recomendado	Configuração	Código	Limite
NSApplication.ActivationPolicy.regular	App principal com ícone no Dock	Não definir LSUIElement	Padrão	Mais comum
NSApplication.ActivationPolicy.accessory	App de fundo sem Dock, com barra	LSUIElement=true no Info.plist	NSApplication.shared.setActivationPolicy(.accessory)	Barra visível
NSApplication.ActivationPolicy.prohibited	Processo sem UI	Configuração LaunchAgent	NSApplication.shared.setActivationPolicy(.prohibited)	Sem Dock nem barra

Comparação de níveis de janela

Tipo	Valor	Cenário	Código	Limite
NSWindow.Level.normal	0	Janela normal	Padrão	Mais comum
NSWindow.Level.floating	3	Janela flutuante, como Inspector	window.level = .floating	Não cobre agressivamente outros apps
CGShieldingWindowLevel	Máximo	Camada de proteção, como notch-ui	window.level = CGShieldingWindowLevel()	Cobre tudo; usar com cuidado

O módulo cobre apenas macOS. Para padrões multiplataforma, use por exemplo o módulo correspondente do claude-swift-skills.

NSApplication.setActivationPolicy() muda o ícone do Dock. NSScreen.screens lista telas e visibleFrame exclui Dock e barra. O eixo Y deve ser convertido entre a origem inferior do macOS e a superior da Web.

Módulo settings-ui: ajustes e Liquid Glass

settings-ui cobre uma janela de ajustes macOS correta e Liquid Glass no macOS 26. Evita que o agente use uma cena SwiftUI Window fora das convenções.

Window não suporta fullSizeContentView, então o fundo transparente não se estende. Liquid Glass incorreto também não se parece com Ajustes do Sistema.

A combinação é NSWindowController + .fullSizeContentView + NavigationSplitView. O skill inclui um arquivo Swift. Fluxo:

1. Criar NSWindowController
2. Configurar fullSizeContentView
3. Adicionar NavigationSplitView com sidebar e detalhe
4. Definir fundo transparente
5. Integrar Liquid Glass no macOS 26+

Exemplo:

// 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 // Ajuste principal
        self.init(window: window)
    }
}

Liquid Glass exige macOS 26+. Sistemas anteriores usam materiais comuns. Sem essa necessidade, um WindowGroup padrão basta.

O skill fornece a verificação de versão para escolher material e um exemplo de sidebar com NavigationSplitView.

Módulo auto-update: integrar Sparkle

auto-update corrige uma armadilha de tempo. SPUStandardUpdaterController deve ser criado antes de applicationDidFinishLaunching terminar; caso contrário, a verificação pode falhar.

O uso típico combina singleton UpdaterManager, Info.plist e chave EdDSA. O UpdaterManager.swift está incluído.

Fluxo:

1. Adicionar Sparkle como dependência SPM
2. Criar o singleton UpdaterManager
3. Configurar SUFeedURL e SUPublicEDKey no Info.plist
4. Gerar a chave EdDSA com sign_update
5. Adicionar controles em ajustes e barra de menus

Exemplo:

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

    init() {
        // Criar antes de applicationDidFinishLaunching terminar
        updaterController = SPUStandardUpdaterController(
            startingUpdater: true,
            updaterDelegate: nil,
            userDriverDelegate: nil
        )
    }
}

Serve para distribuição fora da Mac App Store. Na loja, Sparkle não é usado; a App Store gerencia atualizações.

A chave é criada com sign_update. Para testar, inicie um servidor de feed local ou execute uma verificação após a release.

Módulo notch-ui: interface Dynamic Island no notch

notch-ui cria uma interface flutuante semelhante à Dynamic Island na área do notch do MacBook, não uma janela comum no topo.

Os pontos difíceis são NSPanel borderless com CGShieldingWindowLevel, cálculo de posição e curvas Bézier côncavas. Sem isso, posição e forma não correspondem.

O padrão é borderless NSPanel + CGShieldingWindowLevel + NotchShape. NotchWindow.swift e NotchShape.swift estão incluídos.

Fluxo:

1. Criar um NSPanel borderless
2. Definir CGShieldingWindowLevel
3. Implementar NotchShape com curvas côncavas
4. Adicionar animação de mola
5. Oferecer modo pill para Macs sem notch

Exemplo:

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

A solução é para MacBook com notch. iMac e Mac mini usam o modo pill; se não for necessário, ignore o módulo.

Em Macs sem notch, a pill fica centralizada no topo. A posição é calculada pela tela e pelo local do notch.

Módulo release: pipeline completo de publicação

release organiza a distribuição macOS. É fácil omitir mais de 8 etapas: versão, Archive, Notarize, Export, DMG, assinatura EdDSA, appcast.xml e GitHub release.

O uso típico adiciona release.json e executa a CLI em Go incluída.

Fluxo em 8 etapas:

1. Versão: atualizar Info.plist e arquivos do projeto
2. Archive: empacotar com xcodebuild archive
3. Notarize: enviar com notarytool
4. Export: exportar .app com xcodebuild -exportArchive
5. DMG: criar o instalador com create-dmg
6. Assinatura EdDSA: assinar com Sparkle sign_update
7. appcast.xml: atualizar o feed com generate_appcast
8. GitHub release: publicar com gh release create

Exemplo:

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

Ou execute cada etapa:

# 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"

São necessários GitHub CLI e uma chave EdDSA do Sparkle. Sem gh, a última etapa para; sem chave, a assinatura para.

O modelo de release.json inclui versão, credenciais de notarização e configuração do DMG. Em caso de falha, leia o log do notarytool.

Detalhamento dos submódulos

Submódulo	O que é	O que resolve	Uso típico	Comando	Fluxo	Limite	FAQ
Definição	Pipeline completo + CLI Go	Automatiza 8 etapas de release	release.json + CLI	go run github.com/fayazara/macos-app-skills/release/cli@latest	Versão → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	GitHub CLI + chave Sparkle	Sem CLI? Publicar manualmente
Problemas	Mais de 8 etapas frágeis	Omissão quebra a release	Carregar skill e seguir fluxo	Sem comando único	Executar → revisar → corrigir	Não pular etapas	Falhou? Usar checklist
Uso típico	release.json + CLI	Implementação padrão	Adicionar release.json e executar	Ver bloco	Configurar → executar → revisar	Configuração manual	release.json? Usar modelo
CLI	Ferramenta Go	Automatiza publicação	Um comando	go run github.com/.../cli@latest	Executar → esperar → revisar	Ambiente Go	Sem Go? Etapas manuais
Fluxo	8 etapas	Checklist clara	Manual ou CLI	Sem comando fixo	bump → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	Manter ordem	Mudar ordem? Não recomendado
Limite	GitHub CLI + chave Sparkle	Requisitos	Verificar gh e chave	gh --version, sign_update --help	Verificar → configurar → executar	Ferramenta ausente bloqueia	Chave? Usar sign_update
FAQ	release.json e notarização	Respostas comuns	Modelo e solução de erros	Sem comando fixo	Ler → configurar → corrigir	Pode falhar várias vezes	Falhou? Ler log do notarytool

Três projetos comparáveis: qual escolher?

Além de macos-app-skills, vale comparar fireworks-macapp-creator e claude-swift-skills. Eles têm objetivos diferentes.

Diferenças de posicionamento

Projeto	Posicionamento	Módulos	Características
macos-app-skills	Módulos funcionais focados em macOS	7 módulos	build, macos-patterns, settings-ui, auto-update, notch-ui, release, instalação
fireworks-macapp-creator	Arquitetura + estilos + scaffold	8 estilos	Scaffold Python, SwiftUI-first + AppKit, UI por estilos
claude-swift-skills	Swift completo + iOS/macOS + WWDC 2025	22 skills	Swift 6.2, SwiftUI, SwiftData, Liquid Glass, Foundation Models, multiplataforma

Comparação de casos de uso

Cenário	macos-app-skills	fireworks-macapp-creator	claude-swift-skills
Apenas macOS	Recomendado	Adequado	Amplo demais; inclui iOS
macOS + iOS	Sem iOS	Sem iOS	Recomendado
Pipeline de release	Módulo release	Existe, menos detalhado	macos-distribution
Sistema de estilos	Nenhum	8 estilos	Nenhum
Recursos WWDC 2025	Parcial, como Liquid Glass	Parcial	Cobertura ampla
Ferramenta scaffold	Nenhuma	Python gera projetos SwiftPM	Nenhuma

Recomendação

A decisão depende do alcance de plataformas, dos recursos e da cobertura WWDC.

Apenas macOS: escolha macos-app-skills ou fireworks-macapp-creator. O primeiro para release e notch; o segundo para scaffold e estilos.

macOS + iOS: escolha claude-swift-skills. É o único com iOS, Foundation Models, validação de stack, ferramentas PRD e 22 skills.

Recursos WWDC 2025: escolha claude-swift-skills por cobrir Liquid Glass, Swift 6.2 e recursos recentes do SwiftData.

Na prática, macos-app-skills é o mais leve e rápido. fireworks-macapp-creator oferece o scaffold mais completo para novos projetos. claude-swift-skills é o mais amplo para multiplataforma e WWDC. Os requisitos do projeto definem a escolha.

Conclusão

macos-app-skills é uma caixa de ferramentas prática para agentes que criam apps macOS nativos. Seus 7 módulos — build, macos-patterns, settings-ui, auto-update, notch-ui, release e instalação — reduzem erros na primeira tentativa. Ainda é preciso revisar Xcode, Swift, assinatura, notarização, chaves Sparkle e modelo. Um skill não garante release automática.

Regra rápida: macos-app-skills ou fireworks para apenas macOS; claude-swift-skills para macOS + iOS; macos-app-skills para release; fireworks para estilos; claude-swift-skills para WWDC 2025.

O próximo passo é executar npx skills add fayazara/macos-app-skills -g -y, comparar alternativas com as necessidades do projeto e revisar as práticas do AGENTS.md. Se houver problema, comece pela FAQ e checklist do skill.