Utiliser macos-app-skills pour créer des apps Mac avec un agent IA

Comment Claude Code peut-il produire une app macOS de plus de 20 000 lignes alors que moins de 1 000 ont été écrites à la main ? Dans un retour d’expérience de 2025, Indragie relève cinq pièges : Swift Concurrency mal compris, mélange d’anciens et nouveaux frameworks, API obsolètes, mauvaise gestion des fenêtres et étapes de release oubliées. L’agent ignore les modèles natifs de macOS et traite alors le Mac comme une page Web.

macos-app-skills répond à ce problème. Le pack transforme des connaissances WWDC dispersées, une documentation incomplète et des modèles macOS faciles à rater en 7 modules : build, modèles natifs, réglages, mise à jour, interface du notch, release et installation. Chaque module précise son rôle, le problème résolu, l’usage, les commandes, le flux, les limites et la FAQ. L’agent dispose ainsi d’un meilleur point de départ. Voici le détail, puis un comparatif avec fireworks-macapp-creator et claude-swift-skills.

Installation : charger le pack dans l’agent

La commande est courte :

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

-g installe globalement et -y évite la confirmation interactive. Redémarrez ensuite l’agent pour qu’il charge le dossier. Lors d’un essai dans OpenCode, build, macos-patterns, settings-ui, auto-update, notch-ui et release sont apparus après le redémarrage.

Préparez macOS 14+, Xcode 15+ et Swift 5.9+. Les fonctions de macOS 26 comme Liquid Glass exigent Xcode 26 beta. Sur les anciennes versions, des solutions de repli conservent le flux de base.

Le chargement varie selon l’agent. Claude Code peut demander un chemin de skills configuré manuellement. OpenCode reconnaît ~/.config/opencode/skills/, tandis que Cursor attend .agents/skills/ à la racine. Demandez la liste des skills ou posez une question précise sur le module build.

Les échecs habituels concernent réseau, permissions et versions. Un accès lent aux assets GitHub se corrige avec un proxy ou une nouvelle tentative. Si le cache npx n’est pas accessible en écriture, préférez copier le dossier à sudo npx. Le projet datant de mai 2026, noms et nombre de skills peuvent évoluer : relisez la README avant installation.

Détail des sous-modules

Sous-module	Définition	Problème résolu	Usage type	Commande	Flux	Limite	FAQ
Installation	Installation globale via npx	Rend les skills macOS accessibles à l’agent	Installer en une commande	npx skills add fayazara/macos-app-skills -g -y	Exécuter → redémarrer → vérifier	Dépend de npx et du réseau	Réseau lent ? Proxy ou nouvelle tentative
Prérequis	Versions macOS/Xcode/Swift	Vérifie que l’environnement exécute le code	Contrôler les trois versions	sw_vers, xcodebuild -version, swift --version	Vérifier → comparer à la README → mettre à jour	macOS 14+, Xcode 15+, Swift 5.9+	Anciennes versions ? Repli partiel
Vérification du chargement	Confirme que les skills sont chargés	Valide l’installation	Lister les skills ou tester une référence	Pas de commande standard	Redémarrer → interroger → tester	Chemin différent selon l’agent	Non chargé ? Vérifier le chemin
Échecs courants	Réseau, permissions, versions	Accélère le diagnostic	Proxy, droits, contrôle de version	Pas de commande fixe	Réseau → droits → version	GitHub peut être lent	sudo ? Préférer une copie manuelle

Module build : compiler un projet macOS en ligne de commande

Le module build utilise xcodebuild pour compiler tout projet Xcode macOS sans passer par l’interface graphique.

Il couvre la découverte de .xcodeproj ou .xcworkspace, la détection des schemes, les chemins des toolchains bêta et les erreurs telles qu’un scheme absent ou une signature incorrecte. Les agents devinent souvent les paramètres ou emploient un scheme iOS pour macOS.

Chargez ce skill avant le build. Il explique comment trouver projet et scheme, puis traiter les erreurs. Exemple :

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

Avec un workspace :

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

Le flux est : découverte du projet → détection du scheme → build → inspection → correction. L’agent trouve le projet, liste les schemes, en choisit un et applique la liste de dépannage.

Le module vise les projets Xcode, pas les projets SwiftPM seuls. Il faut alors les ouvrir comme projet Xcode ou choisir un autre skill. Les toolchains bêta demandent aussi un traitement spécial, leurs versions et chemins n’étant pas standardisés.

Un scheme absent est souvent non partagé ou nommé différemment de la target. Lancez xcodebuild -list avant de deviner. Pour une bêta, le skill pointe généralement vers /Applications/Xcode-beta.app et ajoute -destination.

Détail des sous-modules

Sous-module	Définition	Problème résolu	Usage type	Commande	Flux	Limite	FAQ
Définition	Build macOS avec xcodebuild	Compile sans GUI	Charger avant le build	Voir les blocs de code	Découvrir → détecter → compiler → corriger	Projets Xcode uniquement	SwiftPM ? Convertir en projet Xcode
Problèmes couverts	Projet, scheme, toolchain, échecs	L’agent ignore les paramètres	Trouver le projet puis le scheme	xcodebuild -list d’abord	Exécuter → inspecter → corriger	Chemins bêta non standard	Bêta ? Donner chemin et destination
Usage type	Charger le skill avant le build	Évite les paramètres devinés	Charger build avant compilation	Pas de commande fixe	Charger → compiler → corriger	Le skill reste du savoir	Non chargé ? Vérifier la config
Commande	Commandes xcodebuild standard	Donne des exemples exécutables	Passer à xcodebuild	xcodebuild -project MyApp.xcodeproj -scheme MyApp	Exécuter → attendre → analyser	Paramètres exacts requis	Scheme ? Utiliser -list
Flux	Build → contrôle → correction	Cycle standard	Respecter les étapes	Pas de commande fixe	Découvrir → détecter → build → inspecter → corriger	Ne rien sauter	Échec ? Lire la checklist
Limite	Périmètre Xcode	Clarifie l’usage	Projets Xcode seulement	Aucune	Aucun	Pas de SwiftPM direct	Pourquoi ? Basé sur xcodebuild
FAQ	Scheme absent et toolchain bêta	Répond aux cas courants	Lister les schemes, préciser le chemin	xcodebuild -list	Vérifier → interroger → préciser	Configuration supplémentaire	Bêta ? Contrôler version et chemin

Module macos-patterns : ne pas traiter le Mac comme le Web

macos-patterns est le cœur du pack. Il rend consultables les modèles natifs et évite de transposer une interface Web au Mac. Barre de menus, hiérarchie des fenêtres et géométrie d’écran sont propres à macOS.

Les problèmes couverts sont :

1. Trois approches de barre de menus : MenuBarExtra en SwiftUI, NSStatusItem en AppKit et NSPopover pour une fenêtre contextuelle.
2. Politique d’activation : icône du Dock, LSUIElement et NSApplication.setActivationPolicy() ; sans cela, une app d’arrière-plan se comporte comme une app classique.
3. NSPanel ou NSWindow : un inspecteur flottant n’a pas le même comportement qu’une fenêtre normale.
4. Niveaux et collection behaviors : CGShieldingWindowLevel, NSWindow.Level et collectionBehavior règlent superposition, plein écran et multi-écrans.
5. Géométrie : frame ou visibleFrame, axe Y inversé et plusieurs écrans ; l’origine macOS est en bas à gauche.
6. Trois niveaux de raccourcis : .keyboardShortcut() de SwiftUI, moniteur NSEvent et hotkey Carbon au niveau système.
7. Autres modèles : NSOpenPanel, NSPasteboard, NSDragging, NavigationSplitView + inspector, LaunchAgent, QLPreviewPanel, NSWorkspace, ScreenCaptureKit et UserDefaults/@AppStorage.

Chargez ce skill avant de demander une interface macOS. Pour une app de barre de menus, l’agent pourra recommander MenuBarExtra en SwiftUI et garder NSStatusItem comme alternative AppKit.

Chaque modèle est classé par recommandation, alternative, contexte, code et limite. Voici les plus courants.

Comparatif des apps de barre de menus

Approche	Recommandation ou alternative	Usage	Exemple de code	Limite
MenuBarExtra	Recommandé	SwiftUI natif, cas simples	MenuBarExtra("App", systemImage: "app") { ContentView() }	macOS 13+
NSStatusItem	Alternative	Personnalisation complexe ou interop AppKit	NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)	Cycle de vie manuel
NSPopover	Complément	Fenêtre contextuelle ouverte au clic	NSPopover() + NSStatusItem	À combiner avec NSStatusItem

Comparatif des politiques d’activation

Politique	Scénario recommandé	Configuration	Code	Limite
NSApplication.ActivationPolicy.regular	App au premier plan avec Dock	Ne pas définir LSUIElement	Comportement par défaut	Cas courant
NSApplication.ActivationPolicy.accessory	App d’arrière-plan sans Dock, avec barre de menus	LSUIElement=true dans Info.plist	NSApplication.shared.setActivationPolicy(.accessory)	Barre de menus visible
NSApplication.ActivationPolicy.prohibited	Processus sans interface	Configuration LaunchAgent	NSApplication.shared.setActivationPolicy(.prohibited)	Ni Dock ni barre de menus

Comparatif des niveaux de fenêtre

Type	Valeur	Usage	Code	Limite
NSWindow.Level.normal	0	Fenêtre normale	Par défaut	Cas courant
NSWindow.Level.floating	3	Fenêtre flottante comme un Inspector	window.level = .floating	Ne couvre pas agressivement les autres apps
CGShieldingWindowLevel	Niveau maximal	Couche de masquage, par exemple notch-ui	window.level = CGShieldingWindowLevel()	Couvre tout ; à utiliser prudemment

Le module ne couvre que macOS. Pour un modèle multiplateforme, utilisez par exemple le module correspondant de claude-swift-skills.

NSApplication.setActivationPolicy() change dynamiquement l’icône du Dock. NSScreen.screens liste les écrans et visibleFrame retire Dock et barre de menus. L’axe Y doit être converti entre l’origine macOS en bas à gauche et l’origine Web en haut à gauche.

Module settings-ui : réglages et Liquid Glass

settings-ui traite la bonne implémentation d’une fenêtre de réglages macOS et Liquid Glass sous macOS 26. Il évite qu’un agent utilise une simple scène SwiftUI Window contraire aux conventions.

La scène Window ne prend pas en charge fullSizeContentView, donc le fond transparent ne s’étend pas correctement. Une mauvaise configuration de Liquid Glass donne aussi un rendu éloigné des Réglages système.

La combinaison type est NSWindowController + .fullSizeContentView + NavigationSplitView. Le skill fournit un fichier Swift complet. Flux :

1. Créer NSWindowController
2. Configurer fullSizeContentView
3. Ajouter NavigationSplitView avec sidebar et détail
4. Définir un fond transparent
5. Intégrer Liquid Glass sous macOS 26+

Exemple :

// 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 // Réglage clé
        self.init(window: window)
    }
}

Liquid Glass demande macOS 26+. Les anciennes versions reviennent à des matériaux ordinaires. Sans Liquid Glass, un WindowGroup SwiftUI standard suffit.

Le skill fournit le test de version pour sélectionner le matériau et un exemple complet de sidebar avec NavigationSplitView.

Module auto-update : intégrer Sparkle

auto-update corrige un piège de timing. SPUStandardUpdaterController doit être créé avant le retour de applicationDidFinishLaunching, sinon la vérification peut échouer et aucune invite ne s’affiche.

L’usage type combine un singleton UpdaterManager, Info.plist et une clé EdDSA. Le fichier UpdaterManager.swift est fourni.

Flux :

1. Ajouter Sparkle comme dépendance SPM
2. Créer le singleton UpdaterManager
3. Configurer SUFeedURL et SUPublicEDKey dans Info.plist
4. Générer une clé EdDSA avec sign_update
5. Ajouter les contrôles dans les réglages et la barre de menus

Exemple :

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

    init() {
        // À créer avant le retour de applicationDidFinishLaunching
        updaterController = SPUStandardUpdaterController(
            startingUpdater: true,
            updaterDelegate: nil,
            userDriverDelegate: nil
        )
    }
}

Ce module vise la distribution hors Mac App Store. Dans l’App Store, Sparkle n’est pas utilisable ; le Store gère les mises à jour.

La clé se génère avec sign_update. Pour tester, lancez un serveur de feed local ou déclenchez une vérification après une release.

Module notch-ui : une interface Dynamic Island autour du notch

notch-ui crée une interface flottante de type Dynamic Island autour de l’encoche d’un MacBook. Il ne s’agit pas de placer une fenêtre ordinaire en haut de l’écran.

Les difficultés sont un NSPanel borderless avec CGShieldingWindowLevel, le calcul de position et une forme personnalisée avec courbes de Bézier concaves. Sans ces détails, forme et position sont fausses.

Le modèle est borderless NSPanel + CGShieldingWindowLevel + NotchShape. Le skill fournit NotchWindow.swift et NotchShape.swift.

Flux :

1. Créer un NSPanel borderless
2. Définir CGShieldingWindowLevel
3. Implémenter NotchShape avec des courbes concaves
4. Ajouter une animation à ressort
5. Prévoir un mode pill pour les Mac sans notch

Exemple :

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

La solution vise les MacBook à encoche. Les iMac et Mac mini utilisent le mode pill ; si l’interface n’est pas nécessaire, ignorez le module.

Sur un Mac sans notch, la pill est centrée en haut. Sa position découle de la taille de l’écran et de l’emplacement du notch.

Module release : pipeline de publication complet

release structure la distribution macOS. Plus de 8 étapes manuelles sont faciles à oublier : version, Archive, Notarize, Export, DMG, signature EdDSA, appcast.xml et GitHub release.

L’usage type ajoute release.json puis lance la CLI Go fournie.

Flux en 8 étapes :

1. Version : mettre à jour Info.plist et les fichiers du projet
2. Archive : empaqueter avec xcodebuild archive
3. Notarize : envoyer avec notarytool
4. Export : exporter .app avec xcodebuild -exportArchive
5. DMG : créer l’installateur avec create-dmg
6. Signature EdDSA : signer avec Sparkle sign_update
7. appcast.xml : actualiser le feed avec generate_appcast
8. GitHub release : publier avec gh release create

Exemple :

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

Ou exécutez chaque étape :

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

Il faut GitHub CLI et une clé EdDSA Sparkle. Sans gh, la dernière étape bloque ; sans clé, la signature bloque.

La template de release.json couvre version, identifiants de notarisation et réglages DMG. En cas d’échec, lisez le journal de notarytool.

Détail des sous-modules

Sous-module	Définition	Problème résolu	Usage type	Commande	Flux	Limite	FAQ
Définition	Pipeline complet + CLI Go	Automatise 8 étapes de release macOS	release.json + CLI	go run github.com/fayazara/macos-app-skills/release/cli@latest	Version → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	GitHub CLI + clé Sparkle	Pas de CLI ? Publier manuellement
Problèmes couverts	Plus de 8 étapes fragiles	Un oubli casse la release	Charger le skill et suivre le flux	Pas de commande unique	Exécuter → inspecter → corriger	Ne rien sauter	Échec ? Utiliser la checklist
Usage type	release.json + CLI	Implémentation standard	Ajouter release.json et lancer	Voir le bloc	Configurer → lancer → contrôler	Configuration manuelle	release.json ? Utiliser la template
CLI	Outil Go	Automatise la publication	Une commande	go run github.com/.../cli@latest	Lancer → attendre → contrôler	Environnement Go	Pas de Go ? Étapes manuelles
Flux	8 étapes	Checklist claire	Manuel ou CLI	Pas de commande fixe	bump → Archive → Notarize → Export → DMG → EdDSA → appcast → GitHub	Garder l’ordre	Changer l’ordre ? Déconseillé
Limite	GitHub CLI + clé Sparkle	Prérequis	Vérifier gh et la clé	gh --version, sign_update --help	Vérifier → configurer → exécuter	Outil manquant = blocage	Clé Sparkle ? Utiliser sign_update
FAQ	release.json et notarisation	Réponses courantes	Template et dépannage	Pas de commande fixe	Lire → configurer → corriger	Plusieurs échecs possibles	Échec ? Lire le journal notarytool

Trois projets comparables : lequel choisir ?

Outre macos-app-skills, fireworks-macapp-creator et claude-swift-skills méritent comparaison. Leur positionnement diffère nettement.

Différences de positionnement

Projet	Positionnement	Modules	Caractéristiques
macos-app-skills	Modules fonctionnels centrés sur macOS	7 modules	build, macos-patterns, settings-ui, auto-update, notch-ui, release, installation
fireworks-macapp-creator	Architecture + styles + scaffold	8 styles	Scaffold Python, SwiftUI-first + AppKit, UI pilotée par styles
claude-swift-skills	Swift complet + iOS/macOS + WWDC 2025	22 skills	Swift 6.2, SwiftUI, SwiftData, Liquid Glass, Foundation Models, multiplateforme

Comparatif des usages

Scénario	macos-app-skills	fireworks-macapp-creator	claude-swift-skills
App macOS seule	Recommandé	Adapté	Trop lourd, inclut iOS
macOS + iOS	Pas d’iOS	Pas d’iOS	Recommandé
Pipeline de release	Module release	Présent, moins détaillé	macos-distribution
Système de styles	Aucun	8 styles	Aucun
Fonctions WWDC 2025	Partiel, dont Liquid Glass	Partiel	Couverture large
Outil de scaffold	Aucun	Python génère un projet SwiftPM	Aucun

Recommandation

Le choix dépend de la portée des plateformes, des fonctions et de la couverture WWDC.

macOS uniquement : choisissez macos-app-skills ou fireworks-macapp-creator. Le premier convient à la release et au notch ; le second au scaffold et aux styles.

macOS + iOS : choisissez claude-swift-skills. C’est le seul à couvrir iOS, Foundation Models, validation de stack, architecture PRD et 22 skills.

Fonctions WWDC 2025 : choisissez claude-swift-skills pour Liquid Glass, Swift 6.2 et les fonctions SwiftData récentes.

En pratique, macos-app-skills est le plus léger et rapide à adopter. fireworks-macapp-creator fournit le scaffold le plus complet pour un nouveau projet. claude-swift-skills offre la portée la plus large pour le multiplateforme et WWDC. Les exigences du projet tranchent.

Conclusion

macos-app-skills est une boîte à outils concrète pour les agents qui créent des apps macOS natives. Ses 7 modules — build, macos-patterns, settings-ui, auto-update, notch-ui, release et installation — réduisent les erreurs du premier essai. Il faut néanmoins contrôler Xcode, Swift, signature, notarisation, clés Sparkle et modèle. Un skill ne garantit pas une publication automatique.

Repère rapide : macos-app-skills ou fireworks pour macOS seul, claude-swift-skills pour macOS + iOS, macos-app-skills pour la release, fireworks pour les styles et claude-swift-skills pour WWDC 2025.

Vous pouvez maintenant lancer npx skills add fayazara/macos-app-skills -g -y, comparer les alternatives avec vos besoins et lire les bonnes pratiques d’AGENTS.md. En cas de problème, commencez par la FAQ et la checklist du skill.