/skill-doctor: gli skill che pesano sul contesto di Claude Code

Lanci Claude Code, non hai ancora chiesto nulla, e una parte del contesto se n’è già andata. Sull’installazione misurata qui, 117 skill personali sono caricati, 108 non sono mai stati invocati, e il loro elenco riparte a ogni turno di conversazione.

Cosa mostra esattamente /skill-doctor

Il comando è arrivato con Claude Code 2.1.261, pubblicata il 4 settembre 2026. La nota di versione lo annuncia in una riga: mostra quali skill caricati restano inutilizzati e quanto costano in contesto, così puoi eliminarli.

La documentazione precisa il perimetro. Il rapporto copre gli skill della tua sessione, a eccezione degli skill inclusi in Claude Code e degli skill aziendali. Segnala quelli mai invocati, indica dove disattivarli, e in più elenca i plugin che non hai usato di recente. In sessione interattiva, si apre nella scheda Stats del gestore /plugin, in modalità non interattiva, con -p, Claude Code lo stampa come testo.

Due condizioni da conoscere prima di provarlo. Serve Claude Code 2.1.252 o più recente. E da Remote Control, su telefono o browser, il comando si rifiuta di rispondere: restituisce Skill usage reports are not available on this connection. Eseguilo nel terminale della macchina che ospita la sessione.

Perché uno skill mai invocato costa comunque contesto?

Perché uno skill si carica in tre tempi. Lo standard aperto Agent Skills lo chiama divulgazione progressiva: all’avvio, l’agente legge solo il nome e la descrizione di ogni skill, quando un compito corrisponde a quella descrizione, legge il corpo dello SKILL.md, apre i file accessori solo se ne ha bisogno. Il meccanismo è descritto nella nostra guida al formato SKILL.md.

Il primo livello, invece, si paga a ogni turno di conversazione. La documentazione di Claude Code è esplicita: ogni skill dell’elenco si aggiunge al contesto a ogni turno, che Claude lo usi o no. E quell’elenco dispone di un budget in caratteri pari all’1% della finestra di contesto del modello. Oltre questa soglia, Claude Code accorcia le descrizioni per rientrare nel budget, rischiando di eliminare proprio le parole chiave che attivano lo skill giusto.

Troppi skill costano quindi token, e peggiorano al passaggio l’attivazione di quelli che volevi davvero.

Il rapporto, su 117 skill

Su un’installazione che carica 117 skill personali, il comando stampa una riga per skill e una frase di chiusura. La modalità non interattiva lo stampa in testo semplice, il che permette di conservarlo:

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.

Quattro colonne reggono la decisione. context dà il peso della riga di elenco, quella che riparte a ogni turno: da meno di 20 a 360 token per skill qui, circa 8.800 in tutto. 7d tokens conta ciò che lo skill ha realmente consumato in sette giorni, e mostra un trattino quando non ha consumato nulla. uses e last used dicono il resto: su 117 skill caricati, 108 non sono mai stati invocati, e solo cinque hanno consumato qualcosa nella settimana.

Misurare senza il comando

Su una versione anteriore alla 2.1.252, o semplicemente per riscontrare l’ordine di grandezza, il livello 1 si misura direttamente nei file, dato che è fatto solo di frontmatter YAML.

# Peso del livello 1: nome + descrizione di ogni skill personale
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

La stima «un token ogni quattro caratteri» dà 11.428 token là dove il rapporto ne conta circa 8.800: sovrastima, il che basta ampiamente per decidere. Lo stesso calcolo su ~/.codex/skills dà 7 skill e circa 590 token: su questo punto, i due agenti non giocano nella stessa categoria, come mostra il confronto tra Codex e Claude Code.

Il secondo comando stampa la classifica. Basta quella per decidere.

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

Questi 117 file SKILL.md totalizzano 778.142 caratteri, circa 194.500 token, e l’elenco ne rappresenta solo il 6%. La divulgazione progressiva fa dunque il suo lavoro, e ciò che pesa ogni giorno resta il numero degli skill. Resta che 45.715 caratteri sono nell’ordine di grandezza del budget dell’elenco: impossibile sapere senza /context se le mie descrizioni sono già tagliate.

Tagliare quello che non serve

Apri /skills, seleziona uno skill, premi Spazio per scorrere gli stati, poi Esc per salvare. Il menu scrive da solo l’impostazione skillOverrides in .claude/settings.local.json. Esistono quattro stati.

name-only è il compromesso giusto per uno skill che richiami tu stesso di tanto in tanto: il nome resta nell’elenco, la descrizione non pesa più. off va bene per quelli che avevi installato «per curiosità».

Attenzione al caso dei plugin: gli skill apportati da un plugin non sono interessati da skillOverrides. Bisogna disattivare il plugin da /plugin, poi eseguire /reload-plugins o riavviare la sessione perché i suoi skill vengano scaricati.

Verificare che il taglio sia servito

La riga Skills di /context dà la dimensione dell’elenco dopo l’applicazione del budget: è esattamente ciò che riceve il modello. Rilevala, taglia, riavvia la sessione, rilevala di nuovo. Se non si muove anche se hai disattivato dieci skill, è probabile che tu fossi già al limite e che Claude Code troncasse le tue descrizioni, il taglio avrà comunque guadagnato in precisione di attivazione.

Per il conto, /cost e /usage restano i riferimenti, ma aspettati un guadagno modesto: il vero beneficio si legge in contesto, non in euro. Se cerchi risparmi di un altro ordine di grandezza, è il routing delle letture di file che conviene guardare, come nel resoconto di Spotify sugli hook.

Due impostazioni permettono di ampliare il budget invece di tagliare: skillListingBudgetFraction (per esempio 0.02 per il 2%) e la variabile d’ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET, che fissa un numero di caratteri. Ampliare sposta il problema: il contesto guadagnato sugli skill si perde altrove.

Cosa ricordare

• Uno skill mai invocato costa comunque il suo nome e la sua descrizione a ogni turno: è il livello 1 della divulgazione progressiva.
• /skill-doctor richiede Claude Code 2.1.252 o più recente, e compare nella scheda Stats del gestore /plugin.
• Il rapporto conta qui 117 skill caricati, 108 mai invocati, circa 8.800 token di elenco. Due righe di awk su ~/.claude/skills/*/SKILL.md danno lo stesso ordine di grandezza senza il comando.
• Si taglia con /skills e il tasto Spazio, gli skill di plugin si tagliano da /plugin, poi /reload-plugins.
• Si verifica sulla riga Skills di /context, che riflette il budget realmente applicato.