Portabilité de SKILL.md : Analyse technique de Claude Code vs. Codex CLI

Le format SKILL.md est une norme simple et puissante pour étendre les capacités des agents de codage. Claude Code d'Anthropic et Codex CLI d'OpenAI le prennent en charge. Cela soulève une question essentielle pour les développeurs : le même fichier SKILL.md fonctionne-t-il sur les deux plateformes ? La réponse simple est oui, le fichier lui-même est portable. La réponse utile est plus complexe et concerne moins le format de fichier que l'environnement d'exécution fourni par chaque agent.

Chez SkillProof, nous installons et exécutons des skills Claude Code sur des tâches réelles pour vérifier leur bon fonctionnement. Nous publions les résultats, y compris les échecs. Sur 2090 skills testés dans un environnement Claude Code, 1291 ont réussi (62 %), 697 n'ont fonctionné qu'après une configuration que la description doit détailler, et 102 ont reçu un verdict d'échec : certains se sont exécutés en aggravant la situation, d'autres n'ont pas pu s'exécuter du tout en raison d'un CLI manquant, d'une dépendance obsolète ou d'un exemple qui plante. Nous n'avons jamais exécuté de skill sur Codex CLI. L'intégralité de notre jeu de données est basée sur l'exécution avec Claude Code.

Cependant, notre corpus de tests contient un ensemble unique de preuves unidirectionnelles. Cet article examine les différences techniques dans la manière dont les deux agents gèrent SKILL.md et ce que nos données, exclusives à Claude, révèlent sur la portabilité de Codex vers Claude.

Le terrain d'entente : Le format SKILL.md

Avant de comparer les agents, il est essentiel de comprendre ce qu'est un fichier SKILL.md. C'est un fichier texte qui combine des instructions pour l'agent avec des métadonnées. La structure est simple :

1. Frontmatter YAML : Un bloc en tête de fichier, délimité par ---, contient des paires clé-valeur. name et description sont fondamentaux. L'agent utilise la description pour décider quand invoquer le skill. Une clé optionnelle allowed-tools nomme les outils que le skill souhaite pré-approuver pour ne pas interrompre l'exécution. C'est un champ de commodité, pas un bac à sable (sandbox) : il ne retire pas d'outils au modèle. Vous trouverez une analyse détaillée dans notre référence sur le frontmatter.
2. Corps Markdown : Sous le frontmatter se trouve l'ensemble d'instructions pour l'agent, rédigé en Markdown simple. Il indique au modèle comment accomplir la tâche, étape par étape.
3. Fichiers intégrés : Un skill peut inclure d'autres fichiers, comme des scripts ou des données de référence, qui sont fournis avec lui.

Point crucial, SKILL.md ne contient aucune signature de fonction ni schéma d'arguments. C'est un format d'instruction en langage naturel, pas un manifeste d'appel de fonction structuré. Ceci est le domaine de MCP, un protocole distinct. Pour une analyse plus approfondie, consultez notre comparatif Claude Skills vs. MCP.

Comme SKILL.md n'est que du texte structuré, tout analyseur (parser) compatible peut le lire. Claude Code et Codex CLI peuvent tous deux charger le même fichier sans modification. La différence réside dans ce qui se passe ensuite.

Chargement et exécution : Deux environnements différents

Bien que le fichier soit identique, le contexte dans lequel il s'exécute ne l'est pas. L'architecture de l'agent, ses paramètres par défaut et les outils disponibles définissent l'environnement d'exécution. C'est là qu'apparaissent les différences pratiques entre Claude Code et OpenAI Codex.

Claude Code

Dans notre travail, nous testons exclusivement avec Claude Code. Les skills sont chargés depuis ~/.claude/skills pour les skills personnels et .claude/skills à l'intérieur d'un projet pour ceux spécifiques au dépôt. Lorsque vous donnez une tâche à l'agent, il compare votre invite (prompt) avec le champ description de tous les skills disponibles. Vous pouvez également en appeler un directement par son nom avec une commande slash.

Un comportement critique que nous avons documenté est son mode d'échec. Si le frontmatter YAML d'un fichier SKILL.md est malformé (une tabulation mal placée, un guillemet manquant), Claude Code ne produit pas d'erreur de validation. Le skill devient simplement invisible pour l'agent. Il ne sera pas listé et ne sera jamais déclenché. Cet échec silencieux peut être difficile à déboguer, un sujet que nous abordons dans notre article sur que faire quand un skill ne se déclenche pas.

Notre méthodologie consiste à exécuter chaque skill sur une tâche du monde réel. Les résultats de nos 2090 tests montrent qu'un verdict de réussite ('pass') n'est pas garanti. Les 697 skills ayant obtenu le verdict 'setup' nécessitaient une configuration non triviale que nous avons dû documenter. Les 102 échecs ('fails') n'ont pas pu s'exécuter du tout en raison de dépendances manquantes ou ont produit un résultat pire que si aucun skill n'avait été utilisé.

Codex CLI

Codex CLI est un agent de codage en terminal open-source d'OpenAI. Ce n'est pas un wrapper d'API ; c'est un outil autonome qui lit une base de code, effectue des modifications multi-fichiers et exécute des commandes dans votre environnement local. Il a intégré le support de SKILL.md en décembre 2025, initialement comme une fonctionnalité expérimentale.

Les chemins de découverte ont changé depuis ce lancement, ce qui est bon à savoir si vous suivez un guide plus ancien. La documentation actuelle d'OpenAI liste .agents/skills dans le répertoire de travail et ses parents pour les skills de dépôt, $HOME/.agents/skills pour les skills personnels, et /etc/codex/skills pour les skills à l'échelle de la machine. L'emplacement original ~/.codex/skills est celui que vous verrez encore dans la plupart des README de skills tiers. Un skill peut être invoqué explicitement en tapant $ et en le choisissant dans la liste, ou il peut être déclenché implicitement si une tâche correspond à sa description.

Son fichier de configuration principal est ~/.codex/config.toml, et son jeu d'instructions de base peut être personnalisé via un fichier nommé AGENTS.md. Cela offre un point d'entrée différent pour la personnalisation par rapport au modèle centré sur les skills de Claude Code.

Alors, Codex supporte-t-il SKILL.md ? Oui, nativement. Le format de fichier est un citoyen de première classe. La divergence vient de l'environnement qu'il fournit pour l'exécution de ce fichier.

Portabilité unidirectionnelle : Ce que nos données révèlent

C'est le cœur du problème. Nous n'avons jamais testé de skill sur Codex CLI. Nous ne pouvons pas fournir un taux de réussite pour Codex ou une comparaison directe basée sur nos propres données de test. Prétendre le contraire reviendrait à inventer un jeu de données.

Ce que nous pouvons fournir, c'est un regard honnête sur un schéma spécifique dans nos résultats de test sur Claude Code. Sur les 2090 skills que nous avons testés, nos notes montrent que 47 d'entre eux mentionnent ou supposent un environnement Codex. Ces skills ont été écrits pour Codex, mais nous les avons exécutés dans un environnement Claude Code. Cela nous donne une vue unique et unidirectionnelle de la portabilité.

Les résultats pour ces 47 skills sont :

• Réussi : 11
• Configuration requise : 34
• Échec : 2

Cela raconte une histoire claire : un fichier SKILL.md écrit pour Codex nécessitera très probablement une configuration manuelle pour fonctionner sur Claude Code. Ce n'est pas parce que le fichier est invalide, mais parce que les instructions du skill reposent sur des outils ou des chemins qui n'existent pas dans le nouvel environnement.

Examinons des exemples spécifiques de notre catalogue :

• Generate 2D Map (Verdict : Configuration requise) : Le README en amont du skill indique explicitement qu'il est pour Codex/Grok et liste les chemins d'installation ~/.codex/skills et ~/.grok/skills, et non le ~/.claude/skills que sa description prétendait. Son pipeline principal nécessite une paire d'outils intégrés de génération et de visualisation d'images que Claude Code ne possède pas. Nous l'avons testé sur la seule branche qui ne nécessite pas d'images — la construction d'une carte orthogonale Tiled en JSON — et le skill a fait exactement comme le modèle de base : des tableaux de tuiles identiques au byte près, des métadonnées de spawn et de sortie identiques. Le fichier s'est chargé ; la partie qui justifiait son installation n'a pas fonctionné.

• Generate 2D Sprite (Verdict : Configuration requise) : Ce skill a le même problème. Il dépend fortement de capacités de génération d'images fournies avec Codex et Grok mais pas avec Claude Code. Il peut planifier une feuille de sprites, mais il ne peut pas exécuter l'étape finale de production de l'art.

• Ablation Planner (Verdict : Configuration requise) : Le mécanisme principal de ce skill implique de déléguer le travail de conception à un outil spécifique de Codex. Lorsqu'il est exécuté dans notre environnement Claude Code, cet outil n'était pas disponible. L'étape a dû être effectuée manuellement, ce qui est la définition d'un verdict de 'configuration requise' ('setup').

Ces exemples montrent que le fichier SKILL.md est portable, mais que la logique du skill peut ne pas l'être. Les instructions ne sont que du texte ; si elles demandent à l'agent d'utiliser un outil qui n'est pas présent, le processus s'arrêtera.

Inversement, 11 de ces skills orientés Codex ont réussi sans problème. Des skills comme Better Codex et PinMe Share ont réussi nos tests sur Claude Code. Tous deux tirent leur valeur du texte plutôt que d'outils propriétaires. Better Codex est une surcouche comportementale purement basée sur le prompt, sans fichiers externes ni scripts, et il a tout de même surpassé le modèle de base sur une tâche d'analyse de configuration, où le modèle de référence échouait silencieusement sur des valeurs contenant un signe égal. PinMe Share s'installe à partir d'un unique fichier SKILL.md valide sans références pendantes, et son avantage réside dans sa connaissance exacte d'un CLI npm ordinaire : il a émis la commande de téléversement canonique et les étapes d'authentification requises, là où le modèle de base a deviné la commande et omis la connexion. Voilà la forme d'un skill portable. Il a besoin d'un outil que vous pouvez installer, pas d'un outil intégré fourni avec l'agent d'un seul fournisseur.

Principales différences en un coup d'œil

Une comparaison directe met en évidence les compromis à faire lorsqu'on envisage d'utiliser Codex CLI ou Claude Code pour coder avec des skills.

Caractéristique	Claude Code	Codex CLI
Chemin des skills	~/.claude/skills (personnel), .claude/skills (projet)	$HOME/.agents/skills (personnel), .agents/skills (dépôt), /etc/codex/skills (machine)
Configuration	settings.json, plus CLAUDE.md pour les instructions	~/.codex/config.toml, plus AGENTS.md pour les instructions
Sandboxing	Opt-in ; les variables d'environnement sont héritées du shell parent	Activé par défaut en écriture dans l'espace de travail, réseau désactivé sauf si activé
SKILL.md malformé	Échec de chargement silencieux	(Comportement non testé par nous)

Le compromis du sandboxing

La différence la plus significative dans les environnements d'exécution est le comportement par défaut du sandboxing.

Codex CLI, selon sa documentation, fonctionne avec une posture de sécurité par défaut plus stricte. Dans son mode d'écriture dans l'espace de travail, l'accès réseau est désactivé sauf si vous l'activez explicitement dans config.toml. Les écritures sur le système de fichiers sont limitées à l'espace de travail actuel, et la politique d'approbation de l'agent demande par défaut une confirmation avant d'agir. C'est un modèle de 'refus par défaut' ('default-deny').

Claude Code, tel que documenté par Anthropic, adopte une approche différente. Le sandboxing est quelque chose que vous activez plutôt que vous ne désactivez, et même lorsqu'il est activé, le shell hérite par défaut de l'environnement du processus parent. Cela signifie que si vous avez des informations d'identification comme AWS_ACCESS_KEY_ID exportées dans votre session de terminal, un skill invoqué par Claude Code peut potentiellement les lire. Cela permet aux skills qui communiquent avec des services externes ou des informations d'identification locales de fonctionner directement, et vous impose la charge de gérer cette exposition.

Aucune approche n'est intrinsèquement meilleure ; c'est un compromis. Le modèle de Codex priorise la sécurité par défaut, ce qui peut nécessiter plus de configuration pour faire fonctionner un skill en réseau. Le modèle de Claude Code priorise la fonctionnalité prête à l'emploi, exposant potentiellement davantage l'environnement hôte. Un skill qui utilise curl pour appeler une API pourrait fonctionner directement sur Claude Code mais être bloqué par défaut sur Codex CLI.

La règle de décision : Jugez l'environnement, pas le fichier

Alors, Claude Code vs Codex CLI : lequel devriez-vous utiliser pour les skills ?

Nos données fournissent une réponse honnête, bien qu'incomplète. Le format de fichier SKILL.md lui-même n'est pas le facteur décisif. Le même fichier se chargera sur les deux plateformes. La vraie décision dépend de l'environnement d'exécution et des dépendances des skills que vous souhaitez utiliser.

1. Vérifiez les dépendances aux outils : Le skill repose-t-il sur des outils intégrés et spécifiques à l'agent (comme la génération d'images dans Generate 2D Map) ? Si c'est le cas, il ne sera pas portable.
2. Vérifiez les dépendances aux CLI universels : Le skill n'utilise-t-il que des outils en ligne de commande courants ? Il a de fortes chances d'être portable, comme le montrent les 11 skills orientés Codex qui ont réussi dans notre environnement Claude Code.
3. Considérez votre préférence en matière de sandboxing : Préférez-vous un système verrouillé par défaut qui nécessite des autorisations explicites (Codex CLI) ? Ou préférez-vous un système qui fonctionne avec moins de friction mais hérite du contexte complet de votre environnement (Claude Code) ?

Nous ne pouvons pas déclarer de vainqueur universel car nous n'avons pas testé sur les deux plateformes. Le choix dépend de vos besoins spécifiques et de votre posture de sécurité. Ce que nous pouvons affirmer avec certitude, c'est que supposer qu'un skill fonctionnera simplement parce que le fichier SKILL.md est compatible est une erreur. L'environnement est primordial.

Lectures complémentaires : AGENTS.md vs Claude Skills traite de l'autre moitié de la question multi-outils — le fichier d'instructions que chaque agent lit avant le chargement de tout skill. Et si vous choisissez entre des agents de terminal pour des raisons autres que les skills, Claude Code vs Cursor analyse ce compromis.

Chez SkillProof, notre valeur ajoutée consiste à éliminer cette incertitude pour l'écosystème Claude Code. Nous effectuons les tests pour que vous n'ayez pas à le faire. Chaque verdict de réussite ('pass') dans notre catalogue représente un skill que nous avons installé et exécuté sur Claude Code, sur des tâches réelles. Pour un point de départ organisé, nos packs de skills par rôle rassemblent chacun dix skills testés pour une fonction professionnelle — développeur, revue de sécurité, marketing, design et quatre autres — pour 10 $ le pack, avec le verdict de chaque skill clairement indiqué.