Usar macos-app-skills para crear apps Mac nativas con agentes de IA

¿Cómo pudo Claude Code producir una app macOS de más de 20 000 líneas cuando menos de 1 000 se escribieron a mano? En un informe práctico de 2025, Indragie enumera cinco trampas: confusión con Swift Concurrency, mezcla de frameworks antiguos y nuevos, API obsoletas, mala gestión de ventanas y pasos de release omitidos. En resumen, el agente desconoce los patrones nativos de macOS y trata el Mac como una página web.

macos-app-skills aborda ese problema. Convierte conocimiento disperso de WWDC, documentación incompleta y patrones macOS fáciles de aplicar mal en 7 módulos: build, patrones nativos, ajustes, actualización, interfaz del notch, release e instalación. Cada módulo explica qué es, qué resuelve, uso típico, comandos, flujo, límites y FAQ. Así el agente parte de una base más fiable. A continuación se detallan los módulos y se comparan con fireworks-macapp-creator y claude-swift-skills.

Instalación: cargar el paquete en el agente

El comando es breve:

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

-g instala globalmente y -y omite la confirmación interactiva. Reinicia el agente para que cargue el contenido. En una prueba con OpenCode, después del reinicio aparecieron build, macos-patterns, settings-ui, auto-update, notch-ui y release.

Prepara macOS 14+, Xcode 15+ y Swift 5.9+. Las funciones de macOS 26 como Liquid Glass requieren Xcode 26 beta. Las versiones anteriores recurren a alternativas sin bloquear el flujo básico.

La carga cambia entre agentes. Claude Code puede exigir una ruta configurada manualmente. OpenCode reconoce ~/.config/opencode/skills/ y Cursor espera .agents/skills/ en la raíz. Pide la lista de skills o pregunta por el módulo build para verificarlo.

Los fallos frecuentes son red, permisos y versiones. Si los assets de GitHub cargan despacio, usa un proxy o reintenta. Si el caché de npx no permite escritura, es más seguro copiar el directorio que usar sudo npx. El proyecto se creó en mayo de 2026, así que nombres y cantidad de skills pueden cambiar: revisa la README actual.

Desglose de submódulos

Submódulo	Qué es	Qué resuelve	Uso típico	Comando	Flujo	Límite	FAQ
Instalación	Instalación global mediante npx	Hace disponibles los skills macOS	Instalar con un comando	npx skills add fayazara/macos-app-skills -g -y	Ejecutar → reiniciar → verificar	Depende de npx y red	¿Red lenta? Proxy o reintento
Requisitos	Versiones de macOS/Xcode/Swift	Verifica el entorno	Comprobar las tres versiones	sw_vers, xcodebuild -version, swift --version	Verificar → comparar con README → actualizar	macOS 14+, Xcode 15+, Swift 5.9+	¿Versiones anteriores? Degradación parcial
Verificación de carga	Confirma que el agente cargó los skills	Valida la instalación	Listar skills o probar una referencia	Sin comando estándar	Reiniciar → consultar → probar	Ruta distinta por agente	¿No carga? Revisar la ruta
Fallos comunes	Red, permisos y versión	Acelera el diagnóstico	Proxy, permisos, versiones	Sin comando fijo	Red → permisos → versión	GitHub puede ser lento	¿sudo? Mejor copia manual

Módulo build: compilar un proyecto macOS desde la terminal

build usa xcodebuild para compilar cualquier proyecto Xcode de macOS sin operar la interfaz gráfica.

Cubre detección de .xcodeproj o .xcworkspace, schemes, rutas de toolchains beta y errores como schemes ausentes o firmas. Los agentes suelen adivinar parámetros o usar un scheme iOS como si fuera macOS.

Carga el skill antes del build. Explica cómo encontrar proyecto y scheme y cómo tratar los errores. Ejemplo:

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

Con workspace:

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

El flujo es proyecto → scheme → build → inspección → corrección. El agente encuentra el archivo, enumera schemes, elige uno y sigue la lista de solución de problemas.

Solo cubre proyectos Xcode, no proyectos SwiftPM puros. En ese caso hay que abrirlos como proyecto Xcode o usar otro skill. Las toolchains beta también requieren manejo especial porque sus rutas y versiones no son uniformes.

Un scheme ausente puede no estar compartido o tener otro nombre. Ejecuta xcodebuild -list antes de adivinar. Para una beta, suele usarse /Applications/Xcode-beta.app y un parámetro -destination.

Desglose de submódulos

Submódulo	Qué es	Qué resuelve	Uso típico	Comando	Flujo	Límite	FAQ
Definición	Build macOS con xcodebuild	Compila sin GUI	Cargar antes del build	Ver bloques de código	Detectar proyecto → scheme → compilar → corregir	Solo Xcode	¿SwiftPM? Convertir a proyecto Xcode
Problemas cubiertos	Proyecto, scheme, toolchain y errores	El agente desconoce parámetros	Primero proyecto, luego scheme	Antes xcodebuild -list	Ejecutar → inspeccionar → corregir	Rutas beta no estándar	¿Beta? Indicar ruta y destination
Uso típico	Skill antes del build	Evita parámetros adivinados	Cargar build antes de compilar	Sin comando fijo	Cargar → build → corregir	El skill es conocimiento	¿No carga? Revisar configuración
Comando	Comandos xcodebuild estándar	Da ejemplos ejecutables	Pasar a xcodebuild	xcodebuild -project MyApp.xcodeproj -scheme MyApp	Ejecutar → esperar → analizar	Parámetros correctos	¿Scheme? Usar -list
Flujo	Build → revisar → corregir	Ciclo estándar	Seguir los pasos	Sin comando fijo	Detectar → build → inspeccionar → corregir	No omitir pasos	¿Falló? Usar la checklist
Límite	Alcance Xcode	Define el uso	Solo proyectos Xcode	Ninguno	Ninguno	Sin SwiftPM directo	¿Por qué? Basado en xcodebuild
FAQ	Scheme ausente y beta	Responde dudas habituales	Listar schemes y ruta beta	xcodebuild -list	Revisar → consultar → especificar	Configuración adicional	¿Es beta? Ver versión y ruta

Módulo macos-patterns: no tratar el Mac como la web

macos-patterns es el núcleo. Expone patrones nativos para evitar que el agente traslade interfaces web al Mac. Barra de menús, jerarquía de ventanas y geometría son específicas de macOS.

Los problemas concretos incluyen:

1. Tres enfoques de barra de menús: MenuBarExtra en SwiftUI, NSStatusItem en AppKit y NSPopover para ventanas emergentes.
2. Política de activación: icono del Dock, LSUIElement y NSApplication.setActivationPolicy() para que una app de fondo no se comporte como una app principal.
3. NSPanel frente a NSWindow: los paneles flotantes y las ventanas normales tienen comportamientos distintos.
4. Niveles y collection behaviors: CGShieldingWindowLevel, NSWindow.Level y collectionBehavior controlan capas, pantalla completa y varias pantallas.
5. Geometría: frame frente a visibleFrame, eje Y invertido y pantallas múltiples; macOS parte de la esquina inferior izquierda.
6. Tres niveles de atajos: SwiftUI .keyboardShortcut(), monitor NSEvent y hotkey Carbon del sistema.
7. Otros patrones: NSOpenPanel, NSPasteboard, NSDragging, NavigationSplitView + inspector, LaunchAgent, QLPreviewPanel, NSWorkspace, ScreenCaptureKit y UserDefaults/@AppStorage.

Carga el skill antes de pedir UI macOS. Para una app de barra de menús, el agente podrá recomendar MenuBarExtra en casos SwiftUI simples y reservar NSStatusItem para AppKit.

La lista se organiza por recomendación, alternativa, caso, código y límite. Estos son tres ejemplos comunes.

Comparación de apps de barra de menús

Enfoque	Recomendación o alternativa	Caso	Ejemplo de código	Límite
MenuBarExtra	Recomendado	SwiftUI nativo, casos simples	MenuBarExtra("App", systemImage: "app") { ContentView() }	macOS 13+
NSStatusItem	Alternativa	Personalización compleja o AppKit	NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)	Ciclo de vida manual
NSPopover	Complemento	Ventana emergente al hacer clic	NSPopover() + NSStatusItem	Debe combinarse con NSStatusItem

Comparación de políticas de activación

Política	Escenario recomendado	Configuración	Código	Límite
NSApplication.ActivationPolicy.regular	App principal con icono en Dock	No definir LSUIElement	Predeterminado	Caso habitual
NSApplication.ActivationPolicy.accessory	App de fondo sin Dock, con barra de menús	LSUIElement=true en Info.plist	NSApplication.shared.setActivationPolicy(.accessory)	Barra visible
NSApplication.ActivationPolicy.prohibited	Proceso de fondo sin UI	Configuración LaunchAgent	NSApplication.shared.setActivationPolicy(.prohibited)	Sin Dock ni barra

Comparación de niveles de ventana

Tipo	Valor	Caso	Código	Límite
NSWindow.Level.normal	0	Ventana normal	Predeterminado	Más común
NSWindow.Level.floating	3	Ventana flotante, como Inspector	window.level = .floating	No cubre agresivamente otras apps
CGShieldingWindowLevel	Máximo	Capa de protección, como notch-ui	window.level = CGShieldingWindowLevel()	Cubre todo; usar con cuidado

El módulo solo cubre macOS. Para patrones multiplataforma, usa por ejemplo el módulo correspondiente de claude-swift-skills.

NSApplication.setActivationPolicy() cambia el icono del Dock. NSScreen.screens enumera pantallas y visibleFrame excluye Dock y barra. El eje Y debe convertirse entre el origen inferior de macOS y el superior de la web.

Módulo settings-ui: ajustes y Liquid Glass

settings-ui cubre una ventana de ajustes macOS correcta y Liquid Glass en macOS 26. Evita que el agente use una escena SwiftUI Window que no sigue las convenciones.

Window no admite fullSizeContentView, por lo que el fondo transparente no se extiende. Una configuración incorrecta de Liquid Glass tampoco se parece a Ajustes del sistema.

La combinación es NSWindowController + .fullSizeContentView + NavigationSplitView. El skill incluye un archivo Swift. Flujo:

1. Crear NSWindowController
2. Configurar fullSizeContentView
3. Añadir NavigationSplitView con sidebar y detalle
4. Establecer fondo transparente
5. Integrar Liquid Glass en macOS 26+

Ejemplo:

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

Liquid Glass requiere macOS 26+. Los sistemas anteriores usan materiales normales. Si no se necesita, basta un WindowGroup estándar.

El skill ofrece la comprobación de versión para elegir material y el ejemplo completo de sidebar con NavigationSplitView.

Módulo auto-update: integrar Sparkle

auto-update corrige una trampa de tiempo. SPUStandardUpdaterController debe crearse antes de que termine applicationDidFinishLaunching; de lo contrario, las comprobaciones pueden fallar.

El uso típico combina singleton UpdaterManager, Info.plist y una clave EdDSA. Se incluye UpdaterManager.swift.

Flujo:

1. Añadir Sparkle como dependencia SPM
2. Crear el singleton UpdaterManager
3. Configurar SUFeedURL y SUPublicEDKey en Info.plist
4. Generar la clave EdDSA con sign_update
5. Añadir controles en ajustes y barra de menús

Ejemplo:

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

    init() {
        // Crear antes de que applicationDidFinishLaunching termine
        updaterController = SPUStandardUpdaterController(
            startingUpdater: true,
            updaterDelegate: nil,
            userDriverDelegate: nil
        )
    }
}

Sirve para distribución fuera de Mac App Store. En la tienda no se usa Sparkle; el Store gestiona las actualizaciones.

La clave se genera con sign_update. Para probar, inicia un servidor de feed local o ejecuta una comprobación tras una release.

Módulo notch-ui: interfaz Dynamic Island alrededor del notch

notch-ui crea una interfaz flotante similar a Dynamic Island en la muesca del MacBook, no una ventana normal colocada arriba.

Los puntos difíciles son un NSPanel borderless con CGShieldingWindowLevel, el cálculo de posición y las curvas Bézier cóncavas. Sin ellos, posición y forma no coinciden.

El patrón es borderless NSPanel + CGShieldingWindowLevel + NotchShape. Se incluyen NotchWindow.swift y NotchShape.swift.

Flujo:

1. Crear un NSPanel borderless
2. Definir CGShieldingWindowLevel
3. Implementar NotchShape con curvas cóncavas
4. Añadir animación de resorte
5. Ofrecer modo pill para Macs sin notch

Ejemplo:

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

La solución es para MacBook con notch. iMac y Mac mini usan el modo pill; si no hace falta, omite el módulo.

En equipos sin notch, la pill aparece centrada arriba. La posición se calcula con tamaño de pantalla y ubicación del notch.

Módulo release: pipeline completo de publicación

release organiza la distribución macOS. Es fácil omitir más de 8 pasos: versión, Archive, Notarize, Export, DMG, firma EdDSA, appcast.xml y GitHub release.

El uso típico añade release.json y ejecuta la CLI de Go incluida.

Flujo en 8 pasos:

1. Versión: actualizar Info.plist y archivos del proyecto
2. Archive: empaquetar con xcodebuild archive
3. Notarize: enviar con notarytool
4. Export: exportar .app con xcodebuild -exportArchive
5. DMG: crear el instalador con create-dmg
6. Firma EdDSA: firmar con Sparkle sign_update
7. appcast.xml: actualizar el feed con generate_appcast
8. GitHub release: publicar con gh release create

Ejemplo:

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

O ejecuta cada paso:

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

Se requieren GitHub CLI y una clave EdDSA de Sparkle. Sin gh, se detiene el último paso; sin clave, la firma.

La plantilla de release.json incluye versión, credenciales de notarización y ajustes DMG. Ante errores, lee el registro de notarytool.

Desglose de submódulos

Submódulo	Qué es	Qué resuelve	Uso típico	Comando	Flujo	Límite	FAQ
Definición	Pipeline completo + CLI Go	Automatiza 8 pasos de release	release.json + CLI	go run github.com/fayazara/macos-app-skills/release/cli@latest	Versión → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	GitHub CLI + clave Sparkle	¿Sin CLI? Publicación manual
Problemas cubiertos	Más de 8 pasos frágiles	Un paso omitido rompe la release	Cargar skill y seguir flujo	Sin comando único	Ejecutar → revisar → corregir	No omitir pasos	¿Fallo? Usar checklist
Uso típico	release.json + CLI	Implementación estándar	Añadir release.json y ejecutar	Ver bloque	Configurar → ejecutar → revisar	Configuración manual	¿release.json? Usar plantilla
CLI	Herramienta Go	Automatiza publicación	Un comando	go run github.com/.../cli@latest	Ejecutar → esperar → revisar	Entorno Go	¿Sin Go? Pasos manuales
Flujo	8 pasos	Checklist clara	Manual o CLI	Sin comando fijo	bump → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	Mantener orden	¿Cambiar orden? No recomendado
Límite	GitHub CLI + clave Sparkle	Requisitos	Comprobar gh y clave	gh --version, sign_update --help	Comprobar → configurar → ejecutar	Herramienta ausente bloquea	¿Clave? Usar sign_update
FAQ	release.json y notarización	Respuestas comunes	Plantilla y solución de errores	Sin comando fijo	Leer → configurar → corregir	Puede fallar varias veces	¿Fallo? Leer registro notarytool

Tres proyectos comparables: ¿cuál elegir?

Además de macos-app-skills, conviene comparar fireworks-macapp-creator y claude-swift-skills. Sus objetivos son distintos.

Diferencias de enfoque

Proyecto	Enfoque	Módulos	Características
macos-app-skills	Módulos funcionales centrados en macOS	7 módulos	build, macos-patterns, settings-ui, auto-update, notch-ui, release, instalación
fireworks-macapp-creator	Arquitectura + 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

Comparación de casos de uso

Escenario	macos-app-skills	fireworks-macapp-creator	claude-swift-skills
Solo macOS	Recomendado	Adecuado	Demasiado amplio; incluye iOS
macOS + iOS	Sin iOS	Sin iOS	Recomendado
Pipeline de release	Módulo release	Existe, menos detallado	macos-distribution
Sistema de estilos	Ninguno	8 estilos	Ninguno
Funciones WWDC 2025	Parcial, como Liquid Glass	Parcial	Cobertura amplia
Herramienta scaffold	Ninguna	Python genera proyectos SwiftPM	Ninguna

Recomendación

La decisión depende del alcance de plataformas, funciones y cobertura WWDC.

Solo macOS: elige macos-app-skills o fireworks-macapp-creator. El primero para release y notch; el segundo para scaffold y estilos.

macOS + iOS: elige claude-swift-skills. Es el único con iOS, Foundation Models, validación de stack, herramientas PRD y 22 skills.

Funciones WWDC 2025: elige claude-swift-skills por su cobertura de Liquid Glass, Swift 6.2 y SwiftData reciente.

En la práctica, macos-app-skills es el más ligero y rápido. fireworks-macapp-creator aporta el scaffold más completo para proyectos nuevos. claude-swift-skills es el más amplio para multiplataforma y WWDC. Mandan los requisitos del proyecto.

Conclusión

macos-app-skills es una caja de herramientas práctica para agentes que crean apps macOS nativas. Sus 7 módulos — build, macos-patterns, settings-ui, auto-update, notch-ui, release e instalación — reducen errores del primer intento. Aun así, hay que revisar Xcode, Swift, firma, notarización, claves Sparkle y el modelo. Un skill no garantiza una release automática.

Regla rápida: macos-app-skills o fireworks para solo macOS; claude-swift-skills para macOS + iOS; macos-app-skills para release; fireworks para estilos; claude-swift-skills para WWDC 2025.

El siguiente paso es ejecutar npx skills add fayazara/macos-app-skills -g -y, comparar alternativas con las necesidades del proyecto y revisar las prácticas de AGENTS.md. Si aparece un problema, empieza por la FAQ y la checklist del skill.