# Agent Teams > Playbook operativo per creare e orchestrare agent team in Claude Code (piu istanze di Claude Code che collaborano condividendo una task list e messaggiandosi tra loro). Usa questa skill ogni volta che l'utente chiede di lanciare un team di agenti, fare spawn di teammate, parallelizzare un lavoro su piu agenti, eseguire una review o un'indagine multi-agente, coordinare lavoro su frontend/backend/t… - **Type:** Skill - **Install:** `agentstack add skill-antonioguadagnoai-agent-teams-agent-teams` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [AntonioGuadagnoAI](https://agentstack.voostack.com/s/antonioguadagnoai) - **Installs:** 0 - **Category:** [Communication](https://agentstack.voostack.com/c/communication) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [AntonioGuadagnoAI](https://github.com/AntonioGuadagnoAI) - **Source:** https://github.com/AntonioGuadagnoAI/agent-teams ## Install ```sh agentstack add skill-antonioguadagnoai-agent-teams-agent-teams ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent Team: Playbook Operativo Gli agent team fanno collaborare piu istanze di Claude Code. Una sessione e il **team lead** (questa sessione, che coordina e sintetizza). I **teammate** sono istanze separate di Claude Code, ciascuna con la propria context window, che prendono i task da una lista condivisa e si messaggiano direttamente tra loro. Questa e la differenza chiave rispetto ai subagent, che riportano solo al chiamante e non comunicano mai tra loro. Gli agent team sono potenti ma costosi: ogni teammate e un'istanza Claude completa, quindi il consumo di token cresce circa in modo lineare con la dimensione del team. Ricorri a un team solo quando l'esplorazione parallela e indipendente aggiunge davvero valore. Altrimenti una sessione singola o i subagent sono lo strumento migliore. ## Step 0: Verifica che sia lo strumento giusto Prima di fare spawn di qualsiasi cosa, decidi con questo gate rapido. Scegli un team **solo** se il lavoro e parallelizzabile in corsie indipendenti. **Usa un agent team quando:** - Ricerca o review da piu angolazioni contemporaneamente (es. sicurezza + performance + test sullo stesso PR) - Nuovi moduli o feature in cui ogni teammate possiede un pezzo separato - Debug con ipotesi competitive che i teammate testano in parallelo, sfidandosi a vicenda - Modifiche cross-layer (frontend, backend, test) ognuna gestita da un teammate diverso **NON usare un agent team; preferisci sessione singola o subagent quando:** - Il lavoro e sequenziale o ha forti dipendenze tra gli step - Piu worker modificherebbero gli stessi file (porta a sovrascritture) - Conta solo il risultato finale e i worker non devono mai parlarsi (usa i subagent) - Il task e di routine o piccolo (l'overhead di coordinamento supera il beneficio) Se il task non supera il gate, dillo e proponi l'alternativa piu economica invece di fare spawn di un team. **Subagent vs agent team, in sintesi:** - **Subagent**: context proprio, i risultati tornano solo al chiamante, l'agente principale gestisce tutto il lavoro, costo in token piu basso. Ideali quando conta solo il risultato. - **Agent team**: context totalmente indipendenti, i teammate si messaggiano tra loro, si auto-coordinano tramite una task list condivisa, costo in token piu alto. Ideali quando i worker devono discutere, sfidarsi e coordinarsi. ## Step 1: Verifica che la funzione sia abilitata Gli agent team sono sperimentali e **disabilitati di default**. Senza il flag non funziona niente. Verifica che `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` sia impostato a `1`, nell'ambiente o in `settings.json`: ```json { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } ``` Se non e impostato, di' all'utente di aggiungerlo e riavviare la sessione. Senza il flag non viene creato nessun team all'avvio, non vengono scritte le directory del team e non puoi fare spawn di teammate. Non tentare workaround. ## Step 2: Progetta il team Pianifica prima di fare spawn. Decidi quattro cose: **1. Dimensione del team.** Parti con **3-5 teammate** per la maggior parte dei workflow. E il compromesso tra parallelismo e overhead di coordinamento. Tre teammate focalizzati di solito battono cinque dispersi. Aumenta solo quando il lavoro beneficia davvero di piu corsie simultanee; i rendimenti calano in fretta oltre quel numero. **2. Ruoli e corsie.** Assegna a ogni teammate una corsia distinta e non sovrapposta, cosi non toccano mai gli stessi file. Dai un nome chiaro a ogni ruolo (es. `security-reviewer`, `perf-reviewer`, `test-validator`). Assegnare nomi espliciti in anticipo ti permette di indirizzare teammate e lead in modo prevedibile nei prompt successivi. **3. Scomposizione dei task.** Suddividi il lavoro in task autonomi, ognuno con un deliverable chiaro (una funzione, un file di test, una review, una nota di findings). Punta a **5-6 task per teammate**. Troppo piccoli e il costo di coordinamento domina; troppo grandi e i teammate lavorano a lungo senza check-in, rischiando sforzo sprecato. Con 15 task indipendenti, 3 teammate sono un buon punto di partenza. **4. Modello per teammate.** I teammate NON ereditano il `/model` del lead di default; usano il "Default teammate model" da `/config`. Se il task richiede un modello specifico, indicalo nello spawn prompt (es. "Usa Sonnet per ogni teammate"). Il livello di effort viene invece ereditato dal lead. ## Step 3: Scrivi spawn prompt efficaci I teammate caricano automaticamente il contesto di progetto (CLAUDE.md, server MCP, skill) ma **NON** ereditano la cronologia della conversazione del lead. Tutto cio che serve a un teammate deve stare nel suo spawn prompt. I prompt vaghi sono la causa piu comune di output scadente. Un buon spawn prompt nomina il ruolo, delimita i file, indica le aree di focus, fornisce i fatti rilevanti e definisce il formato del deliverable. **Debole:** `Fai spawn di un teammate per revisionare il codice di auth.` **Forte:** ```text Fai spawn di un teammate security-reviewer con il prompt: "Revisiona il modulo di autenticazione in src/auth/ per vulnerabilita di sicurezza. Concentrati su gestione dei token, gestione delle sessioni e validazione degli input. L'app usa token JWT salvati in cookie httpOnly. Riporta ogni problema con un livello di severita." ``` Per riusare un ruolo tra sessioni, referenzia una **subagent definition** per nome durante lo spawn (es. "Fai spawn di un teammate usando l'agent type security-reviewer"). Il teammate rispetta la allowlist `tools` e il `model` di quella definizione, e il corpo della definizione viene appeso al suo system prompt. Nota: i campi frontmatter `skills` e `mcpServers` di una subagent definition vengono ignorati per i teammate; questi caricano skill e MCP dalle impostazioni di progetto e utente. Vedi `references/mechanics.md` per i dettagli. ## Step 4: Fai spawn e coordina Fai spawn dei teammate descrivendo il task e i ruoli in linguaggio naturale. Il lead popola la task list condivisa, fa spawn di un teammate per corsia e coordina. **Assegna o lascia che prendano i task.** I task hanno tre stati (pending, in progress, completed) e possono dipendere da altri task. Puoi assegnare esplicitamente ("dai il task X al researcher") oppure lasciare che i teammate prendano il prossimo task disponibile quando ne finiscono uno. Il file locking impedisce che due teammate prendano lo stesso task. I task dipendenti si sbloccano automaticamente quando i prerequisiti sono completati. **Richiedi l'approvazione del piano per il lavoro rischioso.** Per modifiche complesse o distruttive, imponi ai teammate di pianificare prima: lavorano in plan mode a sola lettura finche il lead non approva. Dai al lead criteri di approvazione espliciti nel prompt (es. "approva solo piani che includono copertura di test", "rifiuta piani che modificano lo schema del database"), dato che il lead decide in autonomia. **Messaggia i teammate direttamente** per reindirizzarli o aggiungere istruzioni. Indirizza un teammate per nome; per raggiungere tutto il team, invia un messaggio per ogni destinatario. ## Step 5: Monitora, aspetta, sintetizza Non fare "fire and forget". Un team lasciato incustodito rischia di sprecare lavoro. - **Aspetta i teammate invece di fare il lavoro tu.** A volte il lead inizia a implementare invece di delegare. Se ti sorprendi a farlo, fermati e lascia finire i teammate. Se l'utente se ne accorge, potrebbe dire: "Aspetta che i tuoi teammate completino i loro task prima di procedere." - **Non cantare vittoria troppo presto.** Il lead puo pensare che il team abbia finito prima che tutti i task siano davvero completi. Verifica lo stato dei task; se un task sembra bloccato perche un teammate ha dimenticato di marcarlo completo, controlla lo stato reale, aggiornalo o sollecita il teammate. - **Guida man mano che arrivano i findings.** Reindirizza gli approcci che non funzionano e sintetizza i risultati in un'unica risposta coerente per l'utente man mano che i teammate riportano. ## Step 6: Spegni Per terminare un teammate in modo pulito, chiediglielo per nome (es. "Chiedi al teammate researcher di spegnersi"). Il teammate puo approvare e uscire, o rifiutare con una motivazione. Lo spegnimento puo essere lento perche il teammate prima finisce la richiesta o la tool call in corso. Le directory del team vengono ripulite automaticamente alla fine della sessione; non c'e uno step di cleanup manuale. ## Checklist best practice - Conferma che il task si parallelizzi davvero prima di fare spawn (Step 0). - Tieni i teammate lontani dai file altrui; un solo proprietario per set di file. - Front-load del contesto negli spawn prompt; i teammate partono ciechi rispetto alla cronologia del lead. - Dimensiona bene: 3-5 teammate, 5-6 task ciascuno. - Fai partire chi e nuovo agli agent team da task di **ricerca o review** (confini chiari, nessun conflitto di scrittura parallela) prima dell'implementazione parallela. - Pre-approva le operazioni comuni nelle permission settings prima dello spawn, dato che le richieste di permesso dei teammate risalgono al lead e creano frizione. - Se vuoi, imponi quality gate con gli hook (`TeammateIdle`, `TaskCreated`, `TaskCompleted`). Vedi `references/mechanics.md`. ## Pattern pronti all'uso **Code review parallela** (tre lenti indipendenti, nessun conflitto di file): ```text Fai spawn di tre teammate per revisionare il PR #142: - Uno focalizzato sulle implicazioni di sicurezza - Uno che verifica l'impatto sulle performance - Uno che valida la copertura di test Fai che ciascuno revisioni e riporti i findings. ``` **Indagine a ipotesi competitive** (il dibattito adversarial fa emergere la vera root cause): ```text Gli utenti segnalano che l'app si chiude dopo un messaggio invece di restare connessa. Fai spawn di 5 agent teammate per investigare ipotesi diverse. Falli parlare tra loro per provare a smontare a vicenda le proprie teorie, come un dibattito scientifico. Aggiorna il doc dei findings con il consenso che emerge. ``` **Refactor parallelo con modello fisso:** ```text Fai spawn di 4 teammate per rifattorizzare questi moduli in parallelo, un modulo ciascuno cosi non toccano mai gli stessi file. Usa Sonnet per ogni teammate. ``` ## Quando qualcosa va storto Modi di fallimento comuni e rimedi (display mode, path di storage e lista completa delle limitazioni sono in `references/mechanics.md`): - **I teammate non compaiono**: in modalita in-process appaiono nel pannello agenti sotto il prompt; usa le frecce su/giu e Invio per visualizzarli. Le righe idle si nascondono dopo 30s e ricompaiono al turno successivo. Verifica anche che il task fosse abbastanza complesso da giustificare un team. - **Teammate fermo su un errore**: visualizza il suo output, dai nuove istruzioni o fai spawn di un sostituto per continuare. - **Task bloccato / stato in ritardo**: un teammate puo aver finito ma non aver marcato il task come completo, bloccando i dipendenti. Verifica e aggiorna lo stato manualmente o sollecita il teammate. - **Il lead ha chiuso troppo presto**: digli di continuare finche tutti i task non sono davvero completi. - **Troppe richieste di permesso**: pre-approva le operazioni comuni prima dello spawn. ## Reference Carica `references/mechanics.md` quando ti servono i dettagli piu profondi: display mode (in-process vs split panes, setup tmux/iTerm2), il setting `teammateMode` e il flag `--teammate-mode`, gli hook per i quality gate, il layout di storage (`~/.claude/teams/`, `~/.claude/tasks/`), la meccanica delle subagent definition, i permessi e la lista completa delle limitazioni sperimentali (niente ripristino della sessione per i teammate in-process, un solo team per sessione, niente team annidati, lead fisso e altro). ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [AntonioGuadagnoAI](https://github.com/AntonioGuadagnoAI) - **Source:** [AntonioGuadagnoAI/agent-teams](https://github.com/AntonioGuadagnoAI/agent-teams) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-antonioguadagnoai-agent-teams-agent-teams - Seller: https://agentstack.voostack.com/s/antonioguadagnoai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.