Vous lancez Codex sur un projet Swift, mais les Agent Skills fournis avec Xcode 27 restent invisibles.
Action immédiate : vérifiez d’abord que les outils en ligne de commande pointent vers Xcode 27, puis exportez les compétences dans le dossier Codex indiqué par Apple.
Cet article s’adresse aux développeurs qui veulent réutiliser les conseils Apple dans Codex pour Swift ou SwiftUI, aux ingénieurs DevOps qui administrent un Mac distant avec plusieurs versions d’Xcode, et aux responsables de plateformes qui doivent distinguer les réglages personnels des consignes partagées par l’équipe.
Dernière vérification : 10 octobre 2026. Les éléments sur le problème connu et la procédure d’export sont recoupés avec les notes de version Xcode 27 d’Apple, les ressources développeur Apple et la documentation des compétences Codex. Le comportement de détection doit être vérifié avec la version de Codex effectivement installée : aucune lecture réussie sur un Mac distant n’est présumée ici.
SECTION 01 Repères de diagnostic
Un export et une compétence utilisable par Codex correspondent à des étapes différentes. La commande peut s’exécuter sans erreur alors que la chaîne d’outils active n’est pas celle attendue, que les fichiers sont écrits ailleurs ou que Codex ne découvre pas leur emplacement. Traitez donc le problème comme une vérification en plusieurs étapes, pas comme une simple commande à relancer.
| Étape | Ce que vous établissez | Preuve à conserver | Si le contrôle échoue |
|---|---|---|---|
| Chaîne d’outils | Le répertoire développeur sélectionné correspond à l’installation Xcode voulue | Sortie de xcode-select -p et chemin de Xcode |
Sélectionnez la bonne installation, puis contrôlez à nouveau |
| Commande | xcrun trouve la commande d’export dans la chaîne active |
Sortie de xcrun et résultat de la commande |
Vérifiez l’outil actif avant de modifier la destination |
| Export | Les fichiers sont effectivement présents à l’emplacement demandé | Liste du dossier de destination | Contrôlez le compte, le chemin et les éventuels messages d’erreur |
| Détection | Codex lit et suit une compétence adaptée | Résultat d’une tâche Swift ciblée | Vérifiez la documentation de votre version et gardez les preuves |
Cette séparation évite trois conclusions trop rapides : « l’export a réussi, donc Codex a chargé les fichiers », « les fichiers existent, donc ils sont au bon endroit » et « le terminal utilise forcément la même installation qu’Xcode ouvert dans l’interface ». Ce sont des hypothèses distinctes, qui demandent chacune une preuve.
SECTION 02 Outil actif et commande d’export
Commencez dans le terminal qui servira réellement à lancer l’export. Sur un Mac distant, cette précaution est essentielle : une session SSH, un terminal graphique et un compte de service peuvent ne pas utiliser la même configuration. L’environnement visible sur votre poste local ne permet pas de déduire celui de la session distante.
Affichez le répertoire développeur sélectionné :
xcode-select -p
Le chemin retourné indique le répertoire développeur que les outils en ligne de commande utilisent. Comparez-le à l’installation d’Xcode 27 que vous souhaitez employer ; ne vous contentez pas du nom de l’application visible dans le Dock. Apple documente la sélection des outils et leur relation avec le répertoire développeur dans ses instructions sur les outils en ligne de commande et sa note technique sur les outils en ligne de commande.
Vérifiez ensuite que xcrun résout bien des outils dans la chaîne attendue :
xcrun --find swift
Examinez le chemin retourné et comparez-le à l’installation que vous venez de contrôler. Ce test ne prouve pas à lui seul que chaque composant d’Xcode est disponible, mais il révèle une incohérence fréquente : l’interface Xcode ouverte et les outils appelés par le shell ne suivent pas la même sélection.
Si le répertoire actif n’est pas celui que vous voulez, sélectionnez le répertoire Contents/Developer de l’installation prévue, en remplaçant le chemin d’exemple par celui qui existe sur votre machine :
sudo xcode-select --switch /chemin/vers/Xcode-27.app/Contents/Developer
Ne copiez pas littéralement ce chemin fictif. Identifiez d’abord l’emplacement réel de l’application, vérifiez le répertoire sélectionné après le changement, puis relancez la vérification avec xcrun --find swift. La documentation Apple sur les exigences système d’Xcode aide également à vérifier que l’installation visée est adaptée à la version de macOS utilisée.
Une fois l’outil actif confirmé, appliquez la procédure indiquée par Apple pour exporter les compétences vers le répertoire Codex :
xcrun agent skills export --path ~/.codex/skills
Apple donne cette solution pour le cas où les Agent Skills rédigés par Apple ne s’affichent pas dans Codex : sélectionner Xcode 27 comme répertoire développeur actif, puis exporter vers ~/.codex/skills. La commande et la destination doivent être recoupées avec les notes de version Xcode 27, qui constituent la référence pour le problème connu et la correction proposée.
L’événement développeur Apple consacré aux compétences décrit leur export depuis Xcode ; il apporte un contexte utile, mais ne remplace pas la vérification de la destination ni celle de leur lecture par Codex. Vous pouvez consulter la présentation Apple sur l’export des Agent Skills pour comprendre le flux prévu.
N’ajoutez pas une option d’écrasement trouvée dans un exemple non vérifié. Si le dossier contient déjà des fichiers, sauvegardez-le ou choisissez une destination de test avant toute opération susceptible de les remplacer ; les notes Apple citées ci-dessus doivent rester la référence pour les options officiellement prises en charge.
SECTION 03 Destination, compte et lecture par Codex
Après l’export, inspectez le répertoire demandé :
ls -la "$HOME/.codex/skills"
Le contrôle doit être effectué avec le même compte utilisateur que celui qui lance Codex. Si l’export est fait dans une session SSH ouverte sous un compte d’administration, mais que Codex est lancé sous un autre compte, ~ peut désigner deux répertoires personnels différents. Dans ce cas, des fichiers peuvent avoir été créés sans être visibles dans l’environnement qui exécute l’agent.
Vérifiez trois éléments séparément :
- Présence : le répertoire contient des fichiers issus de l’export.
- Emplacement : le chemin inspecté est bien celui demandé par la commande et correspond au compte utilisé par Codex.
- Utilisation : une tâche adaptée montre que Codex a pris en compte les instructions de la compétence.
Cette distinction est importante, car les mécanismes de découverte peuvent dépendre de la version et de la configuration de Codex. Consultez la documentation OpenAI sur les concepts et l’organisation des compétences, puis comparez ses indications avec la version installée. Ne supposez pas qu’un fichier présent dans ~/.codex/skills est automatiquement chargé, ni qu’une consigne de projet partagée suit les mêmes règles qu’une compétence personnelle.
Sur un Mac distant, vérifiez aussi le contexte de connexion. Si la commande d’export s’exécute par SSH, relevez l’utilisateur, le répertoire personnel et l’installation Xcode sélectionnée dans cette session. Puis confirmez que Codex s’exécute sur cette même machine et sous le compte attendu. Si Codex tourne sur votre poste local alors que l’export a été effectué sur le Mac distant, les fichiers distants ne deviennent pas accessibles par magie à la session locale.
Pour une équipe, séparez les instructions personnelles des consignes destinées au dépôt. Une compétence exportée dans le dossier personnel d’un compte n’est pas, par ce seul fait, versionnée avec le projet ni partagée avec les autres développeurs. Avant d’adopter un emplacement de dépôt, vérifiez les règles de découverte documentées par la version actuelle de Codex et retenez une méthode d’équipe qui laisse une trace dans le contrôle de versions. Cette précaution évite qu’un poste fonctionne grâce à une configuration invisible pour les autres.
SECTION 04 Validation sur une tâche Swift réelle
La dernière étape n’est pas de relancer la commande, mais de vérifier un comportement observable. Choisissez une tâche dans le périmètre des instructions exportées, suffisamment ciblée pour distinguer une consigne suivie d’une réponse générique. Par exemple, demandez à Codex d’examiner une vue SwiftUI existante et de proposer une modification limitée qui respecte les conventions du projet, sans lui demander d’écrire immédiatement une fonctionnalité complète.
Procédez dans cet ordre :
- Fixez le contexte : notez la version d’Xcode, le résultat de
xcode-select -p, le compte utilisé et le fait que Codex tourne localement ou sur le Mac distant. - Faites un état initial : relevez le contenu du dossier de compétences avant l’export, afin de distinguer les fichiers préexistants de ceux qui viennent d’être générés.
- Exportez une seule fois : utilisez la destination recommandée par Apple après avoir confirmé la chaîne d’outils active.
- Contrôlez les fichiers : vérifiez leur présence et leur emplacement ; conservez le message de la commande et la liste du dossier.
- Soumettez une tâche ciblée : choisissez un cas Swift, SwiftUI ou UIKit cohérent avec les instructions de la compétence, puis examinez si Codex applique effectivement les directives pertinentes.
- Consignez le résultat : notez la tâche, la réponse observée et les conditions d’exécution ; si l’essai échoue, conservez ces éléments avant toute modification supplémentaire.
Une réponse conforme à une consigne ne constitue pas toujours une preuve certaine de chargement : le modèle peut produire un résultat similaire à partir du contexte du projet ou de la demande. À l’inverse, une réponse qui ne suit pas une instruction précise ne prouve pas à elle seule que le dossier est ignoré : la compétence peut ne pas concerner la tâche choisie. Formulez une demande qui teste une directive distinctive, sans inclure vous-même cette directive dans le prompt, puis comparez le résultat à un essai où le fichier n’est pas disponible, si votre protocole et vos règles de confidentialité le permettent.
Si l’essai reste négatif après vérification du chemin et du compte, arrêtez les exports répétés. Conservez la version de Codex, les sorties de xcode-select -p et de xcrun, le chemin inspecté et le résultat de la tâche. Ces éléments permettent de comparer votre situation aux consignes Apple et OpenAI sans écraser un état utile au diagnostic.
SECTION 05 FAQ de dépannage
Fichiers visibles, mais aucune différence dans les réponses
La présence des fichiers confirme seulement qu’ils ont été écrits. Vérifiez que votre tâche sollicite une directive précise de la compétence, puis consultez la documentation de votre version de Codex pour déterminer comment celle-ci découvre et utilise les compétences. Si le mode de découverte reste incertain, ne modifiez pas les fichiers au hasard : documentez la version, le dossier et le résultat afin de reproduire le contrôle.
Export lancé depuis un compte différent
Comparez le compte qui a exécuté xcrun agent skills export avec celui qui démarre Codex. Examinez la valeur de $HOME dans les deux contextes et contrôlez le chemin complet, plutôt que de supposer que ~/.codex/skills désigne toujours le même emplacement. Un écart de compte ou de session peut expliquer pourquoi l’export semble réussi tandis que l’agent ne voit aucun changement.
Plusieurs installations Xcode présentes
Une installation supplémentaire ne signifie pas que le terminal l’utilise. Gardez une trace de xcode-select -p, vérifiez la résolution avec xcrun --find swift et ne lancez l’export qu’après avoir confirmé le répertoire développeur visé. Si vous devez revenir à une autre installation, notez son chemin avant de modifier la sélection ; les outils en ligne de commande suivent la configuration active, pas nécessairement la dernière application ouverte.
SECTION 06 Choix de procédure selon votre environnement
Les deux tableaux ci-dessous servent à décider quoi vérifier avant de toucher aux fichiers. Le premier compare les contextes d’exécution ; le second indique le prochain contrôle selon le symptôme. Ils ne supposent pas que la détection Codex a été validée sur votre machine.
| Contexte | Risque de confusion | Vérification prioritaire | Décision |
|---|---|---|---|
| Mac avec une installation Xcode utilisée au quotidien | Le shell peut être configuré différemment de l’interface | xcode-select -p, puis résolution de swift |
Exportez seulement si le chemin correspond |
| Mac avec plusieurs installations Xcode | L’export peut utiliser une autre chaîne que celle prévue | Comparez le chemin actif à l’installation retenue | Sélectionnez l’installation voulue, puis exportez |
| Mac administré en SSH | Le compte, $HOME ou la session peut différer |
Contrôlez l’utilisateur et le répertoire personnel | Exportez et lancez Codex dans le contexte attendu |
| Poste de travail avec instructions partagées | Le dossier personnel ne versionne pas les consignes d’équipe | Vérifiez les règles de découverte Codex et le dépôt | Séparez configuration personnelle et partage d’équipe |
| Symptôme constaté | Interprétation prudente | Étape suivante |
|---|---|---|
La commande xcrun ne trouve pas l’export |
La chaîne active ou l’installation doit être vérifiée | Recontrôlez le répertoire développeur et les outils disponibles |
| La commande se termine, mais le dossier est vide | L’emplacement, le compte ou le résultat de l’export reste à établir | Inspectez le chemin exact et le contexte de session |
| Les fichiers sont présents, sans effet visible dans Codex | La détection et l’application ne sont pas démontrées | Consultez la documentation Codex et testez une consigne ciblée |
| Le résultat du test est ambigu | La tâche ne permet peut-être pas d’isoler la compétence | Choisissez une directive distinctive et consignez le protocole |
Si vous n’avez pas de Mac avec Xcode 27 pour vérifier la chaîne, l’export et le test Swift, une machine virtuelle ou un serveur Linux ne remplace pas l’environnement macOS requis pour cette procédure. Un poste déjà disponible reste préférable si vous devez seulement vérifier une fois, et l’achat d’un Mac peut être plus cohérent pour une charge soutenue ou des besoins matériels locaux. En revanche, pour un contrôle temporaire, les solutions bricolées autour de plusieurs installations, d’un accès distant improvisé et d’un compte mal identifié ajoutent des causes de panne sans prouver la lecture par Codex.
Vous pouvez d’abord consulter les informations sur l’accès à un environnement Mac distant, puis examiner les formules de location Mac si vous avez besoin d’un environnement macOS accessible pour cette vérification. La location proposée par VPSNIX peut vous éviter l’achat d’une machine pour un besoin ponctuel ; elle ne dispense toutefois pas de confirmer l’outil actif, le compte et la lecture réelle des compétences avant de déclarer le problème résolu.
SECTION 07 FAQ
Pourquoi les Agent Skills d’Xcode 27 n’apparaissent-ils pas dans Codex ?
Apple signale un problème connu où les compétences fournies avec Xcode peuvent ne pas apparaître dans Codex. L’export peut aussi viser le mauvais répertoire si la chaîne d’outils active ne correspond pas à l’installation attendue, ou si vous vérifiez un dossier différent de celui utilisé par votre session Codex. Contrôlez ces éléments séparément avant de conclure à un défaut de Codex.
Comment vérifier que xcrun utilise bien Xcode 27 ?
Dans le terminal de l’environnement où vous lancez l’export, exécutez `xcode-select -p` pour afficher le répertoire développeur sélectionné, puis `xcrun --find swift` pour examiner la résolution d’un outil de la chaîne active. Comparez les chemins obtenus à l’installation d’Xcode 27 que vous souhaitez utiliser ; le nom affiché dans l’interface graphique ne suffit pas à prouver ce choix.
Comment exporter les compétences Apple dans le dossier de Codex ?
Après avoir sélectionné l’installation Xcode voulue comme répertoire développeur actif, utilisez la commande d’export documentée par Apple avec le dossier Codex comme destination : `xcrun agent skills export --path ~/.codex/skills`. Vérifiez ensuite que des fichiers ont été écrits dans ce répertoire. La sortie de la commande prouve l’export, pas que Codex a ensuite chargé ou suivi ces instructions.
Que faire si l’export réussit sur un Mac distant, mais que Codex ne suit toujours pas les compétences ?
Vérifiez d’abord que l’export et Codex s’exécutent sous le même compte, sur le même Mac et avec le même dossier personnel. Inspectez le chemin de destination et la structure des fichiers, puis consultez la documentation de la version de Codex installée pour confirmer son mode de découverte. Si rien ne change, conservez les sorties et évitez de répéter l’export avec une option susceptible d’écraser des fichiers.