SKILL.md Portabiliteit: Een Technische Blik op Claude Code vs. Codex CLI

Het SKILL.md-formaat is een eenvoudige, krachtige standaard om de mogelijkheden van codeer-agents uit te breiden. Zowel Anthropic's Claude Code als OpenAI's Codex CLI ondersteunen het. Dit leidt tot een cruciale vraag voor ontwikkelaars: werkt hetzelfde SKILL.md-bestand op beide? Het simpele antwoord is ja, het bestand zelf is porteerbaar. Het nuttige antwoord is complexer en heeft minder te maken met het bestandsformaat en meer met de uitvoeringsomgeving die elke agent biedt.

Bij SkillProof installeren en draaien we Claude Code-skills op echt werk om te zien of ze slagen. We publiceren de resultaten, inclusief mislukkingen. Van de 2090 skills die in een Claude Code-omgeving zijn getest, zijn er 1291 geslaagd (62%), 697 werkten alleen na configuratie die de beschrijving voor u moet uitschrijven, en 102 kregen het oordeel 'mislukt': sommige draaiden en lieten u slechter achter dan zonder skill, andere konden helemaal niet draaien vanwege een ontbrekende CLI, een dode afhankelijkheid of een voorbeeld dat crasht. We hebben nog nooit een skill op Codex CLI gedraaid. Onze volledige dataset is gebaseerd op uitvoering met Claude Code.

HOns testcorpus bevat echter een unieke, eenzijdige set bewijs. Dit artikel onderzoekt de technische verschillen in hoe de twee agents SKILL.md verwerken en wat onze data, die alleen op Claude is gebaseerd, onthult over de portabiliteit van Codex naar Claude.

De Gemeenschappelijke Basis: Het SKILL.md-formaat

Voordat we de agents vergelijken, is het essentieel om te begrijpen wat een SKILL.md-bestand is. Het is een tekstbestand dat instructies voor de agent combineert met metadata. De structuur is eenvoudig:

1. YAML Frontmatter: Een blok bovenaan het bestand, afgebakend door ---, bevat key-value-paren. name en description zijn fundamenteel. De agent gebruikt de beschrijving om te beslissen wanneer de skill moet worden aangeroepen. Een optionele allowed-tools-key benoemt tools waarvoor de skill vooraf goedkeuring wil, zodat deze niet halverwege de uitvoering stopt om te vragen. Het is een gemaksveld, geen sandbox: het ontneemt het model geen tools. Een gedetailleerde uitleg vindt u in onze frontmatter-referentie.
2. Markdown Body: Onder de frontmatter staat de instructieset voor de agent, geschreven in pure markdown. Dit vertelt het model hoe de taak stap voor stap moet worden uitgevoerd.
3. Gebundelde Bestanden: Een skill kan andere bestanden bevatten, zoals scripts of referentiedata, die ermee worden verpakt.

Cruciaal is dat SKILL.md geen functiesignaturen of argumentschema's bevat. Het is een instructieformaat in natuurlijke taal, geen gestructureerd manifest voor functieaanroepen. Dat is het domein van MCP, een afzonderlijk en onderscheidend protocol. Voor een diepere duik hierin, zie onze vergelijking van Claude Skills vs. MCP.

Omdat SKILL.md slechts gestructureerde tekst is, kan elke compatibele parser het lezen. Zowel Claude Code als Codex CLI kunnen hetzelfde bestand laden zonder aanpassingen. Het verschil zit in wat er daarna gebeurt.

Laden en Uitvoeren: Twee Verschillende Omgevingen

Hoewel het bestand hetzelfde is, is de context waarin het wordt uitgevoerd dat niet. De architectuur van de agent, de standaardinstellingen en de beschikbare tooling definiëren de uitvoeringsomgeving. Hier komen de praktische verschillen tussen Claude Code en OpenAI Codex naar voren.

Claude Code

In ons werk testen we uitsluitend met Claude Code. Skills worden geladen vanuit ~/.claude/skills voor persoonlijke skills en .claude/skills binnen een project voor repo-specifieke skills. Wanneer u de agent een taak geeft, vergelijkt deze uw prompt met het description-veld van alle beschikbare skills. U kunt er ook een direct aanroepen op naam met een slash-commando.

Een kritiek gedrag dat we hebben gedocumenteerd, is de manier waarop het faalt. Als de YAML-frontmatter in een SKILL.md-bestand misvormd is - een verkeerd geplaatste tab, een ontbrekend aanhalingsteken - produceert Claude Code geen validatiefout. De skill wordt simpelweg onzichtbaar voor de agent. Hij wordt niet weergegeven in de lijst en zal nooit worden geactiveerd. Deze stille mislukking kan moeilijk te debuggen zijn, een onderwerp dat we behandelen in onze post over wat te doen als een skill niet wordt geactiveerd.

Onze methodologie omvat het uitvoeren van elke skill op een taak uit de praktijk. De resultaten van onze 2090 tests tonen aan dat een 'geslaagd'-oordeel niet gegarandeerd is. De 697 skills die het oordeel 'configuratie' kregen, vereisten niet-triviale configuratie die we moesten documenteren. De 102 'mislukte' skills konden ofwel helemaal niet draaien vanwege ontbrekende afhankelijkheden, of produceerden een resultaat dat slechter was dan het niet gebruiken van een skill.

Codex CLI

Codex CLI is een open-source terminal codeer-agent van OpenAI. Het is geen API-wrapper; het is een zelfstandige tool die een codebase leest, bewerkingen in meerdere bestanden uitvoert en commando's draait in uw lokale omgeving. Het introduceerde SKILL.md-ondersteuning in december 2025, aanvankelijk als een experimentele functie.

De detectiepaden zijn sinds die lancering verplaatst, wat goed is om te weten als u een oudere gids volgt. De huidige OpenAI-documentatie vermeldt .agents/skills in de werkdirectory en de bovenliggende mappen voor repo-specifieke skills, $HOME/.agents/skills voor persoonlijke, en /etc/codex/skills voor machine-brede skills. De oorspronkelijke ~/.codex/skills-locatie is degene die u nog steeds zult zien in de meeste README's van skills van derden. Een skill kan expliciet worden aangeroepen door $ te typen en uit de lijst te kiezen, of impliciet worden geactiveerd als een taak overeenkomt met de beschrijving.

Het primaire configuratiebestand is ~/.codex/config.toml, en de kerninstructieset kan worden aangepast via een bestand genaamd AGENTS.md. Dit biedt een ander startpunt voor aanpassing vergeleken met het skill-gerichte model van Claude Code.

Dus, ondersteunt Codex SKILL.md? Ja, native. Het bestandsformaat is een 'first-class citizen'. De divergentie komt voort uit de omgeving die het biedt om dat bestand in uit te voeren.

Eenzijdige Portabiliteit: Wat Onze Data Tonen

Dit is de kern van de kwestie. We hebben nooit een skill op Codex CLI getest. We kunnen geen slagingspercentage voor Codex of een directe, naast elkaar geplaatste vergelijking bieden op basis van onze eigen testdata. Iets anders beweren zou neerkomen op het verzinnen van een dataset.

Wat we wel kunnen bieden, is een eerlijke blik op een specifiek patroon in onze Claude Code-testresultaten. Van de 2090 skills die we hebben getest, blijkt uit onze notities dat 47 ervan een Codex-omgeving vermelden of aannemen. Deze skills zijn geschreven voor Codex, maar we hebben ze in een Claude Code-omgeving gedraaid. Dit geeft ons een unieke, eenzijdige kijk op portabiliteit.

De resultaten voor die 47 skills zijn:

• Geslaagd: 11
• Configuratie: 34
• Mislukt: 2

Dit vertelt een duidelijk verhaal: een SKILL.md-bestand dat voor Codex is geschreven, vereist hoogstwaarschijnlijk handmatige configuratie om op Claude Code te draaien. Dit komt niet doordat het bestand ongeldig is, maar doordat de instructies van de skill afhankelijk zijn van tools of paden die niet bestaan in de nieuwe omgeving.

Laten we specifieke voorbeelden uit onze catalogus bekijken:

• Generate 2D Map (Oordeel: Configuratie): De upstream README van de skill vermeldt expliciet dat deze voor Codex/Grok is en geeft installatiepaden op als ~/.codex/skills en ~/.grok/skills, niet de ~/.claude/skills die in de beschrijving werd geclaimd. De primaire pipeline heeft een ingebouwd paar tools voor het genereren en bekijken van afbeeldingen nodig dat Claude Code niet heeft. We hebben het getest op de ene branch die geen afbeeldingen nodig heeft - het bouwen van een Tiled orthogonale kaart als JSON - en de skill presteerde exact gelijk aan het basismodel: byte-identieke tile-arrays, identieke spawn- en exit-metadata. Het bestand werd geladen; het deel waarvoor de installatie de moeite waard was, draaide niet.

• Generate 2D Sprite (Oordeel: Configuratie): Deze skill heeft hetzelfde probleem. Het is sterk afhankelijk van beeldgeneratiemogelijkheden die met Codex en Grok worden meegeleverd, maar niet met Claude Code. Het kan een sprite sheet plannen, maar het kan de laatste stap, het produceren van de art, niet uitvoeren.

• Ablation Planner (Oordeel: Configuratie): Het hoofdmechanisme van deze skill omvat het overdragen van ontwerpwerk aan een specifieke Codex-tool. Toen we dit in onze Claude Code-omgeving draaiden, was die tool niet beschikbaar. De stap moest handmatig worden uitgevoerd, wat de definitie is van een 'configuratie'-oordeel.

Deze voorbeelden tonen aan dat het SKILL.md-bestand porteerbaar is, maar de logica van de skill mogelijk niet. De instructies zijn slechts tekst; als ze de agent instrueren een tool te gebruiken die er niet is, stopt het proces.

Omgekeerd slaagden 11 van deze op Codex gerichte skills zonder problemen. Skills zoals Better Codex en PinMe Share slaagden voor onze tests op Claude Code. Beide ontlenen hun waarde aan tekst in plaats van aan leveranciersspecifieke tooling. Better Codex is een pure prompt-gebaseerde gedrags-overlay zonder externe bestanden of scripts, en het presteerde toch beter dan het basismodel bij een config-parser-taak, waar de baseline stilzwijgend faalde bij waarden die een gelijkteken bevatten. PinMe Share installeert vanuit één geldig SKILL.md-bestand zonder losse verwijzingen, en zijn voordeel is de exacte kennis van een gewone npm CLI: het produceerde het canonieke upload-commando en de vereiste authenticatiestappen, waar het basismodel het commando raadde en de login oversloeg. Dat is de vorm van een porteerbare skill. Het heeft een tool nodig die u kunt installeren, niet een ingebouwde tool die wordt meegeleverd met de agent van één leverancier.

Belangrijkste Verschillen in een Oogopslag

Een directe vergelijking benadrukt de afwegingen bij het overwegen van codex cli of claude code voor coderen met skills.

Kenmerk	Claude Code	Codex CLI
Skill-pad	~/.claude/skills (persoonlijk), .claude/skills (project)	$HOME/.agents/skills (persoonlijk), .agents/skills (repo), /etc/codex/skills (machine)
Configuratie	settings.json, plus CLAUDE.md voor instructies	~/.codex/config.toml, plus AGENTS.md voor instructies
Sandboxing	Opt-in; omgevingsvariabelen worden overgenomen van de parent shell	Standaard aan in workspace-write, netwerk uit tenzij ingeschakeld
Misvormde SKILL.md	Laadt stilzwijgend niet	(Gedrag niet door ons getest)

De Sandbox-afweging

Het belangrijkste verschil in uitvoeringsomgevingen is het standaard sandboxing-gedrag.

Codex CLI, volgens de documentatie, werkt met een strengere standaard beveiligingshouding. In de workspace-write-modus is netwerktoegang uitgeschakeld, tenzij u dit expliciet inschakelt in config.toml. Schrijfacties naar het bestandssysteem zijn beperkt tot de huidige werkruimte, en het goedkeuringsbeleid van de agent vraagt standaard om bevestiging voordat een actie wordt ondernomen. Dit is een 'default-deny'-model.

Claude Code, zoals gedocumenteerd door Anthropic, hanteert een andere aanpak. Sandboxing is iets wat u aanzet in plaats van uitzet, en zelfs als het aanstaat, erft de shell standaard de omgeving van het bovenliggende proces. Dit betekent dat als u credentials zoals AWS_ACCESS_KEY_ID hebt geëxporteerd in uw terminalsessie, een door Claude Code aangeroepen skill deze potentieel kan lezen. Hierdoor werken skills die met externe services of lokale credentials communiceren direct, en legt het de last van het beheren van die blootstelling bij u.

Geen van beide benaderingen is inherent beter; het is een afweging. Het model van Codex geeft standaard prioriteit aan beveiliging, wat mogelijk meer configuratie vereist om een skill met netwerktoegang werkend te krijgen. Het model van Claude Code geeft prioriteit aan out-of-the-box functionaliteit, wat mogelijk meer van de host-omgeving blootstelt. Een skill die een shell-commando naar curl voor een API uitvoert, werkt mogelijk direct op Claude Code, maar wordt standaard geblokkeerd op Codex CLI.

De Beslisregel: Beoordeel de Omgeving, Niet het Bestand

Dus, Claude Code vs Codex CLI: welke moet u gebruiken voor skills?

Onze data geeft een eerlijk, zij het onvolledig, antwoord. Het SKILL.md-bestandsformaat zelf is niet de beslissende factor. Hetzelfde bestand zal op beide platforms laden. De echte beslissing hangt af van de uitvoeringsomgeving en de afhankelijkheden van de skills die u wilt draaien.

1. Controleer op Tool-afhankelijkheden: Is de skill afhankelijk van ingebouwde, agent-specifieke tools (zoals de beeldgeneratie in Generate 2D Map)? Zo ja, dan is deze niet porteerbaar.
2. Controleer op Universele CLI-afhankelijkheden: Gebruikt de skill alleen alomtegenwoordige command-line tools? Dan heeft deze een grote kans om porteerbaar te zijn, zoals blijkt uit de 11 op Codex gerichte skills die slaagden in onze Claude Code-omgeving.
3. Overweeg uw Sandbox-voorkeur: Geeft u de voorkeur aan een systeem dat standaard is vergrendeld en expliciete toestemmingen vereist (Codex CLI)? Of geeft u de voorkeur aan een systeem dat direct met minder frictie werkt, maar uw volledige omgevingscontext erft (Claude Code)?

We kunnen geen universele winnaar uitroepen omdat we niet op beide platforms hebben getest. De keuze hangt af van uw specifieke behoeften en beveiligingshouding. Wat we met zekerheid kunnen zeggen, is dat het een vergissing is om aan te nemen dat een skill zal werken alleen omdat het SKILL.md-bestand compatibel is. De omgeving is alles.

Gerelateerde lectuur: AGENTS.md vs Claude Skills behandelt de andere helft van de cross-tool-vraag - het instructiebestand dat elke agent leest voordat een skill wordt geladen. En als u kiest tussen terminal-agents op andere gronden dan skills, behandelt Claude Code vs Cursor die afweging.

Bij SkillProof ligt onze waarde in het wegnemen van deze onzekerheid voor het Claude Code-ecosysteem. Wij doen het testen, zodat u dat niet hoeft te doen. Elk 'geslaagd'-oordeel in onze catalogus vertegenwoordigt een skill die we hebben geïnstalleerd en gedraaid op Claude Code, op echt werk. Voor een samengesteld startpunt verzamelen onze rolgebaseerde skill-pakketten elk tien geteste skills voor één functie - ontwikkelaar, security review, marketing, design en nog vier andere - voor $10 per pakket, waarbij het oordeel van elke skill vooraf wordt vermeld.