We bouwden een token-discipline skill voor Claude Code

We brengen onze dagen door met het meten van andermans Claude-skills, en er was één patroon dat steeds weer opdook in de telemetrie: de sessies die duur werden, werden niet duur omdat Claude lange antwoorden schreef. Ze werden duur door wat Claude las. Complete bestanden geopend om één functie te vinden. Bestanden opnieuw gelezen direct na een geslaagde edit, "even ter controle". Een JSON-bestand met 16.000 records de context in getrokken alsof het een blogpost was.

Dus bouwden we een skill die precies dat aanpakt, brachten hem uit onder een MIT-licentie, en deden wat we van elke skill in onze catalogus eisen: benchmarken tegen een baseline met gecontroleerde runs, en de cijfers publiceren — ook de cijfers die niet vleiend zijn.

De skill heet token-discipline. Hij is gratis: github.com/Skillproofdev/token-discipline.

Het gat in elke token-skill die we onderzochten

Voordat we een regel schreven, bekeken we acht gepubliceerde token-besparende skills en protocollen — van de output-verbosity-regelset met 5.800 sterren die de niche domineert, tot "noodgeval"-skills die afgaan bij 40% context, tot protocollen die 76–93% besparing claimen zonder mechanisme erachter en zonder telemetrie die we konden terugvinden.

Bijna allemaal delen ze dezelfde blinde vlek: ze optimaliseren de output. Weg met de inleiding, kortere antwoorden, stop met het plan te herhalen. Dat scheelt echt, maar het is de kleinere helft van de rekening. In agent-sessies — Claude Code die echt werk doet in een repository — domineert de input: elk gelezen bestand, elk zoekresultaat, elke tool-output belandt in de context en wordt bij elk volgend verzoek opnieuw meegestuurd.

Drie input-side technieken kwamen in geen van de acht voor als harde regel:

1. Zoek voordat je leest. Lokaliseer eerst met grep/glob, lees daarna alleen het treffende stuk. Nooit een heel bestand openen om iets te vinden.
2. Bundel onafhankelijke tool-aanroepen. Als drie reads niet van elkaar afhangen, horen ze in één bericht. Elke extra beurt betaalt opnieuw voor denk- en toelichtingstokens tussen de aanroepen.
3. Vertrouw op wat je al weet. Na je eigen geslaagde edit hoef je het bestand niet opnieuw te lezen ter controle — de edit-tool geeft luid en duidelijk een fout als het mislukt. Herlezen is voor externe wijzigingen, niet voor je eigen werk.

Die drie vormen de kern van de skill. Daaromheen staan nog zes regels: lees stukken in plaats van hele bestanden, bevraag grote JSON- en logbestanden met python of jq in plaats van ze te openen, vat lange outputs samen en gooi ze daarna weg, delegeer brede verkenningen aan subagents, houd de context cache-vriendelijk (stabiele prefix onaangeroerd laten — Anthropics eigen engineering blog noemt prompt caching de factor met de meeste hefboomwerking op kosten), en ja, ook beknopte output. Negen regels, elk geformuleerd als harde regel met een genoemd alternatief, zodat naleving nooit ten koste gaat van correctheid.

Hoe we het benchmarkten

Zelfde protocol als onze Skill Bench-reeks: zelfde model, zelfde prompt, één variabele. Elke taak draaide twee keer — één Claude Sonnet-agent zonder skill, één die eerst SKILL.md las en de instructie kreeg om die strikt te volgen. De totalen van de skill-agent omvatten de kosten van het lezen van de skill zelf. Het testbed was onze eigen codebase: een Astro-site met zo'n 9.000 regels templates plus een JSON-dataset met 16.682 records — groot genoeg om te laten zien dat ongedisciplineerd lezen echt pijn doet.

Vijf taakparen, gekozen om de hele bandbreedte te dekken, van triviaal tot echt multi-step:

Taak	Baseline	Met skill	Δ
Codebase-Q&A — 8 vragen over verschillende subsystemen	88.419	71.636	−19,0%
Multi-file edit — 4 samenhangende wijzigingen	68.219	54.637	−19,9%
Code trace — one-shot	53.986	52.850	−2,1%
Audit sweep — one-shot	44.691	44.705	+0,0%
Grote-JSON-digest — one-shot	42.726	45.164	+5,7%

Wat de cijfers werkelijk zeggen

Bij echt multi-step werk bespaart de skill zo'n 20%. De Q&A met acht vragen over de codebase komt het dichtst bij een normale werksessie — de auth-flow natrekken, de webhook uitleggen, de sorteerlogica opsporen. De baseline-agent antwoordde correct, maar las onderweg gul en verifieerde overbodig. De gedisciplineerde agent beantwoordde dezelfde vragen, met dezelfde nauwkeurigheid (we controleerden elke file:line-verwijzing van beide), voor 16.783 tokens minder.

De multi-file edit is het interessantere resultaat. Vier samenhangende wijzigingen in vier bestanden. De baseline-agent was klaar en — citaat uit zijn eigen verslag — "geverifieerd door de bewerkte regio's opnieuw te lezen." Alleen die gewoonte is al een vijfde van de rekening. De skill-agent voerde dezelfde vier wijzigingen door, sloeg de ceremoniële herlezingen over, en meldde zich klaar. We vergeleken beide werkbomen: de edits waren in beide gevallen gelijkwaardig en correct. Er ging niets verloren door erop te vertrouwen dat de tool fouten meldt bij falen, want dat is precies wat tools doen.

Bij triviale one-shots maakt het niets uit — en dat publiceren we ook. De JSON-digest-taak kostte met de skill zelfs 5,7% meer. Twee redenen, allebei leerzaam. Ten eerste kost het lezen van de skill zelf ongeveer 1.400 tokens, en een taak die in twee tool-aanroepen klaar is, geeft die overhead nergens de kans om zich terug te verdienen. Ten tweede gedraagt een model van de huidige generatie zich al goed bij makkelijke taken: de baseline-agent wierp één blik op een JSON met 16.682 records en greep meteen naar python in plaats van het bestand te openen. Geen skill nodig. Discipline betaalt zich uit waar ongedisciplineerdheid mogelijk is — lange sessies, veel bestanden, opstapelende context — niet waar er niets te verspillen valt.

Als jouw sessies vooral uit oneliners bestaan, geeft de skill zijn eigen antwoord: een gedistilleerd blok van 60 tokens dat je in CLAUDE.md plakt in plaats van de volledige skill te installeren. Altijd actief, kost ongeveer evenveel als deze zin, en één vermeden volledige bestandsread verdient dat vele malen terug. (We bouwden een rekenmachine voor precies deze always-on-belasting — de rekensom over trigger-omschrijvingen geldt net zo goed voor regelblokken.)

De negen regels, kort

De volledige SKILL.md telt zo'n 1.400 tokens en is in één scherm te lezen; dit is de vorm:

1. Zoek voordat je leest. Eerst grep; lees dan de treffer ±30 regels. Meer dan zo'n 200 regels lezen vraagt om een reden die je in één zin kunt geven.
2. Lees het stuk, niet het bestand. Offset+limit voor alles wat lang is; python/jq voor alles wat gestructureerd is. Een grote JSON is een database, geen document.
3. Bundel onafhankelijke tool-aanroepen. Eén bericht, meerdere aanroepen, telkens wanneer outputs geen input voor elkaar zijn.
4. Vertrouw op wat je al weet. Geen controle-herlezingen na je eigen edits; geen zoekopdrachten opnieuw draaien waarvan de resultaten al in de context staan.
5. Citeer geen code terug. Verwijs naar file:line. Plak alleen wat de mens moet zien om te beslissen.
6. Vat samen, gooi dan weg. Onthoud na een lange tool-output de 2 tot 5 feiten, vraag het log nooit opnieuw op.
7. Delegeer zware verkenning. Brede sweeps gaan naar een subagent; de zware reads sterven daar, niet bij jou.
8. Houd de context cache-vriendelijk. Stabiele prefix onaangeroerd; toevoegen, niet herschrijven; let op de cache-TTL.
9. Outputdiscipline. Eerst het antwoord, geen inleiding, geen diff-essays.

Plus een zelfcontrolemoment (drie vragen voordat je iets groots opnieuw leest) en een expliciete niet-doen-lijst, want een token-skill die een agent noodzakelijke verificatie laat overslaan, bespaart je niets — hij stelt herwerk alleen uit. Als een echte bugzoektocht het hele bestand nodig heeft, zegt de regel: lees het, met de reden erbij.

Waar dit past in het grotere kostenplaatje

Regels zoals deze zijn de variabele helft van je rekening. De vaste helft — de preamble van 30.000 tokens aan MCP-servers, opgeblazen CLAUDE.md-bestanden, en always-on skill-omschrijvingen die letterlijk bij elk verzoek opnieuw wordt meegestuurd — is een ander probleem met andere oplossingen, en meestal de grotere winst voor zware gebruikers. Die audit schreven we uit in Claude Code-tokenkosten verlagen; de twee stukken vullen elkaar aan: fix de vaste kosten eenmalig, en laat token-discipline de variabele kosten de hele sessie vlak houden.

En voor wie zich afvraagt of skills in het algemeen tokens besparen: onze Skill Bench-reeks mat vier populaire skills en ontdekte dat ze dat meestal niet doen — ze kosten extra tokens en kopen daarvoor kwaliteit en discipline. token-discipline werd juist gebouwd om de uitzondering te zijn, en zelfs dan verdient hij zijn geld alleen terug bij multi-step werk. Dat is de eerlijke grens, en die trekken we liever zelf dan dat jij hem op je rekening tegenkomt.

Installeren

git clone https://github.com/Skillproofdev/token-discipline ~/.claude/skills/token-discipline

Herstart Claude Code. De skill gaat af bij "reduce token usage", "work token-efficiently", context-limietklachten en kostenvragen — of pas hem sessiebreed toe via het CLAUDE.md-blok dat erin zit.

FAQ

Vervangt dit de output-verbosity-skills? Nee — hij bevat hun kern (regel 9) en voegt de input-kant toe die zij overslaan. Als je al een terse-output-regelset draait, overlapt token-discipline daarmee op één regel van de negen.

Wordt Claude er slordiger van? De benchmark zegt van niet: de multi-file edit kwam er aan beide kanten gelijkwaardig en correct uit, en de niet-doen-lijst van de skill beschermt expliciet de verificatie die echt nodig is. De regels vervangen ceremoniële reads, niet noodzakelijke.

Waarom is de skill zelf zo kort? Omdat een token-besparende skill die duizenden tokens per sessie kost om te laden zichzelf zou tegenspreken. De SKILL.md is zo'n 1.400 tokens, on demand geladen; het always-on CLAUDE.md-blok is zo'n 60.

Ik zit op een Pro/Max-abonnement, niet op de API. Maakt dit uit? Ja, in limiet-valuta: dezelfde tokens die API-gebruikers factureren, verbruiken jouw gebruikslimieten. Twintig procent minder tokens bij werksessies betekent evenredig meer werk voordat je het plafond raakt.

Was de benchmark cherry-picked? De vijf taken waren ontworpen voordat een van beide varianten draaide, en we publiceerden de twee resultaten waarbij de skill verloor. Ruwe telemetrie — tokenaantallen en tool-call-aantallen per run — staat in de repo README.