Claude Code voor Teams: Een handleiding voor vaardigheidsstandaardisatie

Zet vijf ontwikkelaars met Claude Code bij elkaar en je krijgt vijf verschillende tools. Eén heeft een CLAUDE.md-bestand met sterke meningen over testen. Eén heeft de skills-directory nog nooit geopend. Eén heeft drie weken geleden een debugging-skill geïnstalleerd via een GitHub-thread en is vergeten dit aan iemand te vertellen. Twee gebruiken de standaardinstellingen, wat betekent dat Claude elke sessie opnieuw hun conventies raadt.

De code die in je PR-wachtrij terechtkomt, weerspiegelt die tweedeling. Sommige diffs bevatten eerst geschreven tests en een schone commit-geschiedenis. Andere bevatten een aannemelijk ogende fix voor een bug die niemand daadwerkelijk heeft gediagnosticeerd. Zelfde model, zelfde repo, zelfde week, vijf verschillende outputkwaliteiten, en de reviewer vangt dit allemaal handmatig op.

Dit is een persoonlijk configuratieprobleem dat zich voordoet als een teamprobleem. Individueel is de setup van elke ontwikkelaar verdedigbaar. Collectief heeft het team geen basis. Niemand was het eens over hoe "goed" eruitziet wanneer Claude de eerste versie maakt, dus niemand kan die lijn vasthouden. Dit artikel gaat over de oplossing: vaardigheden op projectniveau die in de repo leven in plaats van op laptops, en het beheer en de uitrol die ze laten beklijven.

De oplossing is waar de skill leeft, niet wat het doet

Claude Code leest skills van twee plaatsen. Persoonlijke skills bevinden zich in ~/.claude/skills/, gekoppeld aan één machine, onzichtbaar voor teamgenoten, verdwenen zodra die ontwikkelaar van laptop wisselt. Project skills bevinden zich in .claude/skills/ binnen de repository zelf, gecommit naast de code die ze beheren.

Die tweede locatie is de hele truc. Een project skill is een bestand in git: het krijgt een diff, een reviewer, een commit-bericht dat uitlegt waarom debugging een hypothese-eerst-lus moet volgen in plaats van wat die dag goed voelde. Wanneer iemand de skill verbetert, wordt de verbetering bij de volgende pull naar iedereen verzonden, op dezelfde manier als een linter-configuratie-update.

Vergelijk dat met het alternatief waar de meeste teams eerst naar grijpen: een wikipagina getiteld "Hoe we Claude gebruiken" die drie mensen hebben gelezen en niemand afdwingt. Een wikipagina is advies. Een project skill is meer een afhankelijkheid: Claude laadt de beschrijving ervan aan het begin van elke sessie in die repo en past deze automatisch toe wanneer een taak overeenkomt, zonder dat iemand hoeft te onthouden dat het bestaat of het opnieuw hoeft uit te leggen in de prompt.

Het praktische resultaat is dat "de standaard van ons team" geen zin meer is in een onboarding-document, maar iets wordt dat Claude daadwerkelijk identiek doet, of het nu de sessie van de tech lead is of de sessie van de nieuwe medewerker op dag één.

Wat eerst te standaardiseren

Probeer niet je hele engineeringcultuur in één keer in skills te coderen. Drie gebieden dekken het grootste deel van de variatie die we zien tussen ontwikkelaars in hetzelfde team, en elk heeft een geteste, gescoorde skill die je kunt aanwijzen als een concreet voorbeeld van hoe "goed" eruitziet, zelfs als je uiteindelijk je eigen versie schrijft, afgestemd op jouw stack.

Een review-checklist. De kloof tussen een review die echte bugs vindt en een review die voorkeuren voor variabelenamen vindt, is precies wat een goede review-skill dicht. Code Review Checklist scoort 8.4/10 in onze tests: op een PR van 600 regels vond het één echte off-by-one fout en twee dode-codepaden, en produceerde het nul stijlgerelateerde opmerkingen. Als elke reviewer die kwaliteit van de eerste pass krijgt voordat een mens de diff opent, besteden senior engineers reviewtijd aan architectuur in plaats van het vangen van wat een checklist had moeten vangen.

TDD-discipline. Test-Driven Development, uit Jesse Vincents Superpowers-collectie, scoort 9.6/10. We hebben het uitgevoerd over een sessie met drie features en Claude schreef elke keer eerst de falende test, weigerend de cyclus over te slaan, zelfs met een beschikbare snelkoppeling. Het is een pure gedrags-skill, geen scripts of externe tools, wat het het gemakkelijkst maakt om universeel te maken: "write the test first" is niet afhankelijk van je framework.

Een debugging-protocol. Systematic Debugging, ook 9.6/10, vervangt de standaard "try a plausible fix"-lus door reproduceren, hypothesiseren, instrumenteren, verifiëren. In onze test heeft het een race-conditie als hoofdoorzaak vastgesteld die al drie op gokken gebaseerde fixes had overleefd. Dit is de skill die het meest telt in een team, omdat guess-and-check debugging de bron is van de output met de grootste variatie, en een gedeeld protocol die kloof overbrugt.

Drie skills. Niet de twintig die je geneigd zult zijn toe te voegen zodra de eerste drie werken.

Wie keurt een nieuwe skill goed

Zodra skills in de repo leven, moet iemand beslissen wat eraan wordt toegevoegd, en dit is het deel dat teams overslaan totdat het hen bijt. Een skill zijn instructies die Claude automatisch volgt en soms scripts die Claude zal uitvoeren, wat het in dezelfde vertrouwenscategorie plaatst als een nieuw npm-pakket of CI-actie. Niemand zou een ontwikkelaar een willekeurige afhankelijkheid laten toevoegen aan package.json zonder een PR-review. Een skill verdient dezelfde poort.

De mechanica is eenvoudig zodra je je eraan committeert om het zo te behandelen. Een nieuwe skill komt de repo binnen via een normale pull request, met dezelfde branch protection als elke andere wijziging. De reviewer leest de hele SKILL.md, controlerend op instructies die niet gerelateerd zijn aan het opgegeven doel en elke netwerkoproep waarvan de reden niet duidelijk is. Als de skill scripts bundelt, opent iemand deze daadwerkelijk. Dit is dezelfde twee minuten durende audit die we doorlopen in onze beveiligingshandleiding.

Wijs een eigenaar toe, één persoon in plaats van een commissie, meestal degene die de skill heeft voorgesteld of een roulerende tech lead, verantwoordelijk voor het accuraat houden van de skill's beschrijving en het actueel houden van de instructies. Wanneer de trigger-zin van een skill begint te vuren op de verkeerde taken, of de instructies afwijken van de workflow waarvoor het is geschreven, dan repareert of verwijdert die eigenaar het.

Versieer het zoals al het andere in de repo. Als een skill het gedrag significant verandert, is dat een notitie waard in de PR-beschrijving en, voor alles met echt gedragsgewicht, een vermelding in de stand-up zodat mensen weten dat hun sessies vanaf vandaag anders zullen werken.

Onboarding is de echte killer feature

Dit is het deel dat gemakkelijk te onderschatten is wanneer je dit aan een sceptische teamleider presenteert: een nieuwe medewerker kloont de repo op dag één en krijgt dezelfde review-discipline, dezelfde test-eerst-gewoonte en hetzelfde debugging-protocol als de persoon die er al twee jaar werkt. Niet omdat ze een onboarding-document van 40 pagina's nauwkeurig hebben gelezen. Omdat de skills al in .claude/skills/ staan, en Claude ze oppikt zodra de nieuwe medewerker het project opent.

Denk eens na over hoe onboarding er meestal uitziet zonder dit. Een senior engineer legt de testfilosofie van het team uit in een 1:1, de nieuwe medewerker knikt, en drie weken later is de helft ervan verdampt onder deadline-druk, omdat gewoonten die onder druk worden gevormd, standaard terugvallen op wat het snelst is. Met project skills is de discipline geen herinnering die de nieuwe medewerker moet onderhouden. Het is infrastructuur, afgedwongen bij hun eerste PR net zo goed als bij hun honderdste.

Het dicht ook de kloof tussen senioriteitsniveaus. De sessie van een junior ontwikkelaar die dezelfde debugging-skill uitvoert als die van een staff engineer, produceert output op een veel dichter kwaliteitsniveau dan de twee onondersteund zouden bereiken, omdat veel van wat een goede debug-sessie scheidt van een slechte, procedure is, niet ervaring.

Als je de rest van de Claude Code-laag nog niet hebt ingesteld, is dat de moeite waard om dit ervoor of ernaast te doen. Onze setup-handleiding behandelt de CLAUDE.md- en permissielagen waarop project skills rusten.

Hoe te zien of het echt werkt

Weersta de drang om hiervoor een dashboard uit te vinden. Het signaal dat je wilt, stroomt al door de tools die je hebt.

Let op het volume van PR-reviewcommentaren en, belangrijker nog, het type commentaar. Als reviewers minder "heb je dit getest" en "dit behandelt de null-case niet" commentaren achterlaten en meer commentaren over daadwerkelijke ontwerpafwegingen, dan doen de review- en TDD-skills hun werk. Als het aantal commentaren daalt, maar de overgebleven commentaren nog steeds correctheidsbugs vangen die de skill had moeten vangen, dan is de skill nog niet goed afgestemd, niet het team.

Let op de regressiesnelheid. Een debugging-skill die de hypothese-verificatie-discipline afdwingt, zou moeten leiden tot minder "gefixte" bugs die een week later weer opduiken, aangezien gok-en-controle-fixes precies het soort zijn dat terugkomt. Dit is een langzamer signaal, meestal zichtbaar over een maand of twee in plaats van een sprint, maar het is het belangrijkst voor een team dat eerder is gebrand door "gefixte" bugs.

Let op de time-to-first-approval op PR's, waarbij één datapunt als een hint wordt behandeld en een aanhoudende verschuiving over meerdere sprints als een echt signaal. En praat met mensen: of ontwikkelaars vinden dat Claude's output consistenter is geworden, of een nieuwe medewerker zegt dat de codebase sneller leesbaar aanvoelde dan bij hun vorige baan, is in de eerste maand meer waard dan al het bovenstaande.

Een uitrol van vier weken voor een team van tien personen

Week 1. Kies één repo, niet allemaal, en één skill; de review-checklist is meestal het gemakkelijkst te verkopen omdat reviewers het voordeel onmiddellijk zien. Voeg het toe aan .claude/skills/ via een normale PR. Vraag twee of drie vrijwilligers om het te gebruiken bij hun volgende paar reviews en rapporteer terug in een korte thread, geen vergadering.

Week 2. Voeg de TDD-skill toe aan dezelfde repo. Dit is degene die de meeste weerstand oproept, aangezien het verandert hoe mensen code schrijven in plaats van hoe ze het reviewen. Verwacht frictie en behandel het als data. Houd de debugging-skill voorlopig buiten beschouwing en verzamel specifieke klachten ("het vuurt op taken waar ik het niet wil") om de beschrijving van de skill te corrigeren voordat je probeert het gedrag van mensen te corrigeren.

Week 3. Voeg de debugging-skill toe. Inmiddels heeft het team een gevoel voor hoe project skills zich gedragen, dus deze toevoeging zou sneller moeten gaan. Doe een korte retro over de twee weken aan data: veranderen reviewcommentaren, vermijdt iemand stilletjes de skills, waarom. Pas trigger-beschrijvingen aan als een skill te vaak of niet genoeg vuurt.

Week 4. Rol dezelfde drie skills uit naar de rest van de repo's van het team. Schrijf een korte notitie in de README van elke repo die aangeeft wat er in .claude/skills/ staat en waarom, zodat de volgende nieuwe medewerker het niet hoeft te vragen. Stel het goedkeuringsproces uit de bovenstaande sectie in als een vaste regel, aangezien de echte test van governance is wat er gebeurt met de vierde skill die iemand voorstelt, niet de eerste drie.

Vier weken, drie skills, één repo opgeschaald naar de rest van de organisatie. Weersta het comprimeren hiervan; de frictie in week 2 is informatie die je wilt voordat je vijf skills over tien repo's draait.

De plugin-optie voor multi-repo organisaties

Project skills lossen standaardisatie binnen een repo op, maar de meeste engineering-organisaties zijn geen één repo. Als je tien ontwikkelaars werken aan vijftien services, dan wordt het handmatig kopiëren van .claude/skills/ naar elk van hen en ze handmatig synchroon houden een eigen onderhoudstaak, het soort dat stilletjes stopt na het tweede kwartaal.

Claude Code-plugins lossen die laag op. Een plugin bundelt een set skills, plus commands en andere configuratie, in één installeerbare eenheid die niet gekoppeld is aan de git-geschiedenis van één enkele repo. In plaats van vijftien kopieën van dezelfde drie skills die onafhankelijk afdrijven, onderhoudt de organisatie één plugin, eenmalig geversioneerd, en elke repo installeert hiervan. Een update van de debugging-skill verspreidt zich dan overal waar de plugin is geïnstalleerd, in plaats van vijftien afzonderlijke PR's te vereisen.

Dit is een stap omhoog in operationele complexiteit, en het is niet de moeite waard om te nemen totdat je de pijn hebt gevoeld van het synchroon houden van meerdere repo's. Voor een team van tien personen op één of twee repo's is de project-skills-aanpak in dit artikel het juiste eindpunt. Voor een organisatie die dezelfde standaarden hanteert over veel codebases, behandelt onze plugins-handleiding de verpakkings- en distributiemechanismen.

De faalmodus: twintig skills verplichten op dag één

De meest voorkomende manier waarop dit misgaat is niet technisch, het is een uitrolfout. Een tech lead leest over project skills, raakt enthousiast en commit er twintig in één middag: review, TDD, debugging, plus een dozijn meer voor logging-conventies, commit message-formaat, API-ontwerp, toegankelijkheid, en al het andere dat redelijk leek om 16.00 uur op een donderdag.

Twee dingen gaan mis. Ten eerste beginnen overlappende beschrijvingen te vuren op de verkeerde taken, of op elkaar, omdat niemand heeft gecontroleerd of de trigger-zin van skill drie botst met die van skill elf; deze conflicten zijn een van de meest voorkomende defecten die we zien bij het testen, en ze worden erger naarmate het aantal toeneemt. Ten tweede, en schadelijker, ontwikkelt het team nooit vertrouwen in de skills, omdat een week onder twintig nieuwe regels aanvoelt als een compliance-oefening, en mensen beginnen om Claude heen te werken in plaats van ermee.

Drie skills, over een maand aangenomen, met echte feedback die elk vormgeeft voordat de volgende arriveert, bouwt vertrouwen op dat twintig skills die tegelijk worden gedropt nooit zullen doen. Als je team nog steeds beslist waar te beginnen, zijn onze coding skills rankings gerangschikt op geteste score, wat een redelijk filter is voor het kiezen van de volgende na je eerste drie.

Veelgestelde vragen

Werken project-level skills hetzelfde als persoonlijke skills?

Ja, het formaat is identiek. Het enige verschil is de locatie: .claude/skills/ in de repo in plaats van ~/.claude/skills/ op een laptop. Claude Code laadt beide op dezelfde manier. Als een skill op beide plaatsen met dezelfde naam bestaat, heeft de projectversie over het algemeen voorrang voor die repo, wat precies het gedrag is dat je wilt voor een teamstandaard.

Zal dit Claude vertragen voor iedereen in het team?

Nauwelijks. Elke geïnstalleerde skill kost ongeveer 100 tokens aan altijd geladen metadata. Drie project skills binnen een team voegen minder permanente context toe dan een enkele verbonden MCP-server doorgaans doet. De echte kosten van dit verkeerd aanpakken zijn niet snelheid, het is trigger-verwarring door overlappende beschrijvingen, daarom voegt het bovenstaande uitrolplan skills één voor één toe.

Wat als een ontwikkelaar het niet eens is met de TDD- of debugging-standaard van het team?

Dat is een gesprek dat je moet voeren voordat de skill wordt samengevoegd, in de PR-review, dezelfde plek waar je het zou hebben over een linter-regel. Zodra het in de repo staat, geldt het voor iedereen, maar "iedereen" zou moeten betekenen dat iedereen de kans heeft gehad om mee te wegen tijdens de review, niet dat één persoon unilateraal heeft besloten en naar main heeft gepusht.

Moeten we skills verplichten of optioneel laten?

Project skills laden automatisch voor iedereen die de repo heeft, dus er is geen aparte "vereis"-stap, ze zijn gewoon onderdeel van de codebase. Wat je optioneel kunt maken is bijdrage: niet elke ontwikkelaar hoeft nieuwe skills voor te stellen, maar de sessie van elke ontwikkelaar draait de skills die zijn samengevoegd. Behandel de merge-beslissing als de poort.

Hoe verschilt dit van het simpelweg schrijven van een lange CLAUDE.md?

Laadgedrag. CLAUDE.md laadt in elke sessie, ongeacht wat de ontwikkelaar die dag doet, wat het geschikt maakt voor feiten die altijd van toepassing zijn: build commands, architectuur, naamgevingsconventies. Een skill laadt alleen wanneer een taak overeenkomt met de beschrijving, wat het geschikt maakt voor een procedure die je soms nodig hebt: hoe het team debugt, hoe het team reviewt. Als je CLAUDE.md een lange sectie heeft die beschrijft hoe tests te schrijven of een review te structureren, dan wil die sectie liever een skill worden.