Claude Code skills: ridurre il costo del contesto

Ora è possibile capire quali Claude Code skills consumano contesto senza produrre lavoro utile, per poi eliminare quello spreco senza rinunciare alle istruzioni necessarie nei workflow reali. Il nuovo report /skill-doctor trasforma la manutenzione delle skill: non più tentativi alla cieca, ma un processo misurabile, reversibile e ripetibile.

In breve: esegui /skill-doctor, valuta ogni skill inutilizzata in base alle conseguenze che avrebbe la sua assenza, applica la modifica di visibilità meno invasiva e verifica il risultato in una nuova sessione. Non partire cancellando cartelle. Una skill rimasta silenziosa per una settimana potrebbe essere proprio quella che rende sicuro un deployment o la gestione di un incidente.

Claude Code 2.1.261, pubblicato il 4 settembre 2026, ha introdotto /skill-doctor, che mostra quali skill caricate non vengono usate e quanto contesto costa ciascuna. È un dato importante: il nome e, di norma, la descrizione di ogni skill elencata entrano in ogni turno, anche quando Claude non richiama mai le istruzioni complete.

Claude Code skills: che cosa significa davvero costo del contesto

Il contesto delle skill presenta due voci di costo. Confonderle porta a ottimizzazioni sbagliate.

La prima è il costo dell'elenco. Prima ancora che venga digitato un prompt, Claude riceve nomi e descrizioni delle skill disponibili, così da scegliere quella adatta alla richiesta. Per impostazione predefinita, Anthropic limita questo elenco all'1% della finestra di contesto del modello; inoltre, il testo complessivo di description e when_to_use di ogni skill non può superare 1,536 caratteri per impostazione predefinita.

La seconda è il costo di invocazione. Il contenuto integrale di SKILL.md viene caricato soltanto quando la skill viene richiamata dall'utente o da Claude. Da quel momento resta nella conversazione anche nei turni successivi. Dopo la compattazione, Claude Code può reinserire fino a 5,000 token per ogni skill invocata, entro un budget complessivo di 25,000 token per tutte le skill reinserite.

L'elenco è come la vetrina di un negozio; il corpo della skill è la merce portata al banco. Ogni insegna occupa spazio sulla strada. La merce ne richiede molto di più, ma solo quando qualcuno la domanda.

Questa distinzione determina l'intervento corretto. Una skill inutilizzata con una descrizione lunga genera un costo ricorrente nell'elenco. Una skill richiamata spesso e dotata di un corpo enorme crea invece un costo persistente per la sessione. /skill-doctor è particolarmente efficace sul primo problema; una buona architettura delle skill risolve il secondo.

Il conto si paga a ogni turno, non una volta sola

Una skill inattiva non è un costo di configurazione una tantum. Il testo che la descrive viene riproposto mentre la conversazione procede. Una stima operativa utile è:

Contesto evitabile al giorno = token inutilizzati nell'elenco per turno × turni Claude al giorno

Per esempio, se il report rileva 2,000 token di contesto inutilizzato nell'elenco e il lavoro genera 40 turni del modello, nell'arco della giornata vengono presentati 80,000 token in input. È un esempio, non un benchmark. Il prompt caching può ridurre il costo fatturato per il testo ripetuto, ma non fa sparire quel contesto.

Per chi usa API e cloud provider, quei token aggiuntivi incidono sulla fattura. Per chi ha un abbonamento, consumano la capacità del piano e riducono lo spazio operativo disponibile prima della compattazione. Secondo Anthropic, nelle implementazioni enterprise di Claude Code la media è di circa $13 per sviluppatore per giorno attivo e da $150 a $250 per sviluppatore al mese. Lo spreco legato alle skill è solo una parte della spesa, ma ora è una delle poche che si possono isolare per nome.

Non è in gioco soltanto il budget del modello, ma anche la produttività degli sviluppatori. Quando l'elenco è troppo affollato, Claude Code può omettere le descrizioni delle skill meno usate. Si risparmia spazio, ma diventa anche più difficile per Claude selezionare automaticamente la skill corretta.

Il workflow per ridurre il contesto e poter tornare indietro

Il metodo più sicuro si articola in sette passaggi.

1. Parti da una sessione terminale aggiornata

Aggiorna Claude Code alla versione 2.1.261 o successiva e controlla quella installata con claude --version. La documentazione di Anthropic indica che /skill-doctor richiede almeno la versione 2.1.252, mentre la 2.1.261 è quella in cui il comando è stato annunciato nel changelog.

Esegui /skill-doctor nel terminale della macchina su cui gira la sessione. In una sessione interattiva, il report si apre nella scheda Stats del gestore /plugin. In modalità non interattiva con -p, viene stampato come testo e può quindi essere salvato per un audit locale. Remote Control non è in grado di restituire il report.

2. Registra il punto di partenza

Prima di modificare qualsiasi cosa, salva tre elementi: il costo totale dell'elenco delle skill, le voci inutilizzate più pesanti e le skill o i plugin su cui intendi intervenire. Esegui anche /context per vedere la riga Skills dopo l'applicazione del budget e /doctor per individuare le voci che pesano di più nell'elenco.

Non convertire automaticamente il numero di token in denaro, a meno di conoscere modello, comportamento della cache e tariffe contrattuali. Usa i token come unità stabile e calcola separatamente il costo economico.

3. Classifica le skill in base al costo di un errore

Dividi ogni candidata in una di queste tre categorie:

È qui che il report richiede giudizio. “Mai invocata” misura la frequenza, non il valore. Un estintore può restare inutilizzato ed essere comunque indispensabile.

4. Applica il controllo meno invasivo

Per le skill locali, personali, di progetto o sincronizzate, il menu /skills può scrivere una modifica reversibile a skillOverrides nel file .claude/settings.local.json.

• Usa name-only quando Claude deve sapere che la skill esiste, ma non ha bisogno della descrizione completa nell'elenco.
• Usa user-invocable-only quando vuoi mantenere disponibile /skill-name senza consentire la selezione automatica.
• Usa off soltanto quando né l'utente né Claude devono poter vedere la skill.
• Usa on per ripristinare il comportamento originale.

Se la skill è tua, disable-model-invocation: true rappresenta la versione portabile, a livello di autore, di una policy riservata all'invocazione manuale. La descrizione scompare dall'elenco di Claude, mentre l'invocazione diretta resta disponibile.

Per le skill dei plugin il comportamento è diverso: skillOverrides non ha effetto. Disabilita il plugin senza disinstallarlo con /plugin disable plugin-name@marketplace-name, quindi ripristinalo con /plugin enable plugin-name@marketplace-name. Prima di spegnerlo, ricorda che un plugin può fornire anche agenti, hook, server MCP o strumenti per i linguaggi e controllane quindi tutti i componenti.

5. Riduci il corpo senza perdere funzionalità

Quando una skill utile ha un corpo troppo grande, tratta SKILL.md come una scheda di instradamento e sposta esempi dettagliati, riferimenti API e casi limite nei file di supporto. Anthropic consiglia di mantenere SKILL.md sotto le 500 righe. I file di supporto vengono caricati solo quando servono a Claude; gli script ausiliari, invece, possono essere eseguiti senza inserire il loro codice sorgente nel prompt.

Colloca all'inizio l'obiettivo, il trigger, le regole inderogabili e la mappa dei file di supporto. In questo modo proteggi anche la parte essenziale dopo la compattazione, quando di ogni skill reinserita vengono conservati soltanto i primi 5,000 token.

6. Verifica il risultato in una sessione nuova

Modificare una skill non elimina le istruzioni già caricate nella conversazione corrente. Apri una nuova sessione, prova alcuni prompt che dovrebbero attivare la skill e confronta i risultati con gli stessi prompt eseguiti mentre la skill è nascosta. Misura prima la riuscita del compito e solo dopo i token.

Anthropic raccomanda confronti in sessioni nuove, perché il contesto residuo usato per creare la skill o lasciato dalla skill stessa può mascherarne il contributo reale. Se le modifiche ai plugin richiedono /reload-plugins, considera che la richiesta successiva avrà un costo in token e potrebbe anche ricostruire la prompt cache quando il plugin espone strumenti MCP non differiti.

7. Ripristina ciò che serve e ripeti l'audit

Se la qualità peggiora, torna indietro di un livello: da off a user-invocable-only, dalla modalità riservata all'utente a name-only, oppure da plugin disabilitato ad abilitato. Se invece la qualità resta invariata, mantieni la configurazione più snella e riesegui /skill-doctor dopo un periodo rappresentativo di lavoro reale.

Quest'ultimo controllo è essenziale. L'obiettivo non è ottenere l'elenco di skill più corto possibile, ma quello meno costoso che sappia ancora instradare correttamente le attività ricorrenti.

Chi ottiene il vantaggio maggiore

Questi casi d'uso sono ordinati per probabile impatto economico.

1. Platform team che gestiscono una configurazione Claude Code condivisa

Chi guida una piattaforma usata da decine di sviluppatori può chiedere a un gruppo pilota di esportare i report locali di /skill-doctor, individuare le skill presenti ovunque ma mai attivate e rendere i workflow opzionali disponibili solo all'utente o al progetto. Il vantaggio si moltiplica per ogni turno di ogni sviluppatore, mentre il file di ripristino mantiene reversibile l'esperimento. Le skill gestite a livello enterprise non compaiono nel report: questo metodo offre quindi un campione locale della flotta, non un audit completo delle policy.

2. Team di sviluppo con molti plugin

Un team può installare un plugin per una singola migrazione e lasciare attivi per mesi skill, agenti, hook e strumenti MCP. /skill-doctor porta in evidenza i plugin non usati di recente e il gestore dei plugin consente di disabilitarli senza disinstallarli. Il risparmio non riguarda soltanto la descrizione della skill, perché un plugin inutilizzato può aggiungere diversi componenti che occupano contesto. Anche il rischio è più ampio: disabilitarlo può rimuovere componenti utili che non sono skill.

3. Consulenti che passano da uno stack cliente all'altro

Un consulente può mantenere globalmente skill per frontend, dati, ecommerce e infrastruttura, anche se per il cliente corrente è pertinente un solo gruppo. Può conservare profili nominati nelle impostazioni locali, esporre il gruppo rilevante e lasciare i workflow di sicurezza più rari in modalità manuale. Il risultato è un contesto iniziale pulito per ogni incarico, senza dover ricostruire tutti gli strumenti ogni lunedì.

4. Manutentori di grandi monorepo

Mentre legge directory sempre più profonde, Claude Code può scoprire skill annidate che restano disponibili per il resto della sessione. Chi mantiene un monorepo può eseguire un audit dopo un'attività trasversale a più pacchetti, spostare le istruzioni specifiche nella directory annidata corretta e accorciare le descrizioni al livello radice. Il vantaggio è un instradamento migliore: il lavoro sul backend non deve trascinarsi dietro una sfilata di descrizioni relative ai workflow frontend.

5. Team con comandi rari e ad alto rischio

Le skill per deployment, rollback, migrazioni dei dati e incidenti possono non attivarsi per settimane. Non vanno cancellate solo perché il report le segnala come inutilizzate. Impostandole per il solo uso manuale, le descrizioni spariscono dall'elenco ricorrente di Claude, ma resta disponibile la precisa via d'uscita /skill-name. Si alleggerisce così il contesto delle sessioni normali, senza dover ricostruire il runbook durante un'emergenza.

6. Autori di skill ricche di documentazione

Un autore può usare il report per trovare una skill costosa, quindi separare esempi lunghi e specifiche in file di supporto. Il file principale diventa una mappa decisionale concisa. Il vantaggio consiste nel rinviare il costo del contesto: i dettagli arrivano soltanto quando il lavoro raggiunge il ramo che li richiede.

7. Sviluppatori indipendenti con limiti di abbonamento

Chi sviluppa da solo potrebbe non vedere un risparmio economico diretto, perché Pro e Max includono l'utilizzo nell'abbonamento. Il beneficio concreto è riuscire a fare più lavoro entro la stessa quota e avere più spazio prima della compattazione. Affianca /skill-doctor a una configurazione pulita di Claude Code e azzera la sessione quando passi a un'attività non correlata.

Tre prodotti che vale la pena costruire

Il mercato di ricerca è più ampio di quanto faccia pensare la nuova query. Secondo DataForSEO, claude code skills totalizza 12,100 ricerche mensili negli Stati Uniti e un CPC di $8.26. Le frasi più specifiche sulla riduzione del contesto delle skill non hanno restituito suggerimenti: è quindi un'opportunità appena emersa all'interno di un mercato consolidato delle skill, non una categoria autonoma già matura.

1. Skill Budget Guard, l'opportunità più solida

Crea una CLI local-first e un controllo CI che leggano le skill del repository, le impostazioni di visibilità e un report /skill-doctor esportato, mostrando per ogni pull request la variazione di contesto. I platform team pagano perché lo strumento trasforma la pulizia fatta da un singolo sviluppatore in un budget replicabile per tutto il team.

Il segnale della domanda è insolitamente chiaro: claude code skills registra 12,100 ricerche al mese, ha un CPC di $8.26 e, secondo Anthropic, il costo enterprise medio di Claude Code va da $150 a $250 per sviluppatore al mese. La versione minima vendibile richiede un parser locale, un file di budget incluso nel repository, una GitHub Action e suggerimenti reversibili come “passa alla modalità manuale” o “separa i riferimenti”.

Il limite da non nascondere è il rischio di piattaforma. Anthropic potrebbe ampliare /skill-doctor e la sua Analytics API è già gratuita per le organizzazioni idonee. La difesa competitiva sta nello storico delle policy, nel confronto tra repository e nella prova che la riduzione del contesto non abbia peggiorato la riuscita delle attività.

2. Project Skill Profile Switcher

Crea profili nominati come frontend, data, incident e release, capaci di applicare modifiche a skillOverrides e di attivare o disattivare i plugin, per poi ripristinare lo stato precedente con un solo comando. I clienti sono consulenti e team che lavorano su monorepo.

DataForSEO rileva 590 ricerche mensili per best claude code skills, con intento commerciale e CPC di $11.91. L'MVP comprende un manifest, l'anteprima delle differenze, modifiche sicure alle impostazioni locali, comandi per i plugin e un punto di ripristino. Il limite è un vantaggio competitivo ridotto: i menu di Claude Code espongono già i controlli sottostanti e il ricaricamento dei plugin può aggiungere il costo della cache per un turno.

3. Skill Outcome Lab

Crea un test runner che invii lo stesso prompt realistico a nuove sessioni con la skill attiva e disattiva, quindi confronti percentuale di successo, tempo e token utilizzati. Gli autori di skill e i team interni di enablement pagano per dimostrare che un'istruzione vale il contesto che occupa.

DataForSEO rileva 110 ricerche mensili per claude code skills best practices, con intento commerciale e offerte nella parte alta della pagina comprese tra $4.14 e $6.01. Un MVP utile richiede prompt fixture, controlli sull'output atteso, isolamento in sessioni nuove e un semplice report prima/dopo.

Il limite è decisivo: il plugin ufficiale skill-creator di Anthropic confronta già i benchmark con e senza skill. Questa funzione dovrebbe far parte di Skill Budget Guard, non diventare un'azienda autonoma.

Se il tuo team distribuisce skill fra più prodotti o agenti, questo confronto tra Notion Skills e Claude Skills API completa il quadro sul versante della governance.

Che cosa non risolve /skill-doctor

/skill-doctor è un profiler dello spreco nell'elenco delle skill, non uno strumento completo per ottimizzare i costi di Claude Code.

• Non esamina le skill integrate né quelle enterprise.
• Non rimuove il corpo di una skill già caricato nella conversazione corrente.
• Non misura CLAUDE.md, la cronologia precedente, la scelta del modello, i thinking token, l'output prolisso degli strumenti o l'overhead MCP.
• Non può restituire report di utilizzo tramite Remote Control.
• Non può stabilire se una skill usata di rado abbia evitato un errore costoso.
• Non rende gratuito il contesto in cache. Il prezzo della cache e lo spazio occupato nel contesto sono questioni distinte.

Non cominciare abbassando skillListingBudgetFraction. Quando l'elenco supera il budget, Claude Code conserva i nomi ma elimina le descrizioni, iniziando dalle skill meno usate. Il testo si riduce, ma cala anche la probabilità che venga attivata la skill giusta. È preferibile rimuovere o nascondere deliberatamente le voci di scarso valore.

L'altro errore è disinstallare i plugin al primo sguardo. Prima disabilitali, poi esegui i test e disinstallali soltanto dopo aver verificato che gli altri componenti del plugin non servano.

La mossa da fare lunedì

Scegli un repository reale e uno sviluppatore che utilizzi Claude Code in modo intensivo. Esegui /skill-doctor, registra i cinque contributi inutilizzati più pesanti e modificane soltanto due: imposta un workflow raro per il solo uso manuale e disabilita un plugin davvero irrilevante. Avvia una nuova sessione, ripeti tre attività normali e ripristina tutto ciò che cambia il risultato. Entro venerdì avrai una policy difendibile per risparmiare contesto, non soltanto una configurazione più ordinata che ha peggiorato l'agente senza farsi notare.

Come si riduce il contesto usato da Claude Code?

Esegui /skill-doctor per trovare il costo delle skill inutilizzate nell'elenco, usa /context per il quadro complessivo, nascondi le skill irrilevanti, riserva all'uso manuale i workflow rari, sposta i riferimenti più lunghi nei file di supporto e usa /clear tra attività non correlate.

Come si riducono al minimo i costi di Claude Code?

Riduci prima il contesto ricorrente, quindi intervieni sulla scelta del modello, sulle sessioni lunghe, sulle impostazioni di thinking, sull'output prolisso degli strumenti e sui server MCP inutilizzati. /skill-doctor copre soltanto la quota di costo legata alle skill.

Le skill di Claude Code sono gratuite?

La documentazione di Anthropic sulle skill non indica un costo separato per un file locale SKILL.md, ma nome e descrizione possono consumare contesto a ogni turno, mentre il corpo completo ne consuma dopo l'invocazione. Gli utenti API pagano in base ai token utilizzati; chi ha un abbonamento attinge dalla quota inclusa.

Come si compatta il contesto di Claude Code?

Usa /compact quando devi mantenere continuità in un'attività lunga e /clear quando passi a un lavoro non correlato. Dopo la compattazione, i corpi delle skill invocate possono essere reinseriti fino a un massimo di 5,000 token per skill e 25,000 token complessivi.

Quando conviene azzerare il contesto di Claude Code?

Quando si passa a un'attività non correlata. Nei test di riduzione delle skill è importante partire da una sessione nuova, perché il corpo già caricato nella vecchia conversazione può nascondere l'effetto della disattivazione.

Se vuoi realizzare per il tuo team di sviluppo un workflow misurabile per la governance delle skill, scopri i sistemi AI per la produzione.