Codex Skills: een skill maken voor terugkerende taken

Als je Codex vijf keer per week hetzelfde uitlegt — hoe je een rapport opmaakt, e-mails sorteert of teksten in jouw stijl voorbereidt — kun je die instructies één keer opschrijven in een skill. Daarna kan de agent de skill vinden aan de hand van de beschrijving wanneer die bij de taak past, of kun je de skill expliciet aanroepen. Een skill is een gewone map met een tekstbestand met de naam SKILL.md; voor een eenvoudig gebruiksscenario is geen programmeerwerk nodig.

Hieronder bespreken we hoe een skill is opgebouwd, waar Codex ernaar zoekt, hoe je er stap voor stap een maakt en hoe je op basis van de kosten een model kiest. De opdrachten en prijzen zijn gebaseerd op de officiële documentatie van OpenAI, zoals die op 20 september 2026 beschikbaar was. De installatie van Codex behandelen we hier niet opnieuw; die staat in de handleiding Codex van OpenAI: wat het is en hoe je het installeert en uitvoert.

Praktische informatie over het gebruik van Ailoot vind je in de documentatie.

Wat is een skill in Codex?#

Dit formaat heet Agent Skills. Het is een open standaard die oorspronkelijk door Anthropic is ontwikkeld en gepubliceerd op agentskills.io. Verschillende agents ondersteunen de standaard, waaronder Codex, Claude Code en andere compatibele clients. Een eenvoudige skill die alleen uit tekstopdrachten bestaat, kun je naar een andere client overzetten door de map te kopiëren. Bevat de skill scripts, afhankelijkheden of een bestand agents/openai.yaml, controleer de skill dan na het overzetten: sommige instellingen zijn specifiek voor een bepaalde client.

Deze manier van laden heet progressieve openbaarmaking. De agent gebruikt de naam en beschrijving van een skill om te bepalen wanneer die relevant is. Als een taak overeenkomt met de beschrijving, leest de agent de volledige SKILL.md en volgt die de instructies. Zo kun je tientallen skills in Codex bewaren zonder alle instructies in de context te laden: de eerste lijst neemt niet meer dan 2% van het contextvenster in beslag (of 8.000 tekens als de venstergrootte onbekend is). Als er veel skills zijn, kort Codex eerst de beschrijvingen in. Bij een heel grote verzameling kan Codex sommige skills uit de lijst weglaten en je daarvan op de hoogte stellen.

Je kunt een skill gemakkelijk verwarren met AGENTS.md. Codex leest dit bestand tijdens elke projectsessie. Het bevat vaste regels: de technische stack, conventies en codeerstijl. Een skill wordt op verzoek geladen wanneer een taak erbij past. Zet vaste regels dus in AGENTS.md en een terugkerend proces met stappen in een skill.

Hermes Agent-skills werken op vergelijkbare wijze, maar worden in andere mappen opgeslagen en op een andere manier geïnstalleerd. Ze worden behandeld in een aparte handleiding: Hermes Agent Skills: installatie en aanmaak. Dit artikel gaat alleen over Codex.

Waaruit bestaat een skill?#

Een skillmap heeft deze structuur:

my-skill/
  SKILL.md        - verplicht: metadata en instructies
  scripts/        - optioneel: uitvoerbare code
  references/     - optioneel: documenten die zo nodig worden geladen
  assets/         - optioneel: sjablonen en hulpmiddelen
  agents/
    openai.yaml   - optioneel: weergave en afhankelijkheden

Het bestand SKILL.md begint zelf met een metadatablok tussen drie streepjes, gevolgd door de instructietekst in Markdown:

---
name: weekly-sales-report
description: Stel een wekelijks verkooprapport samen op basis van een CSV-export. Gebruik dit wanneer om een wekelijks verkooprapport of een overzicht per manager wordt gevraagd.
---

1. Lees het exportbestand op het pad dat de gebruiker heeft opgegeven.
2. Groepeer de rijen per manager en bereken het totaal en het aantal deals.
3. Vergelijk met de vorige week als het bestand van de vorige week in de buurt staat. Als het er niet staat, vermeld dat dan rechtstreeks in het rapport.
4. Sla het resultaat op in report.md: een tabel per manager, het totaal en maximaal drie belangrijke veranderingen met cijfers, voor zover de gegevens dat toelaten.

Drie regels uit de officiële aanbevelingen van OpenAI:

• Eén skill, één taak. Kies in plaats van “Doe al mijn marketing” een specifieke taak, zoals “stel een verkooprapport samen op basis van deze export”. Splits een groter proces op in afzonderlijke skills die je achtereenvolgens kunt aanroepen.
• Beschrijf de stappen rechtstreeks en geef expliciet aan wat de invoer en uitvoer zijn: wat je moet gebruiken, wat je moet doen en waar je het resultaat moet neerzetten.
• Begin met tekstopdrachten. Gebruik scripts in scripts/ wanneer een stap elke keer precies hetzelfde moet worden uitgevoerd, bijvoorbeeld om een bestand om te zetten of een extern systeem aan te roepen.

Codex kiest een skill voor een taak op basis van het veld description. Begin de beschrijving daarom met de taak en de woorden die je gewoonlijk gebruikt om die te omschrijven.

Waar zoekt Codex naar skills?#

Het is handig om projectskills samen met de code in git op te slaan, zodat het hele team dezelfde verzameling gebruikt. Persoonlijke skills zijn geschikt voor je eigen processen, zoals je schrijfstijl voor e-mails. Als twee skills op verschillende niveaus dezelfde naam hebben, voegt Codex ze niet samen: ze worden allebei in de lijst getoond, waardoor kiezen lastiger wordt. Gebruik unieke namen.

Ter vergelijking: Claude Code-skills worden opgeslagen in .claude/skills, elk met een eigen SKILL.md, en volgen dezelfde open standaard. Je kunt een eenvoudige skill daarheen overzetten door de map te kopiëren. Voer de skill daarna uit en controleer of die wordt aangeroepen. Zie voor een vergelijking van Claude Code-uitbreidingen Skills, Subagents, MCP of Plugins.

Hoe bepaalt Codex welke skill wordt aangeroepen?#

Expliciet aanroepen is in het begin betrouwbaarder: typ in de Codex CLI $weekly-sales-report om dat specifieke proces te selecteren. Impliciet aanroepen is handiger voor dagelijks werk. Test een skill nadat je die hebt geschreven met gewone formuleringen: vraag Codex om de taak in je eigen woorden uit te voeren, zonder $, en kijk of de skill wordt geselecteerd. Gebeurt dat niet, controleer dan eerst of Codex de skill kan zien in /skills, of de skill in een van de laadlocaties staat en of de skill zelf of de automatische aanroep ervan niet is uitgeschakeld. Is de skill beschikbaar en zijn de instellingen correct, verfijn dan de description: benoem de taak en de gebruikelijke formuleringen van het verzoek.

Je kunt ook instellen dat een skill alleen via een expliciete opdracht beschikbaar is: de parameter allow_implicit_invocation: false in agents/openai.yaml schakelt automatische aanroep uit, terwijl $name blijft werken. Je kunt een skill volledig uitschakelen zonder die te verwijderen via ~/.codex/config.toml:

[[skills.config]]
path = "/full/path/to/the/skill/SKILL.md"
enabled = false

Start Codex opnieuw nadat je config.toml hebt bewerkt. Codex detecteert wijzigingen in skillmappen automatisch, maar start Codex opnieuw als een nieuwe skill niet verschijnt.

Zo maak je stap voor stap je eigen skill#

1. Kies één taak

   Kies een proces dat je regelmatig herhaalt en dat een duidelijk resultaat oplevert: een rapport, tabel, brief of analyse. Heb je zo’n resultaat nog nooit gekregen, voer de taak dan eerst handmatig uit met een agent. Gebruik het resultaat als maatstaf voor de instructies.

2. Maak een skill

   Typ $skill-creator in een Codex-sessie om een skill te maken met de ingebouwde assistent. Die vraagt wat de skill doet, wanneer die moet worden aangeroepen en of er scripts nodig zijn, en stelt vervolgens de basis voor je samen. Wil je een skill handmatig maken, maak dan in het project een map .agents/skills met daarin een submap voor de skill, bijvoorbeeld .agents/skills/weekly-sales-report, en plaats daarin een bestand SKILL.md op basis van het bovenstaande voorbeeld.

3. Schrijf de instructies

   Schrijf de stappen als een genummerde lijst met expliciete invoer en uitvoer. Vereist het proces precisie (gegevens overzetten, namen wijzigen, berekenen), beschrijf dan elke stap in detail. Geef bij creatieve taken (teksten schrijven, argumenten kiezen) de grenzen en criteria voor een goed resultaat aan, maar laat het model ruimte om te werken.

4. Test de aanroep

   Vraag Codex om de taak in je eigen woorden uit te voeren, zonder de naam van de skill te noemen. Selecteert Codex de juiste skill, dan werkte de beschrijving voor die formulering. Test daarna de expliciete aanroep met $name. Wordt de skill niet aangeroepen, controleer dan de map, of de skill in /skills verschijnt en de hierboven beschreven uitschakelinstellingen. Start Codex opnieuw als een nieuwe skill niet in de lijst verschijnt. Werkt de expliciete aanroep en is automatische aanroep toegestaan, maar reageert Codex niet op een verzoek in je eigen woorden, verfijn dan het begin van de description: zet de taak voorop, gevolgd door gebruikelijke manieren om het verzoek te formuleren. Test opnieuw.

5. Verfijn na gebruik

   Bekijk na elke uitvoering het resultaat en vertel de agent wat er in de skill moet veranderen: “Voeg de volgende keer een kolom toe aan de overzichtstabel met het aandeel.” Verfijn een skill voor creatief werk op basis van feedback als de eerste versie niet het gewenste resultaat oplevert.

Kant-en-klare skills van OpenAI en de community installeer je met $skill-installer en de naam van de skill. Als je je eigen skills met anderen wilt delen, verspreid ze dan als plugins — dat is een aparte verpakkingsmethode die je voor persoonlijk gebruik niet nodig hebt.

Hoe controleer je het resultaat van een agent?#

Controles kunnen objectief of subjectief zijn. Objectieve controles zijn meetbaar: “het rapport bevat alle 12 managers uit de export” of “de som in de tabel komt overeen met het CSV-totaal”. Leg deze vast als harde eisen. Subjectieve controles gaan over kwaliteit: “de tekst leest alsof ik hem zelf heb geschreven” of “de conclusies zijn beknopt”. Ook die kun je formaliseren: voeg een voorbeeld van een goede passage toe aan de skill en vraag de agent om het resultaat ermee te vergelijken.

Een nuttige techniek is een beoordelingscyclus: nadat de agent het resultaat heeft voorbereid, loopt die een lijst criteria langs, herstelt die gevonden problemen en laat het resultaat pas daarna aan je zien. Anthropic gebruikt een vergelijkbaar patroon, evaluator-optimizer: één agent voert het werk uit, een afzonderlijke evaluator beoordeelt het en geeft feedback, en het proces wordt herhaald totdat het resultaat is goedgekeurd. Binnen één skill is dit meestal een vereenvoudigde versie: een laatste zelfcontrole aan de hand van een lijst. Houd rekening met de beperking: die is minder sterk dan een onafhankelijke evaluator, omdat de agent die het werk uitvoert zijn eigen fout mogelijk niet opmerkt.

Voorbeeld van een controleblok voor ons rapport:

## Controleer vóór het indienen
- Elke manager uit de export staat in de tabel; niemand is overgeslagen.
- Het totaal komt tot op de laatste cent overeen met de som in de CSV.
- Elke belangrijke verandering wordt onderbouwd met een cijfer; als er geen vergelijkingsgegevens zijn, staat dat rechtstreeks in het rapport.
- Het bestand is opgeslagen als report.md en het pad is met de gebruiker gedeeld.

Welk model kies je voor een skill?#

De kolom helemaal rechts bevat suggesties voor taken waarmee je een eerste controle kunt uitvoeren. Het is geen rangschikking of vergelijkingsresultaat: je kunt pas vaststellen welk model geschikt is voor je skill nadat je het hebt uitgevoerd en het resultaat met de maatstaf hebt vergeleken.

De prijzen in de tabel zijn API-tarieven van de modelpagina’s zoals die op 20 september 2026 golden, geen prijzen van ChatGPT-abonnementen. Bij gebruik van een abonnement valt het verbruik binnen de bijbehorende limieten. Op die datum gold voor Sol een actietarief van $4/$20 tot ten minste 21 november 2026; de standaardprijs is $5/$30. Controleer vóór een grote terugkerende uitvoering de prijspagina: promoties van OpenAI veranderen.

Voer dezelfde skill uit met het eerstvolgende goedkopere model en vergelijk het resultaat met de maatstaf. Blijft de kwaliteit gelijk, probeer dan het volgende, nog goedkopere model. Daalt de kwaliteit, ga dan terug naar het vorige model. Modellen hebben ook inspanningsniveaus: voor Astra lopen die van low tot max en voor de 5.6-familie van none tot max. Test die ook aan de hand van dezelfde maatstaf: kies eerst het model en daarna het inspanningsniveau.

Regelmatig een skill uitvoeren brengt terugkerende kosten met zich mee. De invoerprijs van Astra is 50 keer zo hoog als die van Luna, dus verschillende modellen gebruiken voor dezelfde terugkerende skill kan tot merkbare kostenverschillen leiden. Voor een skill die screenshots en documenten analyseert, kan een zwakker model duurder uitvallen door extra werk achteraf.

Veelgemaakte fouten bij het maken en gebruiken van een skill#

• Een skill “voor alles”. Eén proces, één skill — dat is ook de aanbeveling van OpenAI. Een universele skill van tien pagina’s is moeilijk precies te beschrijven en Codex kiest een skill voor een taak op basis van de beschrijving.
• Een vage beschrijving. “Helpt met rapporten” maakt niet duidelijk voor welk soort rapporten de skill bedoeld is. Zet de taak en gebruikelijke formuleringen van het verzoek vooraan in description.
• Instructies zonder omschreven resultaat. Als je niet aangeeft wat er moet worden gemaakt en waar het moet worden opgeslagen, kan het resultaat per uitvoering verschillen.
• Helemaal geen controles. Zonder een laatste stap met criteria kan het resultaat een onaf concept zijn dat je zelf volledig moet nakijken.
• Standaard het meest krachtige model gebruiken. Controleer eerst of een goedkoper model de taak aankan: voer dezelfde skill uit en vergelijk het resultaat met de maatstaf. Stap alleen over als de kwaliteit gelijk blijft.
• Dezelfde namen in verschillende mappen. Codex voegt skills met dezelfde naam niet samen, waardoor het lastiger wordt de juiste te kiezen.

Aan de slag en een skill overzetten naar Claude Code#

Werk je met meerdere agents, dan kun je een map met alleen tekstopdrachten en een bestand SKILL.md overzetten naar Claude Code. Skills worden daar opgeslagen in .claude/skills en aangeroepen met /name. Controleer een skill na het overzetten als die scripts, afhankelijkheden of agents/openai.yaml bevat. Zie voor een handleiding bij de Claude Code-skillbibliotheek Claude Code Skills: zo bouw je je eigen verzameling; voor een vergelijking van Codex en Claude Code, zie Codex versus Claude Code.

Open Ailoot.