AI coding agent skills: zo maak je herhaalbaar werk reviewbaar

Veel teams geven een coding agent steeds opnieuw dezelfde uitleg: welke bestanden je leest, welke checks je draait, wat je niet mag aanpassen en wanneer je moet stoppen. Die kennis verdwijnt daarna in een chatgeschiedenis. AI coding agent skills maken er een klein, herbruikbaar workflowpakket van.

Een goede skill is geen enorme prompt en ook geen garantie dat de agent gelijk heeft. Het is een versiebeheerbare combinatie van instructies, bronnen en eventueel scripts, met een duidelijke grens voor input, output en review. In dit artikel bouw je zo’n skill voor een fictieve Azure-agentfeature. De demo is neutraal; er worden geen persoonlijke klantresultaten geclaimd.

Wat is een AI coding agent skill?

De Agent Skills-specificatie beschrijft een herkenbare vorm voor skills met een SKILL.md-bestand en metadata. De officiële OpenAI-documentatie over skills beschrijft skills als pakketten van instructies, resources en optionele scripts voor taakgerichte workflows. Plugins zijn vervolgens een distributielaag wanneer je zo’n skill met anderen wilt delen.

De praktische betekenis is eenvoudig:

Let op de actualiteit van voorbeelden. De oude openai/skills-repository vermeldt inmiddels zelf dat de repository deprecated is en verwijst voor actuele Codex-skill- en pluginvoorbeelden naar de huidige documentatie en plugins. Gebruik dus niet blind een oud installatiecommando uit een blogpost.

Stap 1: kies één herhaalbare workflow

Begin met een taak die vaak terugkomt en een duidelijk eindpunt heeft. “Help met Azure” is te breed. “Controleer een wijziging aan een Azure Functions-agentfeature op bronnen, rechten, tests en deploymentimpact” is al beter.

Schrijf eerst het contract:

Input:
- een repository of wijzigingsvoorstel;
- de naam van de Azure-feature;
- de gewenste omgeving: lokaal, test of productie.

Output:
- een kort wijzigingsplan;
- primaire bronnen met datum;
- gewijzigde bestanden;
- testuitvoer;
- open risico's en een reviewvraag.

Nooit automatisch:
- secrets uitlezen of tonen;
- productiegegevens wijzigen;
- deployment uitvoeren;
- externe berichten versturen.

Een skill moet kunnen zeggen dat ze niet kan doorgaan. Ontbreekt de featureversie, bron of testomgeving? Stop dan met een gerichte vraag. Een agent die ontbrekende informatie zelf invult, maakt de workflow misschien vlotter maar niet betrouwbaarder.

Stap 2: houd de skill klein met progressive disclosure

Een bruikbare structuur kan er zo uitzien:

azure-agent-review/
├── SKILL.md
├── references/
│   ├── source-policy.md
│   └── review-checklist.md
├── scripts/
│   ├── check-no-secrets.ps1
│   └── check-allowed-files.ps1
└── examples/
    └── neutral-change-plan.md

Zet in SKILL.md alleen de route die bijna iedere uitvoering nodig heeft. Stop uitgebreide uitleg en versiegevoelige links in references. Gebruik scripts voor controles die exact hetzelfde moeten werken. De Azure Agent Skills-repository van Microsoft beschrijft dit als progressive disclosure: eerst metadata ontdekken, daarna instructies laden en pas daarna aanvullende resources gebruiken.

Een SKILL.md kan bijvoorbeeld beginnen met:

---
name: azure-agent-review
description: Review een Azure-agentwijziging op bronnen, rechten, tests en deploymentrisico. Gebruik vóór een merge- of releasebesluit.
---

Daarna beschrijf je:

1. welke input eerst moet worden gecontroleerd;
2. welke bestanden en bronnen gelezen mogen worden;
3. welke tools en scripts zijn toegestaan;
4. hoe de output eruitziet;
5. welke fouten tot stoppen leiden;
6. wanneer een mens moet reviewen.

Maak de beschrijving vindbaar, maar niet misleidend. Noem de taak, de context en het moment waarop de skill nodig is. Zet geen claim als “garandeert veilige Azure-code” in de metadata.

Stap 3: maak bronnen en scripts controleerbaar

Een skill met alleen algemene tekst is snel achterhaald. Verwijs naar primaire documentatie en noteer welke versie of datum relevant is.

## Bronbeleid

1. Gebruik eerst de actuele officiële documentatie van de gebruikte Azure-service.
2. Noteer URL, titel, geraadpleegde datum en de claim die de bron ondersteunt.
3. Gebruik communityvoorbeelden alleen als implementatie-inspiratie, niet als bewijs van productgedrag.
4. Meld wanneer een bron niet toegankelijk of versiegevoelig is.

Scripts mogen deterministische checks uitvoeren, bijvoorbeeld:

$allowed = @(
  'src\agent\review.ts',
  'tests\agent\review.test.ts'
)

$changed = git diff --name-only
$unexpected = $changed | Where-Object { $_ -notin $allowed }

if ($unexpected) {
  Write-Output 'BLOCK: onverwachte bestanden in de diff'
  $unexpected
  exit 1
}

Write-Output 'PASS: diff blijft binnen de afgesproken scope'

Dit script is een illustratie. In productie moet je ook rekening houden met quoting, submodules, generated files en de manier waarop de runner git uitvoert. Een script dat “PASS” zegt zonder zijn input te controleren, maakt een workflow juist minder betrouwbaar.

Laat een skill niet automatisch alle gevonden bronnen in de prompt stoppen. Dat vergroot de context en maakt het moeilijker om te zien welke bron welke beslissing ondersteunde. Maak een klein bronnenoverzicht met claim, URL, datum en beperking.

Stap 4: test de skill als een klein product

Een skill is pas herhaalbaar wanneer je haar niet alleen op de ideale vraag test. Maak een testmatrix:

Test ook de tekst van de output. Kan een reviewer in één minuut zien wat is gewijzigd, wat is getest, welke bron is gebruikt en welke vraag nog openstaat? Dan is de skill reviewbaar. Kan dat niet, dan ontbreekt er meestal een outputcontract.

Gebruik een aparte schone testmap wanneer je wilt weten of de skill alle aannames zelf meeneemt. Een skill die alleen werkt omdat de maker toevallig extra context in zijn persoonlijke omgeving heeft, is nog niet klaar om te delen.

Stap 5: versioneer en onderhoud de skill

Zet de skill in dezelfde reviewcultuur als code:

• verander de versie wanneer instructies of scripts gedrag wijzigen;
• voeg een changelogregel toe met de reden van de wijziging;
• test minstens één positieve en één negatieve case;
• review links naar versiegevoelige documentatie;
• controleer licenties en attributie van meegeleverde voorbeelden;
• beperk secrets, tokens en klantdata tot de omgeving die ze werkelijk nodig heeft.

De MicrosoftDocs Agent-Skills-repository laat zien dat dezelfde skillvorm in meerdere coding assistants kan worden gebruikt, maar compatibiliteit is geen automatische garantie. Paden, pluginmanifesten, toolnamen en permissies verschillen per product. Documenteer daarom de ondersteunde runtime en maak een kleine smoke test per doelomgeving.

Voor community-inspiratie is Matt Pococks skills-repository interessant: het laat zien hoe engineers skills als herbruikbare workflowcollectie organiseren. Behandel zo’n repository als voorbeeld, niet als officiële kwaliteitsstempel voor jouw team.

Wat een skill niet oplost

Een skill kan onduidelijke architectuurkeuzes niet magisch beslissen. Hij kan ook niet voorkomen dat de onderliggende documentatie verandert, dat een model een instructie verkeerd interpreteert of dat een script een fout bevat.

Let vooral op deze grenzen:

1. Een skill is een instructielaag, geen autorisatiesysteem. Rechten moeten ook buiten de prompt worden afgedwongen.
2. Een bronverwijzing is geen bewijs dat jouw deployment correct is. Test de concrete versie en omgeving.
3. Een groen script controleert alleen wat het script controleert.
4. Een gedeelde skill kan onbedoeld interne werkwijzen of gevoelige context lekken.
5. Een te brede skill wordt moeilijk vindbaar en laadt te veel context.

Gebruik voor risicovolle acties een dubbele grens: de agent moet de actie kunnen voorbereiden, maar een afzonderlijke menselijke of platformmatige gate moet de uitvoering toestaan.

Samenvatting

AI coding agent skills maken herhaalbaar werk niet automatisch goed; ze maken het zichtbaar en overdraagbaar. Bouw ze zo:

1. kies één concrete workflow;
2. schrijf input, output en verboden acties;
3. houd SKILL.md klein en verwijs gericht naar resources;
4. gebruik scripts voor deterministische controles;
5. test ook ontbrekende input, secrets en falende checks;
6. versioneer de skill en review haar als code;
7. laat rechten en productieacties buiten de prompt afdwingen.

Zo verander je een handige persoonlijke prompt in teamkennis die een reviewer kan volgen. Maak je coding-agentworkflow reviewbaar met een AI engineer. Bekijk ook de bredere uitleg over coding agents en AI-agenten in productie.