Codex skills maken: geef een terugkerende taak een vaste aanpak

Een Codex skill is een bundel instructies voor een bepaald soort taak. Denk aan wijzigingen samenvatten, een document nalopen of een projectcontrole voorbereiden. Je legt de aanpak vast zodat je niet telkens dezelfde stappen hoeft uit te schrijven.

Mijn advies is om met een eenvoudige tekstprocedure te beginnen. Dan kun je beoordelen of Codex de bedoelde stappen volgt voordat je scripts of externe koppelingen toevoegt. Hieronder maak ik daarvoor een eigen voorbeeld; het is geen verslag van een uitgevoerde test.

Neem een zelfbedacht team dat elke week een wijziging aan een roosterapp oplevert. Bij elke overdracht moeten dezelfde vragen worden beantwoord: wat merkt de gebruiker, welke controle is uitgevoerd en welke onzekerheid blijft staan? Die herhaalde procedure is een goede kandidaat.

Een eenmalige vraag hoeft geen skill te worden. Ook een algemene projectafspraak, zoals welke pakketbeheerder bij de lockfile hoort, is iets anders dan een taakprocedure. Houd zulke afspraken bij de projectinstructies. Zo blijft duidelijk wanneer een instructie geldt en wanneer een specifieke aanpak nodig is.

Schrijf eerst voor jezelf de gewenste uitkomst op. Als je niet kunt zeggen waaraan een goede samenvatting voldoet, maakt een skill de uitkomst niet vanzelf beter. Je legt dan vooral onduidelijkheid vast.

Volgens de actuele OpenAI-documentatie over skills bevat een skill een SKILL.md met name en description. Scripts, naslag en bestanden zijn optioneel. Voor lokale projectskills gebruikt Codex .agents/skills; persoonlijke skills staan in ~/.agents/skills.

Codex leest eerst de beschrijving en laadt de volledige instructies wanneer de skill wordt gebruikt. Je kunt hem in de CLI kiezen via /skills of met $ noemen. De beschrijving helpt ook bij automatische selectie. Controleer na het toevoegen of jouw skill zichtbaar is.

Kies voor een teamprocedure de projectmap, zodat wijzigingen samen met het project beoordeeld kunnen worden. Een persoonlijke schrijfvoorkeur kan in je eigen map blijven. Zet geen wachtwoorden, klantgegevens of persoonlijke sleutels in de skill.

Maak voor dit voorbeeld het bestand .agents/skills/wijziging-uitleggen/SKILL.md. De inhoud hieronder is een eigen redactioneel voorbeeld. De stappen werken met informatie die in de taak beschikbaar is; er staat geen impliciete opdracht in om bestanden te wijzigen of iets te publiceren.

De beschrijving benoemt zowel de bedoelde taak als een grens. Het stappenplan vraagt om bewijs zonder te doen alsof elke controle al is uitgevoerd. Zo krijgt 'test geslaagd' een andere betekenis dan 'deze test zou nuttig zijn'. Dat verschil wil je ook in de uiteindelijke samenvatting terugzien.

Gebruik een oefenwijziging die je zelf kunt begrijpen. Bijvoorbeeld een melding die verschijnt wanneer de einddatum van een reservering vóór de begindatum ligt. Vraag expliciet om de skill en wijs de wijziging aan. Beoordeel daarna of de uitleg het gebruikersgedrag correct beschrijft.

Geef vervolgens een minder nette invoer: er is wel een codewijziging, maar geen testresultaat. Een bruikbare uitkomst zegt dat het bewijs ontbreekt. Als de samenvatting toch meldt dat alles werkt, moet je de instructie aanscherpen. Voeg bijvoorbeeld toe dat alleen aangeleverde of daadwerkelijk waargenomen resultaten als uitgevoerd mogen worden vermeld.

Probeer ook een vraag waarbij de skill niet past, zoals 'verander de kleur van deze knop'. Controleer of de procedure dan onnodig wordt gekozen. Zo beoordeel je niet alleen de tekst van de skill, maar ook de momenten waarop hij van toepassing is.

De procedure beschrijft gewenst gedrag. De technische toegang blijft afhangen van de ingestelde rechten en goedkeuringen. De veiligheidsdocumentatie blijft dus relevant als een skill later commando's gaat gebruiken. Een regel in SKILL.md maakt een geweigerde actie niet toegestaan.

Voor ons voorbeeld is geen externe verbinding nodig. Voeg daarom geen CRM- of publicatiekoppeling toe om een samenvatting te schrijven. Wil je later wel iets versturen, behandel dat als een aparte taak met eigen bevoegdheden en controle.

Het begrenzen van acties komt ook aan bod in onze uitleg over guardrails. Houd een tekstprocedure en de technische handhaving uit elkaar, ook wanneer ze hetzelfde doel dienen.

Een skill kan verouderen als je project verandert. Spreek af wie hem onderhoudt en loop hem na wanneer de werkwijze wijzigt. Een procedure die verwijst naar verdwenen bestanden blijft er op papier overtuigend uitzien. Gebruik daarom concrete voorbeelden om te controleren of de instructies nog passen.

Begin met één verantwoordelijkheid. Als dezelfde skill ook bugs onderzoekt, code schrijft en de release verzorgt, wordt moeilijker te zien welk onderdeel faalt. De MCP-documentatie beschrijft externe gereedschapsverbindingen; die zijn een aparte uitbreiding, geen vereiste voor een tekstskill.

Wil je je opdracht eerst scherper formuleren, lees de gids over prompt engineering. Voor begeleiding bij een eigen ontwikkelwerkwijze kun je de Vibe Coding Training bekijken.