Skill drift bij Claude Code: waarom je SKILL.md verouderd raakt
Door Mike van BeaumondAI Engineer · company brain & automatiseringgepubliceerd op
9 min leestijd
Quick Take
Skill drift ontstaat niet doordat een SKILL.md kapot gaat, maar doordat niemand hem actief bijhoudt terwijl het project eromheen verandert. Een onderhoudsloop met scoring en een diff-review maakt zichtbaar welke regel een probleem had laten glippen.
Quick Take: Skill drift ontstaat niet doordat een SKILL.md kapot gaat, maar doordat niemand hem actief bijhoudt terwijl het project eromheen verandert. Het bestand blijft functioneren, het wordt alleen steeds minder relevant.
Als je Claude Code skills hebt geschreven, of welke vorm van agent-instructiebestanden dan ook, dan weet je dat ze langzaam afdrijven van de werkelijkheid. De skill die zes maanden geleden code review feilloos uitvoerde, mist nu stilletjes precies de check die er vandaag toe doet. Niet omdat iemand een fout maakte, maar omdat niemand een groeiende stapel Markdown-bestanden controleert onder deadlinedruk.
Dat probleem heet skill drift, en het is een van de stilste faalmodi in agentic development. De skill blijft technisch werken, hij geeft gewoon antwoord, alleen mist hij stap voor stap aansluiting bij hoe het project nu daadwerkelijk werkt. Waarom je de skill over het hoe houdt en de bedrijfskennis apart, lees je in Wat zijn Claude skills?.
Wat is skill drift precies?
Direct antwoord: Skill drift is het geleidelijk verouderen van een instructiebestand terwijl het onderliggende project, proces of beleid wel verandert, zonder dat iemand het bestand bijwerkt.
Je begint met skills voor code review, tests, migraties of API-conventies. In het begin werkt alles. De agent volgt de instructies, de output is bruikbaar, dus je breidt de bibliotheek verder uit.
Dan beweegt het project verder en de skill-bestanden niet. Een skill die een paar maanden geleden onmisbaar was, mist nu een kritieke controle. Dat ontstaat niet door een bewuste keuze, maar simpelweg omdat het handmatig controleren van een groeiende stapel instructiebestanden precies het soort taak is dat niemand oppakt als de deadline dichterbij komt.
Waarom is dit gevaarlijker dan een gewone bug?
Een gewone bug breekt zichtbaar. Skill drift breekt onzichtbaar. De agent blijft antwoorden geven, de output ziet er plausibel uit, en niemand merkt dat er een controle ontbreekt totdat het probleem zich in productie voordoet.
- Een autorisatiecheck die nooit expliciet in de skill stond, wordt nooit afgedwongen, ook niet als het project ondertussen met gevoeligere data werkt.
- Een teststandaard die verouderd is, laat de agent precies de testgevallen overslaan die nu wel relevant zijn.
- Niemand audit een skill-bestand structureel, want het voelt als documentatie onderhouden, en dat staat zelden bovenaan een prioriteitenlijst.
Quick Take: Het gevaar van skill drift zit niet in de fout zelf, maar in de onzichtbaarheid. Een instructie die mist, ziet er niet uit als een fout, hij ziet er gewoon uit als stilte.
Hoe gingen teams er vroeger mee om, en hoe nu?
Vroeger
Iemand merkte een gemiste check pas op na een incident, en moest dan handmatig uitzoeken welke skill-regel ontbrak. Het herstel was reactief en kostte vaak meer tijd dan het oorspronkelijke onderhoud zou hebben gekost.
Nu
Een vaste reviewloop scoort elke skill-run en signaleert automatisch wanneer een instructie achterloopt op de praktijk. Het verschil zit niet in extra tooling, maar in het feit dat de check ingebakken zit in de workflow zelf.
Hoe bouw je een onderhoudsloop voor je skills?
n8n liet onlangs een concrete aanpak zien, gebouwd rond de geheugenlaag van cognee, die het probleem structureel aanpakt in plaats van het te negeren tot het pijn doet. Het idee: draai een skill tegen een echte taak, scoor het resultaat, en als de score onder een drempel zakt, stelt het systeem een scherpere herschrijving voor inclusief redenering en een betrouwbaarheidsscore voordat er iets wordt toegepast.
Wat dit laat werken is geheugen. In plaats van elke skill-run als een geïsoleerd moment te behandelen, koppelt een persistente geheugenlaag eerdere runs en skills aan elkaar, zodat elke verbetering gebaseerd is op echte geschiedenis in plaats van een losse gok.
De stappen van de loop:
- Ingest: de huidige SKILL.md wordt geladen als uitgangspunt voor een review.
- Review: de skill wordt tegen een echte taak gedraaid en krijgt een score per dimensie, zoals dekking en correctheid.
- Drempelcheck: scoort de run onder de ingestelde grens, dan start het verbetertraject. Scoort hij erboven, dan stopt de loop hier.
- Voorstel: het systeem stelt een herschrijving voor, zonder die al toe te passen.
- Diff-review: je ziet exact wat er verandert, inclusief de onderbouwing en een betrouwbaarheidsscore, voordat je iets goedkeurt.
- Toepassen: pas na jouw goedkeuring wordt de wijziging daadwerkelijk in de skill doorgevoerd.
Het belangrijkste ontwerpprincipe hierin: een enkele zwakke run kan nooit stilletjes je instructies herschrijven. Er is altijd een keuringsmoment tussen voorstel en toepassing.
Quick Take: De kracht van zo'n loop zit niet in het automatisch fixen van skills, maar in het zichtbaar maken van precies welke regel een probleem had laten glippen, met een diff die je in seconden kunt beoordelen.
Hoe pas je dit toe zonder een compleet nieuw systeem te bouwen?
In mijn ervaring hoeft dit niet meteen een volledige cognee-implementatie te zijn om waarde te leveren. Het basisprincipe, namelijk periodiek scoren en bewust reviewen, kun je ook simpeler starten binnen je eigen Claude Code-workflow.
Een instructie om dit handmatig te triggeren, voordat een team toe is aan een volledige geautomatiseerde loop:
Beoordeel deze SKILL.md tegen de laatste drie taken waarvoor hij is gebruikt.
Geef per sectie aan:
1. Welke instructie nog steeds klopt
2. Welke instructie ontbreekt gezien recente wijzigingen in het project
3. Een concreet voorstel voor de ontbrekende regel, met onderbouwing
Lever het antwoord als een tabel, niet als lopende tekst.Voor teams die dit structureel willen automatiseren, inclusief scoring, drempelwaarden en een goedkeuringsstap, bouwen we die loop visueel in n8n: van trigger tot diff tot Slack-notificatie, zonder dat je dit met losse scripts hoeft te onderhouden.
Wat lost zo'n onderhoudsloop niet op?
Reality check: een geautomatiseerde reviewloop is geen vervanging voor inhoudelijk eigenaarschap. Een paar dingen die we altijd benoemen voordat een team hieraan begint.
- Het systeem signaleert dat een skill tekortschiet, maar bepaalt niet wie verantwoordelijk is voor het uiteindelijke akkoord. Dat blijft mensenwerk.
- Een voorgestelde herschrijving is zo goed als de taak waartegen hij is getest. Test je tegen een onrepresentatieve taak, dan krijg je een onrepresentatief voorstel.
- Het lost geen organisatorisch probleem op als niemand de tijd krijgt om voorstellen daadwerkelijk te beoordelen. De drempel ligt dan bij prioritering, niet bij techniek.
- Het vervangt geen onboarding. Een team dat niet begrijpt waarom een skill bestaat, leert daar niets van bij het goedkeuren van een diff.
Mijn take: begin met één skill die je team echt vertrouwt, bijvoorbeeld code review, en bouw de gewoonte van periodiek scoren op voordat je de hele bibliotheek aanpakt. Wil je weten waar bij jullie de meeste drift zit? Scoor dan eerst je vijf meest gebruikte skills. Meer over hoe ik werk staat op over Mike.
Bottom line
Bottom line: een SKILL.md is geen document dat je één keer schrijft en daarna vergeet. Het is net zo onderhoudsgevoelig als de code waar het over gaat, alleen mist het de compiler-fouten die je bij gewone code wel zou krijgen.
Geen bullshit, gewoon resultaten: teams die skill drift serieus nemen, bouwen geen perfecte skill in één keer. Ze bouwen een gewoonte om regelmatig te toetsen, een diff te bekijken, en bewust akkoord te geven voordat een wijziging live gaat.
Herkenbaar? Laten we praten.
In 30 minuten kijken we samen met welke afdeling je brein begint. Vrijblijvend.
Veelgestelde vragen
Nee. Elk instructiebestand voor een AI-agent, of het nu een systeemprompt, een SKILL.md of een interne richtlijn is, kan verouderen zodra het onderliggende proces verandert en niemand het bestand actief bijwerkt.
Nee. Begin met de skill die het vaakst wordt gebruikt of het hoogste risico draagt, zoals een security- of autorisatie-gerelateerde check. Breid pas uit zodra die eerste loop bewezen waarde levert.
Ja. Een handmatige periodieke review met Claude Code, zoals het prompt-voorbeeld hierboven, vangt al een groot deel van de drift. Automatisering met scoring en een goedkeuringsgate is vooral waardevol zodra je veel skills of een groot team hebt.
Bij voorkeur degene die de inhoudelijke kennis heeft over waarom de oorspronkelijke regel bestond, niet automatisch de persoon die toevallig de workflow heeft gebouwd.
Dat hangt af van het aantal skills, je bestaande tooling en of je voor een handmatige of geautomatiseerde aanpak kiest. We bespreken dit het liefst concreet in een vrijblijvend gesprek, zodat je geen richtprijs krijgt die niet bij jullie situatie past.