Op 19 augustus las ik een artikel terug dat net door mijn hele redactieketen was gekomen. Vier verschillende passes, allemaal groen, en er stonden nog steeds vier zinnen in die klonken alsof een model ze had bedacht. Een lege opener, een binair contrast, twee onthullingen achter een dubbele punt.
Ik ging ervan uit dat er een pass had gefaald. Dat bleek niet zo. De keten die het artikel had gevolgd noemde die pass helemaal niet. Ik had hem maanden eerder toegevoegd, in mijn globale instructies, en de keten in de skill was blijven staan zoals hij was.
De klus
Ik wilde één skill die een bron-URL omzet in een compleet SparkOne-artikel. Nederlands en Engels, allebei native geschreven, een socials-document erbij, en een planning op alle kanalen. Publiceren mag hij niet, inplannen wel.
Dat zijn tien stappen die in volgorde moeten, met per stap een reden waarom die stap er staat. Een prompt is het allang niet meer.
Mijn echte skill
Een skill is een markdown-bestand met een kop erboven. Dit is de kop van de mijne:
---
description: Van bron-URL naar SparkOne-nieuwsartikel (NL+EN), socials-doc
en een planning op alle kanalen, zonder te publiceren
argument-hint: <URL van tweet, blogpost of aankondiging> [extra context]
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch
---
# SparkOne nieuwsartikel uit bron
Bron: $ARGUMENTS
Werk de stappen hieronder in volgorde af.Daaronder staan de stappen. De belangrijkste regel staat meteen bovenaan, voor stap één, omdat hij voor alle tien geldt:
Publiceer niets, plan wel in. Niets gaat direct live: geen post zonder
scheduledTime, geen date in het verleden, en commit pas na een expliciet
ja van Jeroen.Ontleed
Wat ik hiervan geleerd heb gaat over skills in het algemeen, niet over mijn artikelen.
De beschrijving is de trigger, niet de titel. Op grond van die ene zin besluit het model of het je skill überhaupt openslaat. Schrijf er dus in wat er in de vraag van de gebruiker zou staan, niet wat jij het onderwerp vindt. Mijn eerste versie zei “SparkOne artikel-workflow” en die werd nooit geladen, want zo vraagt niemand iets.
Genummerde stappen zijn de inhoud. Bij een skill die iets moet maken is de volgorde het grootste deel van wat je overdraagt. Ik heb er twee keer een stap van omgedraaid nadat het misging, en beide keren staat er nu bij waarom hij op die plek staat en wat er gebeurde toen hij ergens anders stond. Zonder die reden zet de volgende lezer hem terug, en die volgende lezer ben ik zelf over drie maanden.
Beperk het gereedschap. In allowed-tools staat precies wat de skill mag aanraken. Een skill die niet kan publiceren, publiceert ook niet per ongeluk. Dat is sterker dan de waarschuwing die er in hoofdletters boven staat.
Een skill is een instructie, en instructies worden vergeten. Dit is het deel dat me het meeste gekost heeft. Dezelfde regel over mijn redactieketen stond op vier plekken: in mijn globale instructies, in de skill, in het projectbestand en in een los document. Ze weken van elkaar af, en de enige die ze ooit naast elkaar legde was het model dat er toevallig doorheen liep.
Zet het deel dat je met een regex kunt vangen in een gate. Sinds die dag draait er een script mee in mijn build dat negen patronen controleert. Faalt het, dan is er geen deploy. Een gate wordt niet vergeten en een instructie wel, dus alles wat mechanisch te controleren is hoort daar en niet in een skill.
Wat brak
Het antwoord op de eerste vraag was ongemakkelijk. Er was niets kapot, mijn instructie was verouderd, en dat is de storing die je nooit ziet, want alles meldt netjes dat het gelukt is.
Een week eerder ging er een LinkedIn-post in het Engels uit terwijl dat kanaal bij mij alleen Nederlands is. Dezelfde oorzaak. De regel klopte in mijn globale instructies en de skill zei iets anders. Nu staan de kanalen in één JSON-bestand dat een script live uitleest, en klopt de taal niet, dan stopt het.
En toen ik dit artikel voorbereidde gebeurde het opnieuw, kleiner. De gate draaide, meldde één bevinding, die is opgelost. De pass die over zinsbouw gaat en die geen script kan doen, werd overgeslagen. Ik moest er zelf om vragen. Eén dag nadat ik die gate had gebouwd om te voorkomen dat ik erom moet vragen.
Bij het bouwen van die gate heb ik ook geleerd wat er niet in moet. Ik wilde de onthulling achter een dubbele punt erin hebben, want dat patroon irriteert me het meest. Over mijn hele archief sloeg die regel 801 keer aan, verdeeld over 211 van de 218 artikelen, en vrijwel alles waren gewone labels en opsommingen. Het verschil tussen een label en een onthulling is geen regexvraag. Die blijft dus bij de pass die kan lezen.
Kanttekening
Een skill die in jouw stem schrijft, maakt het moeilijker om te zeggen waar jij ophoudt. Bij mij staat de toon in een apart bestand dat elke skill inleest, en dat bestand is door mij geschreven. De zinnen die eruit komen niet. Ik lees daarom elk artikel hardop voor het weggaat, om te horen of het van mij is.
Er zit ook iets in het bestand zelf. In mijn skills staan voorbeelden uit echt werk, en die voorbeelden gaan over opdrachtgevers en over gesprekken die niet van mij alleen zijn. Eén van mijn skills mag daarom bepaalde projectnamen niet noemen, en dat staat er met zoveel woorden in. Het is aantrekkelijk om je beste voorbeeld erin te zetten, en je beste voorbeeld is meestal het voorbeeld waarvan iemand anders niet weet dat je het deelt.
De gates zijn de kwetsbaarste kant. Mijn skills zijn platte markdown en die neem ik overal mee naartoe. De controles eromheen zijn scripts die aan één repository vastzitten. Stap ik over, dan verhuizen de instructies mee en blijven de gates achter, en dan heb ik precies de situatie terug waar dit artikel over gaat.
Pak ‘t zelf
Dit is het skelet. Vul de haakjes in en zet het bestand in je projectmap.
---
description: [wat de gebruiker zou vragen, in hun woorden, niet in de jouwe]
allowed-tools: [alleen wat nodig is; laat weg wat schade kan doen]
---
# [naam van de klus]
## 1. [eerste stap]
[wat er moet gebeuren, en waarom deze stap vooraan staat]
## 2. [tweede stap]
[idem, met wat er misging toen dit ergens anders stond]
## Wat hier niet in staat
[de regels die elders wonen, met de plek erbij die wint bij verschil]Kleine oefening voor vandaag: pak een instructie die je twee keer hebt opgeschreven en leg de twee versies naast elkaar. Bij mij weken ze alle vier af. Kies daarna welke plek wint, en schrijf in de andere drie dat die plek wint.