Come creare un agente in Claude: guida completa
Un agente è un file di testo con dentro due righe di istruzioni e il compito che deve svolgere. Si salva in .claude/agents/ dentro il progetto, oppure in ~/.claude/agents/ per averlo dappertutto. Serve a far fare un lavoro ripetitivo sempre allo stesso modo, senza rispiegarlo ogni volta.
Fabrizio Piccoscritta il 19 settembre 2026 · si legge in 8 minuti
Se ti ritrovi a riscrivere le stesse istruzioni a Claude — «controlla la sicurezza come ti ho detto l’altra volta», «rivedi il codice guardando queste cose» — stai facendo a mano il lavoro di un agente. Un agente è quelle istruzioni, scritte una volta in un file. Ti spiego cos’è davvero, quando conviene e come si scrive, con un esempio completo che puoi copiare.
Cos’è un agente, in parole semplici
Un agente (in inglese subagent) è un assistente con un compito solo. Tu scrivi in un file chi è e cosa deve fare; da quel momento Claude può affidargli quel lavoro, e lui lo svolge in una conversazione sua, separata dalla tua.
Quella separazione è il punto. Immagina di chiedere «cerca in tutto il progetto dove si usa questa funzione»: la risposta sono centinaia di righe di risultati, che restano nella conversazione e occupano spazio anche quando hai già avuto la tua risposta. Un agente quelle righe le legge nella sua stanza e ti riporta solo la conclusione.
Il secondo motivo è la costanza. Un agente parte sempre dalle stesse istruzioni, quindi fa il controllo allo stesso modo il lunedì e il venerdì, e su ogni progetto.
Quando serve un agente e quando no
La documentazione di Claude Code è netta su questo, e vale la pena rispettarla: un agente non serve sempre, e usarlo dove non serve rallenta.
| Situazione | Agente | Conversazione normale |
|---|---|---|
| Molto testo in uscita | sì, caso tipico | riempie la chat |
| Serve che tu corregga | no | sì |
| Solo lettura | sì, si dichiara | no |
| Controllo ripetuto | sì | lo rispieghi ogni volta |
| Modifica veloce | no, più lento | sì |
| Ricerche in parallelo | sì, fino a venti | una alla volta |
Il file: dove si mette e com’è fatto
Un agente è un file di testo con estensione .md. Dove lo salvi decide chi lo vede.
| Cartella | Chi lo vede | Quando usarla |
|---|---|---|
| .claude/agents/ | solo quel progetto | l’agente conosce quel codice. Va in git |
| ~/.claude/agents/ | tutti i progetti | controlli che rifai dappertutto |
- Crea la cartella: .claude/agents/ nella radice del progetto.
- Crea un file con un nome parlante, per esempio controllo-sicurezza.md.
- Scrivi in cima il blocco fra due righe di tre trattini (le istruzioni), e sotto cosa deve fare l’agente.
- Riavvia Claude Code: la prima volta che crei la cartella, gli agenti dentro si vedono solo dopo il riavvio.
I campi delle istruzioni, uno per uno
Il blocco in cima al file accetta una ventina di campi; qui ci sono quelli che si usano davvero. I primi due sono obbligatori, gli altri servono a stringere le maglie.
| Campo | Obbligatorio | A cosa serve |
|---|---|---|
| name | sì | il nome, tutto minuscolo e con i trattini |
| description | sì | quando affidargli il lavoro |
| tools | no | cosa può usare. Omesso: eredita tutto |
| model | no | sonnet, opus, haiku o fable |
| permissionMode | no | quanto chiede prima di agire |
| disallowedTools | no | cosa togliere da quello che eredita |
| maxTurns | no | dopo quanti giri si ferma comunque |
| memory | no | se si ricorda da una volta all’altra |
Un agente completo, da copiare
Questo controlla le pagine di un sito prima di pubblicarle. È scritto in italiano, perché l’agente risponde nella lingua in cui gli parli, e sa solo leggere: non può cambiare niente.
- Crea .claude/agents/controllo-pagine.md.
- In cima metti il blocco delle istruzioni: name: controllo-pagine, description con scritto «Usalo prima di pubblicare una pagina», e tools: Read, Grep, Glob per lasciargli solo la lettura.
- Sotto, scrivi cosa deve controllare: un titolo h1 solo, la descrizione fra 120 e 155 caratteri, ogni immagine col testo alternativo, nessun collegamento rotto.
- Chiudi dicendogli come rispondere: un elenco di problemi trovati, ognuno col file e la riga, e in fondo «si può pubblicare» oppure no.
- Riavvia Claude Code e provalo su una pagina che sai avere un difetto: se non lo trova, le istruzioni non sono abbastanza precise.
Come si lancia
Ci sono quattro modi, dal più comodo al più preciso.
- Lo chiama Claude da solo, quando quello che chiedi somiglia alla description. È il motivo per cui quel campo va scritto bene.
- Lo nomini tu: «usa l’agente controllo-pagine su questa pagina».
- Con la chiocciola: scrivi @ e lo scegli dall’elenco. Così sei sicuro che parta quello e non un altro.
- Per tutta la sessione: avvii Claude Code con l’opzione che lo rende l’assistente principale, e da lì in poi lavori solo con lui.
I cinque errori che rendono un agente inutile
Li ho fatti quasi tutti. Sono questi.
- Description che descrive invece di dire quando. «Agente per la SEO» non fa scattare niente. «Usalo prima di pubblicare una pagina o dopo aver cambiato i testi» sì.
- Istruzioni vaghe. «Controlla che sia fatto bene» non è un controllo. Scrivi i numeri: quanti caratteri, quali file, cosa blocca e cosa no.
- Non dirgli come rispondere. Senza un formato fisso, ogni volta ti restituisce una cosa diversa e non riesci a confrontare due esiti.
- Lasciargli tutti gli strumenti. Se deve solo guardare, dagli solo la lettura: un agente che può scrivere prima o poi scrive.
- Non provarlo su un caso che deve fallire. Un agente che non ha mai detto di no non sai se sa dirlo.
Domande frequenti
Che differenza c’è fra un agente e una skill?
Una skill è un manuale: spiega a Claude come si fa una cosa, e lui la legge quando serve, restando nella tua conversazione. Un agente è una persona in più: lavora per conto suo in una conversazione separata e ti riporta il risultato.
Regola pratica: se ti serve sapere come si fa, è una skill. Se ti serve che qualcuno lo faccia e ti dica com’è andata, è un agente.
Un agente ha accesso a tutto il mio computer?
No, e di suo passa dagli stessi controlli di permesso di qualunque altra azione: se un comando richiede la tua conferma, la richiede anche quando lo lancia un agente. In più puoi restringerlo dal file, con il campo tools: se scrivi solo gli strumenti di lettura, quell’agente non può scrivere niente.
Ma c’è un campo che quei controlli li toglie, ed è giusto saperlo prima di copiare l’agente di qualcun altro: permissionMode. Con bypassPermissions l’agente non chiede più niente e fa quello che vuole sul tuo computer. Se scarichi un agente scritto da altri, quella riga è la prima da guardare.
Quanti agenti posso far lavorare insieme?
Venti alla volta, di serie. Arrivato a venti non ne parte un altro finché uno dei venti non ha finito: te lo dice con un messaggio chiaro, non si blocca niente. Il numero si può cambiare, e il motivo più frequente per cambiarlo è abbassarlo, perché ogni agente consuma richieste per conto suo. Ha senso lanciarne tanti quando le ricerche sono indipendenti fra loro — cinque controlli diversi sulla stessa cartella. Se invece un agente ha bisogno del risultato di un altro, vanno in fila e il parallelo non serve.
Un agente può chiamarne un altro?
Sì, fino a tre livelli sotto la conversazione principale. È una cosa da usare con parsimonia: ogni livello aggiunge tempo e rende più difficile capire chi ha fatto cosa quando qualcosa va storto.
Dove metto l’agente se lavoro su due computer?
Se riguarda un progetto, in .claude/agents/ dentro il progetto, e lo committi: così viaggia con il codice e lo trovi su tutte le macchine. Se lo metti solo in ~/.claude/agents/ resta su quel computer, e sull’altro non esiste. È l’errore più comune, e non dà nessun segnale: semplicemente l’agente non parte.
Serve pagare per usare gli agenti?
No, gli agenti sono una funzione di Claude Code: non costano nulla in più rispetto al piano che già usi. Consumano però richieste come qualunque altro lavoro, e un agente che legge cento file ne consuma quanto leggerli tu.
Come faccio a sapere se l’agente è stato usato davvero?
Claude Code lo dice mentre lavora, indicando quale agente ha lanciato. Se hai il dubbio che non venga mai chiamato, nominalo esplicitamente con la chiocciola: se così funziona ma da solo non parte mai, il problema è la description, che non assomiglia abbastanza a quello che chiedi.
Da dove vengono questi dati
Dati controllati il 19 settembre 2026.
- Claude Code — Creare subagent personalizzati (documentazione ufficiale) letta il 19 settembre 2026
- Anthropic — repository ufficiale delle Agent Skills letto il 19 settembre 2026
Questa guida l’ho scritta con l’aiuto dell’intelligenza artificiale e l’ho verificata sulle fonti qui sopra prima di pubblicarla. Come lavoro
