En 2026, OpenHands Skills ou AGENTS.md ? Comment choisir pour un dépôt iOS

Les règles courtes qui doivent être visibles à chaque tâche vont dans AGENTS.md ; les procédures iOS volumineuses ou spécialisées vont dans les OpenHands Skills. Cette séparation ne dispense jamais de faire vérifier la compilation, la signature et les tests sur un Mac réel ou distant.

Dernière mise à jour : 6 septembre 2026. Les recommandations ont été recoupées avec la documentation officielle des OpenHands Skills, le guide officiel de création d’un Skill, ainsi que les procédures Xcode consacrées aux schémas de compilation et à l’exécution des tests.

Cet article s’adresse à trois profils :

• Responsable de dépôt : vous voulez une convention minimale, stable et commune à tous les agents ;
• Développeur mobile : vous avez besoin d’un flux iOS déclenché seulement lorsque la tâche le justifie ;
• Équipe plateforme ou sécurité : vous devez contrôler les priorités, les scripts, les outils et les permissions associés aux règles.

La frontière de responsabilité entre contexte et exécution

La question « OpenHands Skills et AGENTS.md, quelle différence ? » se résout en séparant deux fonctions, et non en choisissant un format préféré.

AGENTS.md doit contenir le contexte permanent que l’agent ne peut pas ignorer sans risquer de travailler dans le mauvais dépôt. Vous pouvez y placer :

• la finalité du projet et ses limites ;
• l’organisation des répertoires ;
• le point d’entrée de l’application ;
• les commandes d’installation vérifiées ;
• les conventions de modification ;
• les contrôles CI qui bloquent une fusion ;
• les chemins ou fichiers qui nécessitent une revue humaine.

Le document doit rester court, testable et directement relié au contenu du dépôt ou à une configuration existante. Une règle comme « ne modifiez pas les fichiers générés » est vérifiable. Une page entière expliquant l’architecture historique du produit ne l’est pas forcément et risque de consommer du contexte à chaque demande.

Les Skills ont une autre fonction. Ils regroupent une connaissance activée lorsqu’un agent rencontre un domaine, un framework ou une tâche particulière. La documentation officielle présente le Skill autour d’un fichier SKILL.md et permet d’associer des ressources complémentaires, notamment des scripts ou des références, selon l’implémentation retenue【https://docs.openhands.dev/overview/skills】.

La description du Skill doit donc aider l’agent à déterminer quand il doit le charger. « Utiliser ce Skill pour préparer une cible iOS, exécuter les tests d’interface ou analyser un échec de signature » est plus exploitable que « règles mobiles ». Le contenu peut être plus riche qu’AGENTS.md, mais il ne doit pas recopier les règles générales du dépôt sous une deuxième forme.

Attention : une règle présente dans deux endroits avec une formulation différente devient une décision implicite. Si la convention est obligatoire pour toutes les tâches, gardez une seule définition dans AGENTS.md, puis faites référence à cette définition depuis le Skill.

Le choix par rôle dans une équipe iOS

La meilleure organisation dépend moins de la taille du fichier que de la personne qui en assume la maintenance et du moment où la règle doit être appliquée.

Le responsable du dépôt : la base commune

Le mainteneur doit commencer par inventorier les règles déjà observables : scripts du dépôt, fichiers de configuration, étapes CI, schémas de projet et instructions de contribution. Il ne doit pas transformer AGENTS.md en manuel de formation.

Une base convenable peut ressembler à ceci, sans imposer des commandes qui n’existent pas réellement :

# AGENTS.md

- Le dépôt contient l’application iOS principale et ses tests associés.
- Respecter les fichiers de configuration et les scripts déjà utilisés par la CI.
- Ne pas modifier les fichiers générés sans justification dans le changement.
- Avant de proposer une fusion, fournir les résultats des contrôles exécutés.
- Toute modification de signature, de dépendance ou de pipeline demande une revue.

Les commandes Xcode ne doivent pas être ajoutées simplement parce qu’elles sont habituelles dans un autre projet. Vous devez d’abord les retrouver dans le schéma, le script de CI ou la documentation du dépôt. La personnalisation des schémas détermine en effet les actions et les cibles réellement sélectionnées【https://developer.apple.com/documentation/xcode/customizing-the-build-schemes-for-a-project?changes=_6&utm_source=openai】.

Le développeur mobile : le Skill iOS à la demande

Le développeur peut ensuite créer un Skill dédié à l’outillage iOS. Il peut expliquer :

• comment identifier le projet ou l’espace de travail ;
• comment choisir une cible et un schéma ;
• quels tests unitaires, d’interface ou de régression sont concernés ;
• comment interpréter un échec de compilation ;
• quels paramètres doivent être confirmés avant une opération de signature ;
• où trouver les journaux générés par le projet.

Cette connaissance doit rester conditionnelle. Une tâche de documentation ne devrait pas entraîner le chargement de toute la procédure de test sur simulateur. À l’inverse, une demande de correction d’un échec de build doit pouvoir déclencher le Skill sans dépendre d’une phrase vague dans le prompt.

Les versions de Xcode, les appareils simulés disponibles, les identifiants de cible et les commandes de build doivent être vérifiés à partir du projet ou de la CI. Un Skill décrit une méthode ; il ne prouve pas que la machine possède la bonne version, le bon simulateur ou les certificats requis.

La plateforme : priorité, partage et retour arrière

L’équipe plateforme doit documenter les différentes sources de règles : contexte du projet, Skills liés à l’utilisateur ou à l’environnement, anciens répertoires et éventuelles conventions héritées. Il est risqué d’affirmer qu’un fichier situé dans un répertoire donné gagnera toujours, car la priorité effective dépend de la version et du mode de fonctionnement documentés par OpenHands.

La documentation SDK consacrée aux Skills et la documentation d’architecture des Skills doivent être consultées avant chaque migration importante. Dans la pratique, votre gouvernance devrait imposer quatre propriétés :

1. chaque règle partagée possède un propriétaire ;
2. chaque Skill partagé a une version ou un identifiant de révision ;
3. les changements de priorité sont testés dans un dépôt de référence ;
4. une ancienne configuration reste disponible pendant la migration.

Les anciennes formes liées aux Microagents doivent être traitées comme un contexte de migration, pas comme le choix par défaut. Les documents officiels indiquent désormais les Skills comme le modèle actuel et signalent certaines anciennes trajectoires comme héritées ou dépréciées【https://docs.openhands.dev/overview/skills】. Cela ne signifie pas que vous devez supprimer immédiatement tout ancien contenu : commencez par comparer le résultat réellement chargé sur une tâche identique.

La sécurité : le fichier Markdown n’est pas la totalité du risque

Un Skill peut référencer des scripts, des documents ou des configurations d’outils. L’analyse de sécurité ne peut donc pas se limiter au texte de SKILL.md. Vous devez examiner :

• les permissions d’exécution des scripts ;
• les chemins absolus et les répertoires accessibles ;
• les variables d’environnement récupérées ;
• les contenus dynamiques téléchargés ou générés ;
• les outils MCP disponibles ;
• les opérations touchant les certificats, les profils de provisioning ou les secrets ;
• les commandes capables de modifier le dépôt ou la machine.

Un Skill qui explique une commande dangereuse n’est pas équivalent à un Skill qui peut l’exécuter. Cette distinction entre contexte fourni à l’agent et capacité réellement accordée à l’outil doit figurer dans la revue. Les Hooks, par exemple, relèvent d’un mécanisme distinct et ne doivent pas être confondus avec un texte de procédure【https://docs.openhands.dev/openhands/usage/customization/hooks?utm_source=openai】.

La matrice de décision pour votre dépôt

Le tableau suivant sert à décider où placer une règle avant de l’écrire. Il ne remplace pas une revue, mais évite de transformer chaque besoin local en nouvelle convention globale.

Trois critères permettent de trancher lorsqu’un contenu semble appartenir aux deux catégories : doit-il s’appliquer à une tâche qui ne touche pas iOS ? Est-il vérifiable à partir du dépôt ? Son absence peut-elle rendre toute modification incorrecte ? Si les réponses sont respectivement non, non et oui, vous avez probablement affaire à une procédure spécialisée à placer dans un Skill, accompagnée d’un contrôle explicite.

Le flux iOS à construire dans un Skill

Un Skill iOS utile ne se limite pas à recopier une liste de commandes. Il doit guider l’agent dans une séquence où chaque hypothèse est vérifiée avant l’étape suivante.

Les entrées du projet

Commencez par demander à l’agent d’identifier le fichier de projet, l’espace de travail, la cible et le schéma. Un dépôt peut contenir plusieurs applications, des tests séparés ou des extensions. Ne laissez pas le Skill choisir silencieusement le premier fichier trouvé.

Les préconditions de la machine

Le Skill doit indiquer comment vérifier la version de Xcode, l’état du simulateur, l’espace disponible et l’accès aux dépendances. Ces informations doivent être lues sur la machine de validation ou dans la CI, jamais déduites d’une ancienne capture d’écran.

Le build ciblé

Le flux doit sélectionner une cible précise et conserver la commande réellement acceptée par le projet. Pour les projets comportant plusieurs configurations, le Skill doit demander laquelle est concernée au lieu de supposer qu’une configuration de développement convient à une livraison.

Les tests

Distinguez les tests unitaires, les tests d’interface et les contrôles manuels. La documentation Apple décrit l’exécution et l’interprétation des résultats Xcode, notamment la nécessité d’examiner les résultats plutôt que de se contenter d’une commande terminée【https://developer.apple.com/documentation/xcode/running-tests-and-interpreting-results?changes=_3&utm_source=openai】.

Les éléments de preuve

Le résultat attendu doit inclure la commande utilisée, la cible, le schéma, la machine ou le simulateur, les journaux et les tests non exécutés. « L’agent indique que le build est terminé » n’est pas une preuve de build réussi.

La signature et les appareils

La signature doit rester un chemin à risque distinct. Un Skill peut expliquer quels contrôles effectuer, mais il ne doit pas donner implicitement accès aux certificats ou aux profils nécessaires à toutes les tâches. La construction et l’exécution sur un appareil réel suivent des conditions spécifiques que la procédure de construction et lancement d’une application dans Xcode permet de recouper.

Rappel : un test sur simulateur ne valide pas automatiquement la signature, l’installation sur appareil, l’accès aux services protégés ni la préparation d’une publication. Chaque résultat doit porter sur le périmètre effectivement exécuté.

Les coûts cachés des règles mal placées

Une séparation incorrecte crée au moins quatre problèmes opérationnels.

D’abord, un AGENTS.md trop long augmente le contexte envoyé à des tâches qui n’ont aucun rapport avec iOS. L’agent reçoit alors des détails sur le provisioning, les tests d’interface et les schémas alors qu’il doit seulement corriger une documentation.

Ensuite, un Skill trop général peut ne jamais être chargé au bon moment. Une description imprécise ne donne pas à l’agent de signal suffisant pour reconnaître une tâche de test ou de signature.

Troisièmement, les règles dupliquées dérivent. Une modification de commande peut être appliquée dans la CI mais rester ancienne dans le Skill. Le résultat ressemble à un problème de raisonnement de l’agent alors qu’il s’agit d’une incohérence de maintenance.

Enfin, les permissions deviennent invisibles. Un script référencé dans un document peut accéder à un répertoire sensible, appeler un outil externe ou produire une modification durable. La revue doit donc couvrir le comportement de la ressource, ses entrées et ses sorties, pas seulement sa formulation.

La migration depuis les Microagents

La question « faut-il migrer les Microagents vers les Skills ? » ne doit pas recevoir une réponse uniforme. Le bon critère est la fonction actuelle du contenu.

Migrez vers un Skill ce qui correspond à une connaissance spécialisée, à une procédure activée dans certaines tâches ou à un ensemble de ressources qui doit évoluer indépendamment des règles communes. Conservez dans AGENTS.md ce qui décrit les invariants du dépôt et les contrôles applicables à toute modification.

Avant de supprimer une ancienne structure, exécutez une tâche témoin avec les deux configurations. La tâche doit être suffisamment concrète pour révéler les différences : modification limitée d’une cible, lancement d’un test associé, production d’un journal et résumé des fichiers modifiés. Comparez le contexte chargé, les commandes proposées et les preuves produites.

Ne concluez pas qu’une migration est réussie parce que l’agent répond correctement à une question. Elle est réussie lorsque le comportement observé, les restrictions d’accès et les éléments transmis à la validation restent conformes au dépôt.

Le passage obligatoire vers une validation Mac

Le responsable de publication doit recevoir un paquet de remise clair :

• le correctif ou le commit ;
• la liste des fichiers modifiés ;
• les dépendances ajoutées ou mises à jour ;
• les commandes réellement exécutées ;
• les tests passés et ignorés ;
• les journaux utiles ;
• les changements de signature ou de configuration ;
• les points qui exigent une décision humaine.

Vous pouvez séparer les risques en quatre portes : compilation, tests sur simulateur, signature et publication. Un agent peut préparer un correctif sans avoir le droit de signer. Il peut réussir un test unitaire sans avoir validé l’installation sur appareil. Cette séparation réduit la portée d’une erreur et rend la revue plus lisible.

Pour vérifier votre configuration avant de l’adopter dans plusieurs dépôts, utilisez cette liste :

• [ ] AGENTS.md contient uniquement les règles communes et vérifiables.
• [ ] La description du Skill indique clairement les tâches qui doivent le déclencher.
• [ ] Les commandes Xcode proviennent du projet, de la CI ou d’une procédure validée.
• [ ] Le Skill distingue compilation, tests, signature et publication.
• [ ] Chaque script associé possède un propriétaire et une revue de permissions.
• [ ] Les chemins sensibles et les outils disponibles sont explicitement recensés.
• [ ] L’ancienne configuration Microagents peut encore être restaurée pendant la migration.
• [ ] Une tâche identique a été exécutée avec l’ancienne et la nouvelle organisation.
• [ ] Les journaux de build et de test sont transmis avec le correctif.
• [ ] Un Mac de validation indépendant confirme les contrôles annoncés par l’agent.

Cette dernière ligne est déterminante. Si vous ne pouvez pas produire la preuve, la règle ne doit pas être présentée comme une validation accomplie.

Quand un Mac distant devient rationnel

Un Mac local reste préférable lorsque vous avez besoin d’un appareil physique précis, d’interfaces audio ou vidéo connectées, d’un accès direct à des périphériques de design, ou d’une charge de travail longue et stable que votre équipe contrôle déjà. La location n’est pas automatiquement meilleure dans ces cas.

En revanche, votre organisation actuelle présente des limites concrètes si le même Mac sert à la fois de poste quotidien, de machine de test et d’environnement de signature : les tâches se concurrencent, l’état du simulateur devient difficile à reproduire, les permissions restent liées à un utilisateur local et la validation peut être interrompue par une activité sans rapport avec le dépôt. Une machine partagée ou un environnement distant mal documenté ajoute également des délais de remise en état et des incertitudes sur les dépendances.

Dans ce contexte, louer un Mac auprès de SSHMac peut offrir un environnement séparé pour un essai à faible risque, une vérification Xcode ou une migration de règles, sans transformer le poste principal en serveur de validation. Vous pouvez examiner les modalités d’accès VNC à distance et vérifier si une location de Mac mini correspond à votre besoin. Cette solution ne remplace ni la gouvernance des Skills ni une politique de signature : elle fournit seulement une machine distincte sur laquelle les preuves peuvent être produites.

Commencez par un changement iOS sans enjeu de publication, comparez le chargement d’AGENTS.md et du Skill, puis demandez au Mac de confirmer le build et les tests. Si votre poste local ne peut pas assumer régulièrement cette étape, un espace Mac distant devient alors une décision d’exploitation mesurable, plutôt qu’une simple extension du prompt de l’agent.