/skill-doctor: skills opsporen die context kosten

Je start Claude Code, je hebt nog niets gevraagd, en een deel van de context is al weg. Op de hier gemeten installatie zijn 117 persoonlijke skills geladen, 108 zijn nooit aangeroepen, en hun listing gaat bij elke beurt van het gesprek opnieuw mee.

Wat /skill-doctor precies laat zien

Het commando kwam met Claude Code 2.1.261, uitgebracht op 4 september 2026. De release notes kondigen het in één zin aan: het laat zien welke geladen skills ongebruikt blijven en wat ze aan context kosten, zodat je ze kunt snoeien.

De documentatie bakent het bereik af. Het rapport dekt de skills van je sessie, met uitzondering van de skills die met Claude Code worden meegeleverd en de enterprise-skills. Het signaleert de skills die nooit zijn aangeroepen, geeft aan waar je ze uitschakelt, en somt bovendien de plugins op die je de laatste tijd niet hebt gebruikt. In een interactieve sessie opent het rapport in het tabblad Stats van de /plugin-manager, in niet-interactieve modus, met -p, drukt Claude Code het af als tekst.

Twee voorwaarden waar je rekening mee moet houden voordat je het probeert. Je hebt Claude Code 2.1.252 of nieuwer nodig. En via Remote Control, op telefoon of in de browser, weigert het commando te antwoorden: het geeft Skill usage reports are not available on this connection. terug. Start het in de terminal van de machine die de sessie host.

Waarom kost een nooit aangeroepen skill toch context?

Omdat een skill in drie fasen laadt. De open standaard Agent Skills noemt dit progressive disclosure: bij het opstarten leest de agent alleen de naam en de beschrijving van elke skill. Zodra een taak bij die beschrijving past, leest hij de hoofdtekst van SKILL.md. Pas wanneer hij de bijbehorende bestanden nodig heeft, opent hij die. Het mechanisme wordt uitgelegd in onze gids over het SKILL.md-formaat.

Het eerste niveau wordt echter bij elke gespreksbeurt betaald. De documentatie van Claude Code is daar duidelijk over: elke skill in de listing telt bij elke beurt mee voor de context, of Claude hem nu gebruikt of niet. En die listing heeft een tekenbudget dat gelijk is aan 1% van het contextvenster van het model. Daarboven kort Claude Code de beschrijvingen in om binnen het budget te blijven, met het risico net de trefwoorden te schrappen die de juiste skill activeren.

Te veel skills kost dus tokens, en verslechtert en passant het activeren van de skills die je echt wilde.

Het rapport, over 117 skills

Op een installatie die 117 persoonlijke skills laadt, geeft het commando één regel per skill en een slotzin. De niet-interactieve modus drukt het af als platte tekst, wat het bewaarbaar maakt:

claude -p '/skill-doctor'

Skills loaded this session

  skill                      source        context  7d tokens   uses  last used
  ab-test-setup              userSettings     ~270          -     0×  never
  cold-email                 userSettings     ~230          -     0×  never
  …
  seo-onpage                 userSettings     < 20          -     0×  never
  …
  seo-search-console         userSettings     ~190       1.2m     1×  6 days
  seo-keyword-research       userSettings     ~160      15.2m     1×  3 days
  video                      userSettings     ~210     548.4k     4×  3 days
  wp-article-thumbnails      userSettings     ~190      28.5m     8×  today

  context = this skill's one-line listing in the system prompt, included every turn
  (dash = not in the current listing, costs nothing; full SKILL.md loads only when it runs)
  7d tokens = tokens attributed to the skill over the last 7 days of sessions on this machine

108 skills loaded but never invoked. Each one adds to the system prompt every turn.
Disable in /skills, or remove from .claude/skills.

Vier kolommen dragen de beslissing. context geeft het gewicht van de listingregel, degene die bij elke beurt opnieuw meegaat: hier van onder de 20 tot 360 tokens per skill, ongeveer 8.800 in totaal. 7d tokens telt wat de skill werkelijk verbruikt heeft in zeven dagen, en toont een streepje wanneer hij niets verbruikt heeft. uses en last used zeggen de rest: van de 117 geladen skills zijn er 108 nooit aangeroepen, en hebben er maar vijf iets verbruikt in die week.

Meten zonder het commando

Op een versie ouder dan 2.1.252, of gewoon om de orde van grootte te controleren, is niveau 1 rechtstreeks in de bestanden te meten, want het bestaat uit niets anders dan YAML-frontmatter.

# Gewicht van niveau 1: naam + beschrijving van elke persoonlijke skill
awk 'FNR==1{f=0;p=0}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{printf "%d skills, %d caracteres, ~%d tokens\n", ARGC-1, c, c/4}' \
  ~/.claude/skills/*/SKILL.md
# 117 skills, 45715 caracteres, ~11428 tokens

De schatting “een token per vier tekens” geeft 11.428 tokens waar het rapport er ongeveer 8.800 telt: ze schat te hoog, wat ruim voldoende is om een beslissing te nemen. Dezelfde berekening op ~/.codex/skills levert 7 skills en ongeveer 590 tokens op: op dit punt spelen de twee agents niet in dezelfde competitie, zoals blijkt uit de vergelijking tussen Codex en Claude Code.

Het tweede commando geeft de ranglijst. Die volstaat om te beslissen.

awk 'FNR==1{if(NR>1) print c, d; c=0; f=0; p=0; n=split(FILENAME,t,"/"); d=t[n-1]}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{print c, d}' ~/.claude/skills/*/SKILL.md | sort -rn | head -5
# 1101 elevenlabs-game-music
# 1078 elevenlabs-game-sfx
# 864 directory-submissions
# 855 customer-research
# 831 ab-test-setup

Deze 117 bestanden SKILL.md tellen samen 778.142 tekens, oftewel ongeveer 194.500 tokens, en de listing vertegenwoordigt daarvan maar 6%. Progressive disclosure doet dus zijn werk, en wat dagelijks weegt, blijft het aantal skills. Toch liggen 45.715 tekens in dezelfde orde van grootte als het budget van de listing: zonder /context is niet na te gaan of mijn beschrijvingen al zijn ingekort.

Schrappen wat niet gebruikt wordt

Open /skills, markeer een skill, druk op de spatiebalk om door de statussen te bladeren, en op Escape om op te slaan. Het menu schrijft de instelling skillOverrides zelf naar .claude/settings.local.json. Er zijn vier statussen.

name-only is het juiste compromis voor een skill die je zelf af en toe aanroept: de naam blijft in de listing staan, de beschrijving weegt niet meer mee. off is geschikt voor de skills die je “om te proberen” had geïnstalleerd.

Let op bij plugins: skills die door een plugin worden aangeleverd, vallen niet onder skillOverrides. Je schakelt de plugin uit via /plugin, en start daarna /reload-plugins of herstart de sessie zodat de bijbehorende skills worden ontladen.

Controleren of het schrappen heeft geholpen

De regel Skills van /context geeft de omvang van de listing na toepassing van het budget: dat is precies wat het model ontvangt. Noteer de waarde, schrap, herstart de sessie, noteer de waarde opnieuw. Verandert er niets terwijl je tien skills hebt uitgeschakeld, dan zat je waarschijnlijk al tegen het plafond en kortte Claude Code je beschrijvingen al in. De schrapactie heeft dan alsnog de precisie van de activering verbeterd.

Voor de kosten blijven /cost en /usage de ijkpunten, maar reken op een bescheiden winst: het echte voordeel zit in de context, niet in euro’s. Zoek je besparingen van een andere orde van grootte, kijk dan naar de routering van bestandsleesacties, zoals in de ervaring van Spotify met hooks.

Twee instellingen laten je het budget verruimen in plaats van te schrappen: skillListingBudgetFraction (bijvoorbeeld 0.02 voor 2%) en de omgevingsvariabele SLASH_COMMAND_TOOL_CHAR_BUDGET, die een aantal tekens vastlegt. Verruimen verplaatst het probleem: de context die je wint op de skills, verlies je elders.

Wat je moet onthouden

• Een skill die nooit wordt aangeroepen, kost toch zijn naam en beschrijving bij elke beurt: dat is niveau 1 van progressive disclosure.
• /skill-doctor vereist Claude Code 2.1.252 of nieuwer, en verschijnt in het tabblad Stats van de /plugin-manager.
• Het rapport telt hier 117 geladen skills, 108 nooit aangeroepen, ongeveer 8.800 tokens listing. Twee regels awk op ~/.claude/skills/*/SKILL.md geven dezelfde orde van grootte zonder het commando.
• Je schrapt met /skills en de spatiebalk, plugin-skills schrap je via /plugin, gevolgd door /reload-plugins.
• Je controleert het op de regel Skills van /context, die het daadwerkelijk toegepaste budget weerspiegelt.