Quanti subagent servono davvero in Claude Code

Una collezione di oltre 230 subagent già pronti per Claude Code ha superato le 141.000 stelle su GitHub, e la domanda che si porta dietro conta più del numero: quanti subagent servono davvero. Un subagent di Claude Code è un file markdown con frontmatter YAML che definisce un assistente specializzato, con un proprio prompt di sistema, i propri strumenti e una finestra di contesto separata da quella della conversazione principale.

Il repository si chiama msitarzewski/agency-agents, è distribuito con licenza MIT, ha raccolto 23.000 fork e si presenta con una riga che dice bene di che umore è il progetto: "A complete AI agency at your fingertips - From frontend wizards to Reddit community ninjas, from whimsy injectors to reality checkers". Gli agenti sono divisi per reparto, dall'ingegneria al marketing alla sicurezza, e passano per game development, GIS e sanità.

Cosa fa davvero un subagent e perché ne sono nati più di duecento

Un subagent serve a togliere lavoro dalla conversazione principale, non ad aggiungere competenze. La documentazione ufficiale di Claude Code sui subagent lo dice in modo netto: si usa un subagent quando un compito laterale inonderebbe la conversazione di risultati di ricerca, log o contenuti di file che non rileggerete mai. Il subagent fa quel lavoro nel proprio contesto e restituisce soltanto il riassunto.

Da qui discende il motivo per cui esistono collezioni da centinaia di agenti. Se ogni volta lanciate lo stesso tipo di lavoratore con le stesse istruzioni, quelle istruzioni conviene scriverle una volta e riusarle. Il repository agency-agents fa esattamente questo su scala industriale, e dichiara la compatibilità con quattordici strumenti: Claude Code, GitHub Copilot, Antigravity, Gemini CLI, OpenCode, Cursor, Aider, Windsurf, OpenClaw, Qwen Code, Kimi Code, Codex, Osaurus e Hermes. Per Claude Code e Copilot i file markdown sono nativi, per Cursor uno script del repository li converte in regole .mdc.

La differenza rispetto alle agent skills, che sono procedure caricate dentro la stessa conversazione, è dove finiscono i token. Una skill entra nel contesto dell'agente principale, un subagent apre un contesto suo. Sono due strumenti diversi che risolvono due problemi diversi, e vengono confusi di continuo.

Perché installare tutti i subagent di Claude Code non funziona

Claude Code sceglie a chi delegare leggendo il campo description di ogni subagent, e questa è la ragione tecnica per cui una collezione da 230 non si installa in blocco. La documentazione di Anthropic è esplicita: "Claude uses each subagent's description to decide when to delegate tasks". Con 230 descrizioni installate, la decisione di delega diventa una selezione fra 230 candidati che competono sulle stesse parole, e la qualità di quella scelta non migliora aggiungendone altri.

Il limite non è teorico, ed è il repository stesso a documentarlo per un altro strumento. Il README di agency-agents avverte che il runtime di OpenCode registra soltanto circa 119 agenti e scarta silenziosamente il resto, tanto che l'installer mostra un avviso quando la selezione supera quella soglia. Un agente installato che il runtime scarta senza dirlo è peggio di un agente che non avete: credete di averlo e non ce l'avete.

C'è poi un modo silenzioso di rompersi che riguarda direttamente chi mescola collezioni diverse. La documentazione di Claude Code specifica che se due file dentro la stessa cartella .claude/agents/, sottocartelle comprese, dichiarano lo stesso name, viene caricata una sola definizione, scelta dall'ordine di lettura del filesystem e non da una precedenza documentata. Con una manciata di agenti scritti da voi il caso non si presenta mai. Con duecento agenti presi da due raccolte diverse si presenta il primo giorno, e non ve ne accorgete finché non delegate a quello sbagliato.

Come si scelgono i subagent che servono davvero

Il criterio pratico è uno solo: si installa un subagent quando esiste un lavoro ripetitivo, verboso e delimitato che state già facendo a mano. Tutto il resto è ingombro. Le buone pratiche pubblicate da Anthropic vanno nella stessa direzione, a partire dalla prima, "each subagent should excel at one specific task".

Tradotto in passaggi concreti, prima di installare qualsiasi collezione:

1. Usate l'installer in modalità interattiva, ./scripts/install.sh --tool claude-code, e selezionate a mano. Il repository offre anche --no-interactive e --parallel, che sono comodi e sono il modo esatto per ritrovarsi 230 agenti addosso.
2. Aprite il campo description di ogni agente che state per installare. È l'unico testo che decide quando quell'agente verrà chiamato, quindi è anche l'unico che vale la pena leggere per intero prima di dire di sì.
3. Decidete la portata: .claude/agents/ dentro il repository per gli agenti legati a quel progetto, ~/.claude/agents/ nella home per quelli che usate ovunque. Anthropic consiglia di mettere sotto controllo di versione quelli di progetto, così il team lavora con gli stessi.
4. Lanciate /doctor, che segnala i file che condividono lo stesso name e propone di rinominarli o rimuoverli.
5. Se lavorate con molti agenti in parallelo, tenete presente il tetto: venti subagent concorrenti per sessione, oltre i quali la creazione fallisce con Concurrent subagent limit reached. Si alza con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS e serve Claude Code 2.1.217 o successiva.

Sul sito che state leggendo la scelta è stata radicale e vale come esempio in negativo. Il repository di marcomasut.com non ha nessuna cartella .claude/agents/: zero subagent personalizzati. Ha invece una sola skill, .claude/skills/articolo/, divisa in cinque file markdown che coprono la struttura, le linee guida di scrittura, le regole SEO e GEO, la ricerca keyword e il taglio per il pubblico business. Il lavoro di scrittura degli articoli è iterativo e condivide contesto fra le fasi, quindi è esattamente il caso in cui la documentazione consiglia la conversazione principale e non un subagent. Lo stesso ragionamento sul contesto l'ho applicato alla mappa del repository quando ho scritto di come ridurre i token di un agente di coding.

Cosa cambia per chi costruisce con l'AI

Una collezione da 141.000 stelle non è un catalogo di cose da installare, è una libreria da cui pescare due o tre file e riscriverli. Il valore di agency-agents non sta nei 230 agenti, sta nel fatto che qualcuno ha già scritto e messo alla prova centinaia di prompt di sistema per ruoli specifici: leggerne cinque insegna più di qualsiasi guida su come si scrive una description che funziona.

Il rischio vero è un altro, ed è lo stesso di ogni cosa che si installa in blocco dentro un agente. Un subagent è codice che gira con i vostri permessi e i vostri strumenti, e la superficie cresce con il numero di file che avete accettato senza leggere. Su come quei confini possono non tenere ho scritto quando Claude Code ha esteso l'isolamento dei worktree ai subagent, e la lezione è la stessa qui: un confine che non conoscete non vi protegge.

Se ne dovete installare uno solo, che sia quello che risolve il lavoro noioso che vi state facendo a mano da settimane. Poi ne aggiungete un secondo quando serve, non prima.