De Karpathy CLAUDE.md, uitgelegd: het ene bestand achter een Skills Search

Op Google Trends, wereldwijd, over de afgelopen zeven dagen en gelezen op 23 oktober 2026, verschijnt "karpathy skills" als een opkomende zoekopdracht onder de seed "claude skills". Iedereen die die zoekopdracht volgt, komt op dezelfde plek uit: github.com/multica-ai/andrej-karpathy-skills, een repository die op 23 oktober 2026 222.612 sterren op GitHub liet zien. De beschrijving bevat helemaal niet het woord skill. Er staat: "Een enkel CLAUDE.md-bestand om het gedrag van Claude Code te verbeteren, afgeleid van de observaties van Andrej Karpathy over valkuilen bij het coderen met LLM's."

De kloof tussen de zoekopdracht en het object is geen klein technisch detail. Een skill en een CLAUDE.md-bestand zijn verschillende mechanismen die verschillend werk verrichten, en bijna elke bewering die mensen over deze repository doen, hangt er ofwel van af dat men weet welke van de twee het is, ofwel veronderstelt stilzwijgend de verkeerde. De richtlijnen binnenin zitten in één enkel bestand. De repository rond dat bestand bevat ook een plugin-manifest en een map onder skills, en dat is waarschijnlijk waar het woord in de zoekbalk vandaan komt. Het scheiden van de verpakking van de inhoud is hier de eerste nuttige stap.

De cijfers, allemaal van GitHub en gelezen op 23 oktober 2026: 222.612 sterren, 22.321 forks, aangemaakt op 27 januari 2026, voor het laatst gepusht op 20 april 2026, MIT-licentie. Dat laatste paar is het interessantste. De repository heeft in ongeveer zes maanden geen push ontvangen, en toch bleef het aantal sterren maar stijgen.

Het bestand doet het werk; de verpakking licht de zoekterm toe.

Open de repository en de bestandslijst maakt de discrepantie gemakkelijk zichtbaar. Er staat CLAUDE.md in de hoofdmap, en ernaast CURSOR.md, EXAMPLES.md, een map .cursor/rules met dezelfde richtlijnen als een Cursor-projectregel, een map .claude-plugin en een map skills/karpathy-guidelines. De aanbevolen installatieroute volgens de README is de pluginmarktplaats, en deze beschrijft het resultaat als "de skill in al je projecten beschikbaar maken".

Dus de zoekterm is niet zozeer fout als wel onnauwkeurig. Er is een map met skills. Er is een plug-in. Wat er niet is, is een set afzonderlijke skills die elk een andere taak uitvoeren, wat de vorm is die mensen gewoonlijk bedoelen met een skillpack: een map met een SKILL.md en alle ondersteunende bestanden die die capaciteit nodig heeft, aangeroepen voor één taak. Hier bestaat de volledige begeleiding uit één document met vaste instructies, en de plug-in dient om dat document in een project af te leveren.

Of dat onderscheid voor jou van belang is, hangt af van wat je van de zoektocht verwachtte. Als je op zoek was naar een gereedschapskist, dan is dit er geen. Als je een kort regelboek wilde dat verandert hoe een coding agent zich binnen een project gedraagt, dan is dat precies wat het is, en het is de moeite waard om te begrijpen waarom iemand het als een bestand zou schrijven in plaats van als skills.

De klachten waartegen het was geschreven

De in de README vermelde bron is een bericht van Andrej Karpathy op X, dat de README citeert vanwege drie klachten over hoe modellen code schrijven. Ze zijn de moeite waard om volledig te lezen, omdat de vier principes er bijna een-op-een op aansluiten.

Het eerste: modellen "maken verkeerde aannames namens jou en gaan er gewoon mee door zonder te controleren," en "beheren hun verwarring niet, zoeken geen verduidelijking, brengen inconsistenties niet aan het licht, presenteren geen afwegingen, en bieden geen tegenwicht wanneer dat wel zou moeten." Let op wat er wordt beschreven. Dit is geen klacht over verkeerde antwoorden. Het is een klacht over vloeiende foute antwoorden die zonder aarzeling worden gegeven, waarbij de onzekerheid die een vraag had moeten opleveren in plaats daarvan zelfverzekerde code opleverde.

De tweede: ze "houden er echt van om code en API's nodeloos complex te maken, abstracties op te blazen, dode code niet op te ruimen… een opgeblazen constructie van meer dan 1000 regels implementeren waar 100 genoeg zou zijn." Die komt bekend voor bij iedereen die om een functie heeft gevraagd en een framework heeft gekregen.

De derde is subtieler en, voor iedereen die diffs beoordeelt, het duurst: zij "wijzigen/verwijderen nog steeds soms commentaar en code die zij onvoldoende begrijpen als neveneffect, zelfs als dat orthogonaal aan de taak is." Een orthogonale wijziging aan één commentaar is op zichzelf klein. Vermenigvuldigd over een codebase is het hoe een reviewwachtrij volloopt met wijzigingen waar niemand om vroeg, en hoe een commentaar dat een workaround uitlegt verdwijnt voordat iemand leert waarom de workaround bestond.

Vier principes, en de test die elk ervan achterlaat

Het bestand codeert vier principes. Elk gaat vergezeld van een korte set regels, en twee ervan formuleren een test van één regel die je op een diff kunt toepassen zonder iets te installeren. De regels zijn waar het karakter van het bestand blijkt.

Denk na voordat je codeert

De instructie onder de kop is: "Ga niet uit van aannames. Verberg verwarring niet. Maak afwegingen zichtbaar." Daaronder: benoem aannames expliciet en vraag liever dan te gokken; geef meerdere interpretaties wanneer het verzoek ambigu is; spreek je uit wanneer er een eenvoudigere aanpak bestaat; stop wanneer je in de war bent, benoem wat onduidelijk is en vraag om verduidelijking. Dit is rechtstreeks gericht op de eerste klacht. Het mechanisme is niet "wees voorzichtiger" — het is stille keuzes omzetten in zichtbare, zodat een reviewer kan tegenspreken voordat er code bestaat in plaats van erna.

Eenvoud voorop

De regel is: minimale code die het probleem oplost, met niets speculatiefs: geen functies verder dan wat gevraagd is, geen abstracties voor code die maar één keer wordt gebruikt, geen flexibiliteit of configureerbaarheid die niemand heeft gevraagd, geen foutafhandeling voor onmogelijke scenario's, en "als 200 regels 50 kunnen zijn, herschrijf het". De toets is één enkele vraag — zou een senior engineer zeggen dat dit te ingewikkeld is? — en dat is een kwestie van inschatting, en dat wordt openlijk erkend.

Chirurgische wijzigingen

Hier splitst het bestand de instructie in tweeën, wat het nuttigste aspect ervan is. Bij het bewerken van bestaande code: verbeter geen aangrenzende code, commentaar of opmaak; refactor niet wat niet stuk is; houd je aan de bestaande stijl, ook als je het zelf anders zou doen; noem ongerelateerde dode code in plaats van die te verwijderen. Wanneer je eigen wijzigingen verweesde code veroorzaken: verwijder de imports, variabelen en functies die door je wijzigingen ongebruikt zijn geworden, maar laat reeds bestaande dode code met rust, tenzij erom wordt gevraagd. De toets is dat elke gewijzigde regel rechtstreeks terug te voeren is op de aanvraag.

Doelgericht uitvoeren

Definieer succescriteria en blijf itereren totdat ze geverifieerd zijn. De README toont de transformatie als paren. In plaats van "validatie toevoegen", schrijf je tests voor ongeldige inputs en zorg je dat ze slagen. In plaats van "de bug oplossen", schrijf je een test die hem reproduceert en zorg je dat die slaagt. In plaats van "X refactoren", zorg je dat de tests voor en na slagen. Voor werk in meerdere stappen vraagt het om een kort plan waarin elke stap zijn eigen verificatie benoemt. De README citeert Karpathy hier opnieuw: "LLM's zijn uitzonderlijk goed in blijven loopen totdat ze specifieke doelen bereiken… Vertel het niet wat het moet doen, geef het succescriteria en kijk hoe het gaat."

Een bestand, een vaardigheid en een plug-in zijn drie verschillende dingen.

Het is de moeite waard om precies te zijn over het mechanisme, omdat het gedrag in de praktijk verschilt. CLAUDE.md is een projectinstructiebestand: tekst die Claude Code leest als vaste context voor een repository, aanwezig ongeacht of iemand er deze beurt om heeft gevraagd. Een skill is een map met een SKILL.md die beschrijft wanneer de capaciteit moet worden gebruikt; de skill wordt geladen wanneer een taak erom vraagt en niet eerder. Een plugin is een distributiepakket dat via een marktplaats wordt geïnstalleerd en skills, commando's en andere onderdelen kan bevatten. De verschillen gaan over wanneer instructies de context binnenkomen en wie dat bepaalt, niet over kwaliteit.

Een CLAUDE.md is in die zin de botste van de drie. Het staat in dat project altijd aan, het geldt voor elke taak erin, en het neemt bij elke beurt context in beslag, of het werk nu een typfout van één regel herstellen of een migratie is. De README van het bestand erkent die kost in een sectie met de naam Tradeoff Note: de richtlijnen neigen naar voorzichtigheid boven snelheid, en bij triviale taken — eenvoudige typfoutcorrecties, voor de hand liggende one-liners — moet je je oordeel gebruiken. Er staat dat het doel is om kostbare fouten bij niet-triviale werk te verminderen, niet om eenvoudige taken te vertragen.

Dat is een eerlijke weergave van wat een bestand met vaste instructies kan doen. Het kan geen vermogen toevoegen dat het model niet heeft. Het kan alleen het bestaande gedrag van het model waarschijnlijker of minder waarschijnlijk maken. Daarom is het bestand geschreven als beperkingen — doe dit niet, vraag eerst toestemming voordat je dat doet — in plaats van als aanmoediging om beter te zijn.

Wat 222,612 sterren meten

Ze meten aandacht. Dat is geen afwijzing en het is niet niets: een repository die in januari 2026 is aangemaakt en voor het laatst in april is gepusht, bereikte op 23 oktober 2026 222.612 sterren en 22.321 forks, op GitHub, die dag gelezen, wat betekent dat het breed gedeeld werd en geforkt door mensen die hun eigen kopie wilden. Een aantal sterren is een redelijke proxy voor hoeveel mensen iets de moeite van het bookmarken waard vonden.

Het is geen proxy voor effect, en de repository doet niet alsof dat anders is. Wat er nergens in gepubliceerd is: geen enkele benchmark die uitkomsten met en zonder het bestand vergelijkt, geen enkele methodologie om te meten of het werkt, en geen enkele vergelijking met een controlegroep. Er is geen voor-en-na op een echte codebase, geen reviewerstudie, geen incidentcijfer. Een bestand als dit is een elegant geformuleerde hypothese over modelgedrag, en niemand heeft de proef uitgevoerd.

Wat de README in plaats daarvan biedt, is een sectie genaamd ‘How to Know It's Working’, met vier dingen die je zou kunnen waarnemen: minder onnodige wijzigingen in diffs, minder herschrijvingen door overmatige complexiteit, verhelderende vragen die vóór de implementatie komen in plaats van pas nadat er fouten zijn gemaakt, en schone, minimale pull requests. Dat zijn verstandige signalen. Het is ook precies wat je zou opschrijven als je niets had gemeten, en ze zijn zelfgerapporteerd door degene die het bestand toepast. Lees ze als een checklist waaraan je het bestand in je eigen repository kunt toetsen, niet als bewijs dat het die al heeft doorstaan.

Wat je daadwerkelijk typt om het te installeren

De README biedt twee routes. De aanbevolen route werkt binnen Claude Code: voeg de marketplace toe en installeer vervolgens de plugin, waarna de richtlijnen in alle projecten aanwezig zijn in plaats van per repository. De tweede optie is per project: haal de ruwe CLAUDE.md naar een nieuwe repository, of voeg deze toe aan een bestaande. Er is ook een vastgelegde Cursor-projectregel, zodat dezelfde richtlijnen gelden wanneer de map in Cursor wordt geopend — een detail dat aangeeft dat het bestand is geschreven om overdraagbaar te zijn tussen tools die een instructiebestand op projectniveau lezen, en niet gebonden is aan de loader van één leverancier.

Eén ruw randje, het vermelden waard omdat je erop stuit als je de README precies volgt. Het marketplace-commando noemt forrestchang/andrej-karpathy-skills, terwijl de repository-URL bovenaan de pagina multica-ai/andrej-karpathy-skills is. Beide tekenreeksen staan in dezelfde README, gelezen op 23 oktober 2026. Ik zie de mismatch en kan je niet vertellen waarom die bestaat, dus het eerlijke advies is om het andere pad te proberen als het ene faalt, en een van de twee tekenreeksen als verouderd te beschouwen.

Het andere dat op de voorpagina opvalt: de repository wordt onderhouden door multica-ai, en het citaatblok aan het begin van de README promoot Multica, "{{1}}een open-sourceplatform voor het uitvoeren en beheren van codeeragenten met herbruikbare vaardigheden.{{/1}}" Dat is een legitieme bekendmaking, en het is ook een aanwijzing waarom de packaging er zo uitziet. Een project dat geïnteresseerd is in herbruikbare vaardigheden zal zijn eigen richtlijnen waarschijnlijk leveren als iets installeerbaars, en dat is wat de plugin is.

Het gebruiken zonder de aannames ervan over te nemen

De sectie Aanpassing is het deel dat de meeste lezers overslaan. Het bestand is bedoeld om samengevoegd te worden met projectspecifieke instructies in plaats van ze te vervangen, en de voorbeelden die het geeft zijn concreet: gebruik TypeScript strict mode, alle API-eindpunten moeten tests hebben, volg de bestaande patronen voor foutafhandeling in een bepaald bestand. Dat is geen versiering. Het is het verschil tussen een algemeen regelboek en een instructieset die weet waar je code staat.

Er is een praktische reden om samen te voegen in plaats van te stapelen. Als je het bestand ongewijzigd plakt en je project heeft zijn eigen conventies, kunnen de twee sets instructies met elkaar in tegenspraak zijn, en een model dat een tegenstrijdigheid moet verzoenen is precies de verwarring die het eerste principe probeert te elimineren. Je conventies in hetzelfde bestand schrijven, in dezelfde toon, houdt het instructieoppervlak klein genoeg om te auditen.

En dat zou je moeten auditen. Dit is een kort document met gedrags instructies die op elk verzoek in de repository van toepassing zijn. De juiste vraag is niet of 222.612 mensen het mis kunnen hebben — die framing beslecht niets — maar of elke regel overeenkomt met een fout die je daadwerkelijk hebt gezien. Als je diffs nooit terloops herschreven comments hebben bevat, kost de sectie Surgical Changes je onnodig context. Verwijder die. Het bestand valt onder de MIT-licentie en is bedoeld om te worden aangepast.

Eén laag dieper verandert dit niets aan welk model antwoordt. Een CLAUDE.md-bestand bepaalt hoe een verzoek wordt afgehandeld zodra het een model bereikt; het zegt niets over het model dat het ontvangt. Die tweede beslissing is aan wat vóór het model staat. Een manier om dat te regelen is één OpenAI-compatibel endpoint dat meer dan 200 modellen onder één sleutel aanbiedt, met automatische failover tussen providers en de lijstprijzen van providers doorgegeven tegen 0% opslag. Wij hosten modellen; wij maken Claude Code niet, en niets in uw repository is voor ons zichtbaar.

De zoekfunctie zal blijven spreken van skills, omdat dat het woord is dat mensen hebben voor iets dat je installeert om een agent anders te laten werken, en de verpakking rond deze repository gebruikt het ook. Het artefact is een bestand: één document met vaste instructies, geschreven tegen drie specifieke klachten, met vier principes en een reeks tests die je met de hand kunt toepassen. Beoordeel het op of die klachten als jouw repository klinken. Dat is een betere vraag dan het sterrenaantal, dat altijd alleen maar mat hoeveel mensen dezelfde reactie hadden als jij net.