Le skill di Claude Code: quando servono e quando pesano

Una skill di Claude Code è una cartella con dentro un solo file. Il file si chiama SKILL.md. Apre con un frontmatter YAML (un name e una description) e poi un corpo in markdown. Claude carica il corpo nel contesto solo quando la description corrisponde a ciò che l'utente ha chiesto. Il caricamento on-demand è tutto il senso del meccanismo.

La trappola è che le skill sembrano contenuto di CLAUDE.md che ha imparato ad aspettare il proprio turno. CLAUDE.md entra in ogni prompt. Le skill stanno su uno scaffale e si fanno vedere solo quando Claude le ritiene rilevanti. Sembra gratis. Non lo è. Una description di skill pesa circa 75-150 token una volta avvolta nel suo XML, e con il budget di default Claude Code tiene visibili circa 15-25 description su una finestra di contesto da 200K prima che il troncamento ne tagli alcune. Ogni skill è un posto che un'altra skill non può occupare.

È il trade-off che la maggior parte dei team non vede quando spedisce le prime skill. Qui sotto, quattro situazioni in cui una skill ripaga il suo posto, e quattro in cui costa più di quello che restituisce.

Quando una skill si guadagna il posto

Usa una skill se la procedura passa le cinque righe

Se incolli sempre la stessa ricetta in cinque passi (preparare il database di test con queste env, seedarlo con queste fixture, far girare quel comando npm, fare il parsing dell'output così, scrivere l'assertion in questo modo), quella ricetta sta in una skill. Il corpo della skill può arrivare a centinaia di righe senza appesantire le sessioni che non la chiamano. Il costo è la description nel listato, non il corpo. Un corpo lungo che parte una volta a settimana è economico; lo stesso corpo dentro CLAUDE.md è caro a ogni prompt, per sempre.

Usa una skill quando il workflow scatta solo a volte

Una checklist di review PR scatta una volta per PR. Un generatore di changelog scatta alla release. Uno scrittore di migration scatta quando si sposta lo schema. Nessuno di questi sta in CLAUDE.md, perché CLAUDE.md si carica a ogni prompt e portarsi dietro una procedura da release a ogni modifica di codice costa token reali sul tetto settimanale. La skill si carica solo sui prompt in cui la description fa match. Lo scrittore di migration dorme attraverso le 200 attività non correlate fra una migrazione e la successiva.

Usa una skill quando correggi sempre la stessa libreria

Ogni libreria che ha rilasciato una major nei dodici mesi precedenti produce codice in parte sbagliato dal training data. Next.js 16, l'SDK di Anthropic, Prisma, gran parte dei tool Vercel. Una skill che mette nero su bianco l'API attuale più tre punti che gli agenti sbagliano (export rinominati, default cambiati, pattern deprecati) tiene Claude sulla versione nuova senza che tu rispieghi lo stesso fix a ogni sessione. La vincita si accumula: ogni persona sul repo riceve la stessa correzione senza scambiarsi documenti.

Usa una skill quando più agenti hanno bisogno della stessa competenza

Procedure di review di sicurezza, metodi di analisi dati, audit di accessibilità. Se la stessa conoscenza deve abitare in tre subagent, abita in una skill che tutti e tre richiamano. I subagent isolano contesto e permessi sui tool. Le skill impacchettano competenza riutilizzabile. La differenza conta quando il team cresce oltre una persona e un progetto: un subagent che incorpora la logica di security review la lega a una sola attività, una skill la rende disponibile a qualunque attività citi la sicurezza.

Quando le skill diventano peso morto

Salta la skill se la regola vale per ogni task

«Usa sempre feat:, fix:, chore: nei commit.» «Non toccare i file in src/legacy/.» «Fai partire npm run typecheck prima di dire che il task è chiuso.» Roba da CLAUDE.md, non da skill. Una skill si carica solo se la description fa match, perciò una regola di progetto messa in skill manca in silenzio i prompt dove serviva. CLAUDE.md non manca mai. È il suo lavoro. Mettere una regola sempre-on dietro un fuzzy match è il modo per scoprire che la regola era spenta da sempre.

Salta la skill se il team è una persona e un progetto

Se sei un ingegnere solo con un repo, l'economia degli slot non morde ancora. Quasi tutto sta in CLAUDE.md senza problemi di compattazione. Le skill iniziano a servire quando la procedura supera quello che CLAUDE.md regge a basso costo, oppure quando va condivisa fra repo e persone. Un progetto solo raramente arriva a una delle due soglie. Forzare la struttura presto aggiunge un livello di cartelle senza ritorno, e il costo cognitivo di ricordare dove sta cosa esiste davvero.

Salta la skill se la description è vaga

La description è il trigger. Claude fa fuzzy matching su quella stringa, e una description come «aiuta con le attività sul database» non scatterà mai perché nulla di ciò che l'utente scrive ci si sovrappone. La guida ufficiale di Anthropic dice di aprire col verbo che l'utente direbbe («Crea, aggiorna o elenca task programmati…»), poi il sostantivo, poi le condizioni. Va oltre: serve un tono un po' insistente, perché Claude tende a sottoattivare le skill quando potrebbero aiutarlo. Se la description suona da marketing, la skill è zavorra nel listato e Claude continua a fare la cosa sbagliata perché non l'ha mai vista scattare.

Togli di mezzo le skill che non usi più

Il budget di default per il listato è l'uno per cento della finestra di contesto. Su 200K stanno 15-25 description prima che il troncamento inizi a far cadere skill che ti potevano servire. Ogni skill tenuta lì è uno slot che un'altra non può prendere, e se alzi il budget abbastanza da farle entrare tutte, il conto può arrivare a 300K prompt token in più alla settimana su un piano Pro solo per mostrare la directory. Rivedi la lista una volta a trimestre. Se una skill non scatta da tre mesi, archiviala.

Come capire se una skill si è guadagnata lo slot

Prima di pubblicare una skill nuova, tre domande.

Prima: la description fa match con un prompt che l'utente scriverebbe davvero? Leggila a freddo e controlla che apra con un verbo concreto. «Crea task programmati, aggiornali, elencali» batte «aiuta con la pianificazione» ogni volta, perché la prima frase condivide parole con il modo in cui l'utente fa la richiesta.

Seconda: il corpo spinge Claude oltre il suo comportamento di default? Una skill che ricorda di usare useEffect è sprecata; una skill che mette nero su bianco tre punti che Claude sbaglia sempre su una libreria no. Il contenuto utile di una skill è ciò che Claude non avrebbe scritto da solo.

Terza: c'è una sezione Gotchas? La parte più citata di ogni skill ben fatta è l'elenco degli errori comuni. La guida ufficiale di Anthropic per chi scrive skill si appoggia molto su questo pattern. Se la skill è solo un tutorial, Claude il tutorial lo sa già scrivere. Se documenta i modi di fallire che continui a incontrare, si guadagna lo slot.

Il quadro generale: CLAUDE.md tiene i fatti che valgono per ogni task nel repo. Le skill tengono le procedure che scattano a volte e gonfierebbero ogni sessione se fossero sempre attive. I subagent tengono i compiti che vogliono finestra di contesto e permessi sui tool propri. La maggior parte dei team va sulle skill per prima perché le cartelle sembrano pulite. Le cartelle pulite costano token veri. Usale quando la procedura ripaga.

Lo strato runtime della personalizzazione di Claude Code l'abbiamo trattato nel pezzo sugli hook di Claude Code. Le skill stanno un livello sopra: gli hook intercettano le chiamate ai tool, le skill iniettano competenza su richiesta. Si compongono, e rispondono a domande diverse.