Skill vs Subagent di Claude: Una Guida Empirica

La distinzione tra una skill e un subagent di Claude è un frequente punto di confusione. Gli sviluppatori che lavorano su Claude Code si chiedono spesso se impacchettare una logica come una skill riutilizzabile o come un subagent più complesso e isolato. La documentazione fornisce una guida teorica, ma la teoria spesso si scontra con la realtà. Questo articolo offre una risposta empirica alla domanda claude skills vs subagents.

In SkillProof, il nostro intero scopo è testare le skill di Claude Code su lavoro reale. Per farlo in modo affidabile, il nostro sistema di test esegue ogni skill candidata all'interno di un subagent dedicato, in modo che un'esecuzione non possa contaminare la successiva. Questo ci offre un punto di vista pratico, sebbene sia importante essere precisi su ciò che i nostri dati dimostrano e non dimostrano. Abbiamo registrazioni di esecuzione per 2090 skill, il che ci dice molto su come le skill falliscono — non un confronto controllato dello stesso task costruito in entrambi i modi. La differenza tra skill e agent di Claude esposta di seguito è la nostra interpretazione di tali fallimenti, e mostreremo i numeri dietro ogni affermazione in modo che possiate giudicare voi stessi il ragionamento.

Definire i Termini: Skill vs. Subagent

Prima di analizzare i dati, è importante stabilire definizioni chiare. Sebbene possano sembrare simili, skill e subagent servono scopi fondamentalmente diversi e operano a diversi livelli di astrazione.

Una skill è una ricetta. È un insieme di istruzioni e strumenti specifici e riutilizzabili che aumentano le capacità del modello base per un task ben definito. Una skill è definita in un file SKILL.md ed è progettata per essere richiamata dall'agent principale per eseguire un'azione discreta. Opera nel contesto dell'agent principale ed è più adatta per operazioni atomiche, come formattare codice, generare un tipo di file specifico o imporre uno stile interno. Pensatela come una scheda di ricetta che date a un cuoco che sa già cucinare.

Un subagent è un worker completamente separato. È un'istanza indipendente del modello, avviata da un agent primario per gestire un task grande, complesso o specializzato. Un subagent ha il proprio contesto, il proprio system prompt e può gestire il proprio stato durante un workflow multi-step. L'agent primario delega un obiettivo di alto livello al subagent, che poi lavora autonomamente per raggiungerlo. Pensatelo non come una funzione, ma come un servizio separato che chiamate tramite un'API.

Questa tabella riassume le differenze principali:

Caratteristica	Skill	Subagent
Analogia	Una ricetta specifica	Uno chef specializzato
Ambito	Task atomico, a scopo singolo	Workflow complesso, multi-step
Stato	Senza stato (stateless)	Finestra di contesto propria per l'esecuzione; restituisce un riepilogo e non conserva nulla in seguito
Contesto	Condivide il contesto con l'agent principale	Contesto isolato e indipendente
Complessità	Una directory: SKILL.md più script opzionali e file di riferimento caricati su richiesta	Un file markdown con frontmatter YAML in .claude/agents/ — system prompt, allowlist di strumenti, modello
Ideale per	Tooling, imposizione del formato	Task autonomi, ruoli specializzati

Come il Nostro Sistema di Test Rivela la Differenza

Notate che il vero asse di differenza in quella tabella è l'isolamento del contesto, non la dimensione del codice. Entrambi sono scritti come semplice markdown; solo uno ottiene la propria finestra.

La nostra metodologia di test si basa su questa distinzione. Come spiega la nostra pagina sulla metodologia, un agent esegue il test, non una persona: lo stesso agent produce una baseline senza skill e un tentativo guidato dalla skill per lo stesso task reale, poi valuta se il risultato è nettamente migliore di Claude senza la skill. Eseguiamo ciascuno di questi test nel proprio subagent in modo che l'esecuzione di una skill non possa influenzare quella di un'altra.

Questa configurazione impone un confine chiaro. Al subagent viene dato un unico obiettivo: eseguire il task usando la skill fornita. Osservando questo processo migliaia di volte, vediamo esattamente dove l'astrazione della skill eccelle e dove fallisce.

Le statistiche del nostro catalogo sono eloquenti. Delle 2090 skill testate fino ad oggi:

• 1291 (62%) superano ("pass") i nostri benchmark. Si installano, si attivano sui prompt che dichiarano di gestire e superano la baseline senza skill su un task reale.
• 697 richiedono configurazione ("setup"). Secondo la nostra metodologia, "setup" significa che la skill necessita di configurazione, una skill di supporto o un'integrazione connessa per poter funzionare. Analizzando le note di test di questi 697 casi, i blocchi sono prevalentemente legati all'accesso: 229 menzionano una CLI o un binario esterno, 171 una chiave API o credenziali, 169 un account o piano a pagamento, 136 un server o integrazione MCP.
• 102 ottengono un punteggio INFERIORE a Claude base. Non sono riuscite a superare la baseline senza skill — alcune perché non sono riuscite a eseguirsi affatto (una CLI mancante, una dipendenza non funzionante, un esempio che va in crash), altre perché, pur eseguendosi, hanno prodotto un output peggiore di quello di Claude base.

A una lettura onesta, quella distribuzione dice meno sull'architettura di quanto si potrebbe sperare. La categoria "setup" è principalmente una questione di credenziali e binari mancanti, che è ortogonale alla questione se un task appartenga a una skill o a un subagent. È nei fallimenti che si trova la vera lezione architetturale, e ne parleremo di seguito.

Quando Usare una Skill: Il Modello a Ricetta

Basandosi sulle 1291 skill che hanno superato i test nel nostro catalogo, emerge un modello chiaro. Le skill di successo sono focalizzate, stateless e deterministiche. Sono strumenti, non pensatori.

Ecco i casi d'uso ideali per una skill:

1. Task Atomici e Ripetibili: Una skill eccelle in task con un input chiaro e un output prevedibile. Pensate a cose per cui normalmente scrivereste un piccolo script. audit-export, una skill approvata nella nostra categoria produttività, è un chiaro esempio: fornitele un report di audit in markdown e produrrà un CSV pronto per l'importazione in Jira, Linear, Teamwork o Monday. Nel nostro test, ha trasformato un report con cinque rilievi in righe valide con date di scadenza corrette per le fasi e template di ticket multi-riga tra virgolette. Un solo compito, eseguito bene.

2. Insegnare a Claude a Usare l'Accesso che Già Possiede: Questa è la distinzione che le persone più spesso fraintendono, quindi fate attenzione: una skill non concede nuovi accessi. Non può raggiungere la vostra istanza Postgres o chiamare un'API di terze parti da sola — a questo servono i server MCP, e abbiamo trattato la divisione in Claude Skills vs MCP. Ciò che una skill fa è insegnare a Claude a usare le capacità che già possiede, in modo corretto e coerente. Se una CLI è già nel vostro PATH, una skill è il posto giusto per codificare come il vostro team la invoca.

3. Output Vincolato e Formattazione: Quando avete bisogno che l'output si conformi a una struttura rigida, una skill è la scelta giusta. git-workflow, nella nostra categoria coding, è un esempio funzionante: richiesto aiuto prima di aprire una PR da un branch con un solo commit chiamato my-fix con il messaggio di commit "fixed stuff", la skill ha indicato le violazioni specifiche della convenzione e ha prodotto sostituzioni conformi. Il file SKILL.md contiene istruzioni rigide sulla forma, che il modello segue in modo affidabile perché il task è circoscritto.

Le caratteristiche di una skill ben progettata, come si vede nei nostri esempi con punteggio elevato, includono un SKILL.md conciso, una definizione chiara di eventuali strumenti inclusi e l'assenza di logica complessa e ramificata. Le istruzioni dovrebbero guidare il modello, non tentare di programmarlo attraverso la prosa.

Quando Usare un Subagent: Il Modello Specialista

Se una skill è una ricetta, un subagent è uno specialista che assumete per un lavoro complesso. La decisione claude code subagent or skill diventa più chiara quando il task richiede memoria, iterazione o una persona distinta.

I nostri dati sulle skill che falliscono o richiedono una configurazione complessa mostrano quando uno sviluppatore avrebbe dovuto scegliere un'architettura a subagent fin dall'inizio.

Ecco i casi d'uso ideali per un subagent:

1. Workflow Complessi e Multi-Step: Qualsiasi task che richieda una sequenza di passaggi dipendenti è un lavoro per un subagent. Ad esempio: "Ricerca le prestazioni di vari algoritmi di ordinamento per dati quasi ordinati, scrivi un riassunto dei risultati e poi genera codice Python che implementi quello più efficiente." Questo workflow richiede di mantenere il contesto (la ricerca) attraverso più passaggi (riassumere, codificare). La natura stateless di una skill rende quasi impossibile farlo in modo affidabile.

2. Task che Richiedono Isolamento o una Persona Diversa: A volte un task richiede una mentalità completamente diversa da quella dell'agent principale. Un esempio classico è un agent "revisore di codice". Potreste volere che questo agent sia critico, meticoloso e concentrato solo sulla qualità del codice. Cercare di ottenere questa persona da un assistente generico tramite una skill è inefficiente e inaffidabile. È molto più efficace avviare un subagent con un system prompt su misura per quella persona critica.

3. Lavori a Lunga Esecuzione che non Volete nel Vostro Contesto: Una skill non è affatto una chiamata — nulla viene invocato e nulla viene restituito. Claude legge il file SKILL.md nel proprio contesto e segue le istruzioni da solo, all'interno del loop principale. Non c'è un worker separato a cui affidare un lavoro lungo. I subagent sono il meccanismo per questo, e dalla versione Claude Code v2.1.198 vengono eseguiti in background di default, con il foreground riservato a quando il risultato è necessario immediatamente. Un avvertimento da dichiarare chiaramente: per la semplice attesa — polling di un endpoint, osservare il completamento di una build — un task di shell in background è più economico e semplice che generare un agent. Ricorrete a un subagent quando il lavoro richiede giudizio, non solo pazienza.

La Zona Grigia: Perché 102 Skill Sono Peggio di Niente

I dati più illuminanti provengono dai nostri fallimenti — e non dicono ciò che ci aspettavamo. Siamo partiti dal presupposto che i 102 fallimenti fossero skill che si sforzavano di agire come subagent: file SKILL.md gonfiati, ramificazioni contorte, processi stateful stipati in una ricetta. Analizzando le note di test di tutti e 102, solo cinque menzionano la lunghezza o il "token bloat" a tutti. Quella teoria è per lo più sbagliata, e vale la pena dirlo piuttosto che abbandonarla silenziosamente.

Ciò che emerge in realtà si divide in due gruppi. Il più grande è il fallimento delle dipendenze: 30 dei 102 citano una CLI o un binario mancante, 22 un account a pagamento, 19 un server MCP mancante, 10 una chiave API assente. skill-builder è rappresentativo — ogni chiamata a uno strumento dipende da un server MCP separato che non è incluso o connesso automaticamente, e la skill non menziona mai il prerequisito, quindi un approccio manuale semplice lo supera. Questi sono fallimenti di packaging, non fallimenti di architettura.

Il secondo gruppo è più silenzioso e più istruttivo: skill che si installano correttamente, si attivano correttamente e semplicemente non producono nulla di meglio della baseline. api-design-principles è il caso più chiaro. Abbiamo testato un task di progettazione REST — un servizio di bookmarking con endpoint, versioning, paginazione ed esempi JSON — con e senza la skill. Entrambi i rami hanno prodotto un lavoro corretto e comparabile. aeon e arbor sono finiti allo stesso modo. È qui che la questione skill-versus-subagent si fa sentire: queste skill hanno cercato di codificare un intero processo di ragionamento in prosa, e il modello era già capace di tale ragionamento. La skill ha aggiunto parole senza aggiungere capacità.

Questa è l'onesta lezione architetturale. Non "le skill lunghe falliscono", ma: se ciò che state scrivendo è una procedura che il modello segue già con competenza, una skill non aggiunge nulla — e se la procedura ha genuinamente bisogno del proprio contesto, di una persona o di molti passaggi dipendenti, la prosa in un file SKILL.md è il contenitore sbagliato. La risposta a quando usare una skill vs un subagent in Claude Code è questa: se il vostro task assomiglia a un programma, costruiscitelo come un subagent; se assomiglia a un memo per un collega competente che conosce già il lavoro, potrebbe non essere affatto necessario.

Un'Eeuristica Pratica

Scegliere tra una skill e un subagent non deve essere un dibattito accademico. I nostri dati di test suggeriscono un'euristica semplice e pratica:

Il task è una chiamata di funzione o un programma?

• Se il vostro task può essere modellato come una singola chiamata di funzione — prende un input chiaro e produce un output discreto senza bisogno di ricordare interazioni passate — è una skill.
• Se il vostro task richiede stato, memoria interna, passaggi multipli o un contesto specializzato per essere eseguito — in altre parole, se si comporta come un programma autonomo — dovrebbe essere un subagent.

Aderendo a questa distinzione, gli sviluppatori possono costruire soluzioni più robuste, affidabili ed efficaci con Claude Code. Iniziate con l'astrazione più semplice che funziona. Una skill ben definita è potente. Ma riconoscete i segni di una complessità crescente e siate pronti a passare a un'architettura a subagent quando il task lo richiede.

Letture correlate: se avete deciso che il lavoro appartiene a un worker isolato, la nostra guida ai subagent di Claude Code spiega come definirne uno e cosa può effettivamente vedere. E se state ancora decidendo se avete bisogno di un nuovo accesso piuttosto che di istruzioni migliori, Claude Skills vs MCP traccia quella linea correttamente — è la fonte di confusione più comune.

Se avete bisogno di strumenti affidabili e pre-verificati per compiti di sviluppo comuni, abbiamo testato oltre un migliaio di skill approvate. Potete sfogliare per funzione nelle skill di coding e skill per documenti, o acquistare un pacchetto di dieci skill testate basato su un ruolo per 10$ — il developer toolkit è la scelta più adatta per il lavoro qui descritto.