--- title: "Agent Skills: guida gli agenti AI come un software engineer senior" date: "2026-06-11" category: "Sviluppo Software" tags: ["automazione", "coding agents", "intelligenza artificiale", "sviluppo software"] author: "Giuseppe Carruezzo" description: "Ottimizza i tuoi agenti di programmazione AI con Agent Skills: workflow metodologici, test e controllo qualità per uno sviluppo software professionale." source: "https://ainsights.it/blog/agent-skills-guida-agenti-ai" --- # Agent Skills: guida gli agenti AI come un software engineer senior ![Agent Skills: guida gli agenti AI come un software engineer senior](/blogai/backend/uploads/6a2a708403998.webp) Gli agenti di programmazione basati su intelligenza artificiale (AI coding agents), ossia sistemi autonomi capaci di modificare codice e navigare repository, tendono per natura a scegliere la via più breve. Questo comportamento si traduce spesso nella rinuncia a test, specifiche e controlli di sicurezza. **Agent Skills** risolve questo problema strutturale fornendo un set di workflow standardizzati che costringono gli agenti AI a seguire la stessa disciplina metodologica tipica dei software engineer di livello senior. - **24** — Skill Totali (Workflow pronti all'uso per gli agenti AI) - **7** — Comandi Slash (Azioni rapide mappate sul ciclo di vita del software) - **4** — Personaggi Specialistici (Ruoli verticali configurati per audit mirati) ```mermaid flowchart TD A[Idea /spec] --> B[Specifica /plan] B --> C[Codice /build] C --> D[Test /test] D --> E[QA /review] E --> F[Go Live /ship] ``` ## I 7 comandi fondamentali del ciclo di vita Il sistema mappa le attività quotidiane di sviluppo su sette comandi principali. Ogni comando attiva automaticamente le competenze necessarie alla fase corrente.

Attività	Comando	Principio chiave
Definire cosa sviluppare	`/spec`	Scrivere la specifica prima del codice
Pianificare lo sviluppo	`/plan`	Scomporre in task atomici e ridotti
Sviluppare in modo incrementale	`/build`	Implementare una "vertical slice" alla volta
Dimostrare il funzionamento	`/test`	I test sono l'unica prova di validità
Revisionare prima del merge	`/review`	Preservare e migliorare la salute del codice
Semplificare la base codice	`/code-simplify`	La chiarezza prevale sull'astuzia algoritmica
Rilasciare in produzione	`/ship`	Rilasci rapidi e frequenti sono più sicuri

Per ridurre i passaggi manuali dopo la stesura della specifica, il comando `/build auto` permette di generare il piano d'azione e implementare ogni singolo task in un unico ciclo approvato. L'utente valida il piano d'azione una sola volta, dopodiché l'agente esegue lo sviluppo in autonomia. Questo automatismo elimina la necessità di interventi umani _tra_ i singoli compiti, ma non aggira i controlli: ogni attività viene comunque testata e sottoposta a commit individuale, con arresti automatici in caso di errore o passaggi ad alto rischio. Le skill si attivano anche in base al contesto operativo. Ad esempio, la progettazione di un endpoint REST attiva autonomamente le regole di `api-and-interface-design`, mentre la scrittura di componenti visivi richiama le direttive di `frontend-ui-engineering`. ### Pro - Automazione fluida tra fasi di pianificazione ed esecuzione - Applicazione rigorosa di standard qualitativi industriali - Integrazione nativa con i principali strumenti e IDE di mercato ### Contro - Curva di apprendimento iniziale per configurare correttamente i file delle regole - Consumo di token più elevato a causa del contesto strutturato richiesto ## Guida all'installazione rapida ## Come installare e configurare Agent Skills 1. **Installazione su Claude Code**: Esegui all'interno del terminale il comando: \`/plugin marketplace add addyosmani/agent-skills\` seguito da \`/plugin install agent-skills@addy-agent-skills\`. Se riscontri errori di autenticazione SSH con GitHub, usa l'URL HTTPS completo per forzare la clonazione. 2. **Configurazione per Cursor**: Copia il contenuto del file \`SKILL.md\` desiderato all'interno della cartella \`.cursor/rules/\` del tuo progetto, oppure fai riferimento all'intera directory \`skills/\`. 3. **Integrazione con Antigravity CLI**: Aggiungi Agent Skills come plugin nativo digitando a terminale il comando: \`agy plugin install https://github.com/addyosmani/agent-skills.git\`. 4. **Configurazione per Gemini CLI**: Usa il comando nativo di installazione delle competenze: \`gemini skills install https://github.com/addyosmani/agent-skills.git --path skills\` per consentire l'auto-scoperta dei flussi. **Altre integrazioni (Windsurf, OpenCode, Copilot, Kiro)** - **Windsurf:** Integra le istruzioni delle skill all'interno del file di configurazione delle regole globali di Windsurf. - **OpenCode:** Sfrutta l'esecuzione guidata tramite il file `AGENTS.md` e l'apposito strumento di sistema `skill`. - **GitHub Copilot:** Usa le definizioni presenti nella cartella `agents/` come personas personalizzate e copia i contenuti delle skill in `.github/copilot-instructions.md`. - **Kiro IDE:** Salva i file delle skill sotto la cartella `.kiro/skills/` a livello di singolo progetto o a livello globale. ## La mappa completa delle 24 Skill Le competenze sono suddivise in categorie logiche che coprono l'intero ciclo di vita dello sviluppo del software. Oltre alle 23 skill operative, il pacchetto include una meta-skill di coordinamento denominata `using-agent-skills`. ### Meta - Selezione delle competenze

Skill	Descrizione operativa	Quando usarla
using-agent-skills	Mappa il lavoro in ingresso verso il workflow corretto e definisce le regole di esecuzione condivise.	All'avvio di una sessione o per decidere quale competenza attivare.

### Define - Definizione dei requisiti

Skill	Descrizione operativa	Quando usarla
interview-me	Intervista l'utente ponendo una sola domanda alla volta per estrarre le reali necessità di business fino a raggiungere una confidenza del 95%.	Quando la richiesta iniziale è vaga, ambigua o se l'utente richiede esplicitamente una sessione di brainstorming ("grill me").
idea-refine	Applica una metodologia strutturata di pensiero divergente e convergente per trasformare concetti grezzi in proposte tecniche concrete.	In presenza di un'idea di massima che necessita di esplorazione e analisi di fattibilità.
spec-driven-development	Guida la stesura di un PRD (Product Requirements Document, il documento dei requisiti di prodotto) che definisce obiettivi, comandi, architettura, stile e vincoli prima di toccare il codice.	All'avvio di ogni nuova funzionalità, progetto o rifattorizzazione importante.

### Plan - Scomposizione del lavoro

Skill	Descrizione operativa	Quando usarla
planning-and-task-breakdown	Suddivide le specifiche in compiti atomici, sequenziali e facilmente verificabili, completi di criteri di accettazione.	Una volta completata la specifica tecnica e prima di iniziare la fase di scrittura del codice.

### Build - Sviluppo e scrittura del codice

Skill	Descrizione operativa	Quando usarla
incremental-implementation	Implementa fette verticali ridotte e autoconsistenti. Prevede l'uso di feature flag (interruttori logici per abilitare o disabilitare funzionalità a runtime) e rollback sicuri.	Per qualsiasi modifica al codice che coinvolga più di un file contemporaneamente.
test-driven-development	Applica il ciclo TDD (Test-Driven Development: scrittura del test, implementazione, rifattorizzazione). Gestisce la piramide dei test (80% unitari, 15% integrazione, 5% end-to-end) seguendo l'approccio DAMP (Descriptive and Meaningful Phrases) per privilegiare la leggibilità.	Durante lo sviluppo di nuove logiche, la risoluzione di bug o modifiche ai comportamenti esistenti.
context-engineering	Fornisce agli agenti le informazioni giuste al momento giusto tramite file di regole, riduzione del rumore informativo nel contesto e integrazioni MCP (Model Context Protocol).	All'inizio di una sessione, al cambio di task o quando la qualità delle risposte dell'agente degrada.
source-driven-development	Fonda ogni decisione tecnica sulla documentazione ufficiale di librerie e framework, citando le fonti e segnalando i punti non verificati.	Per assicurarsi che l'agente non allucini sintassi o API deprecate di framework esterni.
doubt-driven-development	Sottopone a processo avversario e revisione critica ogni decisione non banale (flusso CLAIM → EXTRACT → DOUBT → RECONCILE → STOP), consentendo escalation a modelli superiori.	In contesti critici (sicurezza, produzione, modifiche irreversibili) o quando si lavora su basi codice ereditate e non familiari.
frontend-ui-engineering	Organizza l'architettura dei componenti visivi, i design system, la gestione dello stato, l'ottimizzazione dell'interfaccia e l'accessibilità WCAG 2,1 AA.	Durante lo sviluppo o la modifica di elementi grafici e flussi utente sul browser.
api-and-interface-design	Progettazione contrattuale delle interfacce. Previene violazioni della Legge di Hyrum (secondo cui ogni comportamento osservabile di un'API finirà per essere sfruttato da qualche client) e gestisce la validazione dei confini del sistema.	Durante il disegno di API, endpoint, moduli interni o librerie condivise.

### Verify - Validazione e Debugging

Skill	Descrizione operativa	Quando usarla
browser-testing-with-devtools	Sfrutta le API di Chrome DevTools via MCP per estrarre log, ispezionare il DOM, tracciare richieste di rete e analizzare i profili prestazionali.	Durante lo sviluppo, il test e il debugging di applicazioni web lato client.
debugging-and-error-recovery	Triage strutturato in cinque fasi: riproduzione, localizzazione, isolamento, risoluzione e prevenzione. Applica la regola del blocco immediato della linea di sviluppo.	In caso di test falliti, build interrotte o anomalie nel comportamento dell'applicazione.

### Review - Controllo qualità pre-integrazione

Skill	Descrizione operativa	Quando usarla
code-review-and-quality	Revisione formale su cinque assi qualitativi. Limita la dimensione delle modifiche a circa 100 righe per pull request e impone tag di gravità (Nit, Optional, FYI).	Prima di effettuare il merge di qualsiasi contributo nel ramo principale.
code-simplification	Applica il principio della Staccionata di Chesterton (non rimuovere una regola o una riga di codice senza averne compreso la ratio originale) e la Regola delle 500 righe per ridurre la complessità cognitiva.	Quando il codice funziona correttamente ma risulta eccessivamente complesso da leggere, manutenere o estendere.
security-and-hardening	Previene le vulnerabilità OWASP Top 10, verifica i flussi di autenticazione, gestisce le chiavi segrete ed effettua l'auditing delle dipendenze.	In presenza di moduli che gestiscono dati utente, autenticazione, persistenza o integrazioni con l'esterno.
performance-optimization	Ottimizzazione orientata alle metriche. Analizza i Core Web Vitals, i bundle applicativi ed esegue profiling preventivo per bloccare regressioni prestazionali.	In presenza di requisiti di performance stringenti o in caso di sospetto degrado dei tempi di risposta.

### Ship - Rilascio e manutenzione

Skill	Descrizione operativa	Quando usarla
git-workflow-and-versioning	Impone il Trunk-Based Development (integrazione continua su un unico ramo principale), commit atomici e l'uso dei commit come punti di ripristino rapidi.	Costantemente, durante l'esecuzione di qualunque modifica al codice sorgente.
ci-cd-and-automation	Implementa l'approccio "Shift Left" (anticipazione dei test nelle prime fasi dello sviluppo), pipeline di validazione automatica e cicli rapidi di feedback in caso di fallimento della build.	Durante l'impostazione, manutenzione o aggiornamento dei server di integrazione e rilascio continuo.
deprecation-and-migration	Considera il codice esistente come una passività finanziaria (liability). Gestisce deprecazioni obbligatorie o consultive e la rimozione sistematica del codice morto.	Durante la dismissione di vecchie API, la migrazione di utenti su nuovi sistemi o la rimozione di funzionalità obsolete.
documentation-and-adrs	Redige Architecture Decision Records (ADR, documenti per tracciare le decisioni architetturali significative), documentazione di API e standard di commenti interni concentrandosi sul perché e non sul cosa.	Ogni volta che si compiono scelte strutturali importanti, modifiche di interfaccia o rilascio di nuove parti di sistema.
observability-and-instrumentation	Configura log strutturati, metriche RED (Rate, Errors, Duration) e tracciamento distribuito tramite OpenTelemetry fin dalla fase di scrittura del codice.	Durante l'aggiunta di telemetria o prima del rilascio in produzione di servizi critici.
shipping-and-launch	Verifica checklist pre-lancio, cicli di vita delle feature flag, roll-out progressivi e procedure standardizzate di ripristino rapido (rollback).	Nelle ore o nei giorni immediatamente precedenti al deployment in produzione.

## Personaggi specialistici e checklist di riferimento Il repository non contiene solo file di competenza sequenziali, ma mette a disposizione dell'utente anche una serie di personaggi (Agent Personas) altamente verticali e delle risorse di consultazione rapida. ### Agent Personas configurati - **code-reviewer (**[**agents/code-reviewer.md**](/addyosmani/agent-skills/blob/main/agents/code-reviewer.md)**):** Agisce come un Senior Staff Engineer, valutando le modifiche secondo i cinque assi qualitativi tipici dei processi di ingegneria di Google. - **test-engineer (**[**agents/test-engineer.md**](/addyosmani/agent-skills/blob/main/agents/test-engineer.md)**):** Specialista di QA (Quality Assurance) focalizzato sull'analisi della copertura e sulla definizione delle strategie di test. - **security-auditor (**[**agents/security-auditor.md**](/addyosmani/agent-skills/blob/main/agents/security-auditor.md)**):** Ingegnere di sicurezza dedicato al threat modeling (modellazione delle minacce) e al rilevamento di vulnerabilità OWASP. - **web-performance-auditor (**[**agents/web-performance-auditor.md**](/addyosmani/agent-skills/blob/main/agents/web-performance-auditor.md)**):** Esegue audit automatici e analisi dei Core Web Vitals tramite il comando rapido `/webperf`. ### Checklist di riferimento - [references/testing-patterns.md](/addyosmani/agent-skills/blob/main/references/testing-patterns.md): Esempi pratici di mocking, unit test, test E2E e pattern architetturali per i test. - [references/security-checklist.md](/addyosmani/agent-skills/blob/main/references/security-checklist.md): Controlli pre-commit per header HTTP, CORS, gestione dei segreti e sanitizzazione degli input. - [references/performance-checklist.md](/addyosmani/agent-skills/blob/main/references/performance-checklist.md): Target quantitativi per i Core Web Vitals, checklist ottimizzazione frontend/backend e istruzioni di profilazione. - [references/accessibility-checklist.md](/addyosmani/agent-skills/blob/main/references/accessibility-checklist.md): Guida pratica per la navigazione da tastiera, compatibilità con screen reader, standard ARIA e test di usabilità inclusiva. ## Anatomia di una Skill e logica interna Ogni file all'interno della cartella `skills/` è strutturato secondo uno standard fisso. Questo permette all'agente AI di comprendere immediatamente come comportarsi senza perdersi in lunghe descrizioni discorsive. ```plaintext ┌─────────────────────────────────────────────────┐ │ SKILL.md │ │ │ │ ┌─ Frontmatter ─────────────────────────────┐ │ │ │ name: nome-competenza-in-kebab-case │ │ │ │ description: Guida gli agenti nel task... │ │ │ │ Utilizzare quando... │ │ │ └───────────────────────────────────────────┘ │ │ │ │ Overview → Scopo della competenza │ │ When to Use → Condizioni di attivazione │ │ Process → Workflow passo-passo │ │ Rationalizations → Scuse comuni dell\u0027agente │ │ Red Flags → Segnali di errore o fretta │ │ Verification → Evidenze e test richiesti │ └─────────────────────────────────────────────────┘ ``` I quattro pilastri che sorreggono l'architettura di Agent Skills sono studiati per superare le limitazioni intrinseche dei modelli linguistici correnti: 1. **Workflow prescrittivi invece di prosa descrittiva:** Le skill non sono testi teorici da leggere, ma veri e propri algoritmi di comportamento che l'agente deve eseguire passo dopo passo, con check-point e criteri di uscita rigidi. 2. **Tabelle di anti-razionalizzazione:** Ogni skill contiene una sezione dedicata a smontare le "scuse" tipiche degli agenti AI (es. "Aggiungerò i test in un secondo momento" o "Questa modifica è troppo semplice per richiedere una specifica"). L'agente trova la sua stessa scusa confutata direttamente dalle istruzioni di sistema. 3. **La verifica non è negoziabile:** Nessun task può considerarsi concluso con un semplice "sembra corretto". Il flusso termina solo quando l'agente produce prove tangibili del funzionamento (es. log di esecuzione dei test, output di build superati, riscontri a runtime). 4. **Rivelazione progressiva del contesto:** Per evitare il sovraccarico di token (le unità di informazione elaborate dai modelli LLM) e mantenere alte le performance dell'agente, il file `SKILL.md` funge da punto d'ingresso leggero. Le checklist di dettaglio vengono caricate solo ed esclusivamente quando l'agente ne ha effettivo bisogno. ## Eredità e cultura ingegneristica L'intero impianto teorico e pratico di Agent Skills eredita direttamente i principi della cultura ingegneristica di Google, ampiamente documentata nel celebre testo _"Software Engineering at Google"_ e nelle guide interne di sviluppo rilasciate dal colosso di Mountain View. Nei flussi operativi proposti si ritrovano concetti fondamentali come la **Regola di Beyoncé** ("Se ti piaceva, allora avresti dovuto scriverci un test sopra"), lo sviluppo strettamente basato su modifiche atomiche e tracciabili, l'attenzione maniacale alla rimozione del codice obsoleto e l'approccio "Shift Left" volto a anticipare la sicurezza e i test di carico nelle primissime fasi di sviluppo dell'applicazione, molto prima del deployment finale. ## Punti chiave - Gli agenti di programmazione AI tendono a prendere scorciatoie che minano la qualità del software a lungo termine. - Agent Skills introduce workflow prescrittivi ed evidenze non negoziabili per forzare l'uso delle migliori pratiche industriali. - Le competenze integrano la cultura ingegneristica di Google, tra cui la regola di Beyoncé, la staccionata di Chesterton e la legge di Hyrum. - La scomposizione in fette verticali atomiche assicura commit puliti e riduce l'insorgenza di bug complessi da isolare. ### Il Verdetto della Redazione — 4.9/5 Agent Skills rappresenta una svolta fondamentale per chiunque utilizzi agenti AI nella scrittura di codice in produzione. Trasforma l'interazione con l'agente da un caotico ciclo di prompt-and-fix a un processo ingegneristico rigoroso, ripetibile e sicuro. Consigliato per team di sviluppo e singoli professionisti che puntano alla massima qualità strutturale del software. ## FAQ ### Posso usare queste skill con qualsiasi agente di programmazione? Sì, i file delle skill sono scritti in formato Markdown standard. Sebbene siano ottimizzati per strumenti come Claude Code o Cursor, funzionano con qualunque agente in grado di accettare istruzioni di sistema o file di contesto. ### Che cos'è la regola di Beyoncé citata nelle skill di test? È una regola non scritta nata in Google: se un comportamento del sistema è importante per il business o per la stabilità, deve esistere un test automatico a protezione dello stesso. Se non c'è un test, quel comportamento non è garantito. ### L'uso di queste skill rallenta lo sviluppo dell'agente? Sì, ma solo in termini di tempo di elaborazione puro (token). Il leggero rallentamento iniziale viene ampiamente compensato dall'assenza di bug strutturali, regressioni o riscritture, che di solito richiedono molto più tempo per essere risolti manualmente. ## Fonti e riferimenti 1. [Repository Ufficiale Agent Skills su GitHub](https://github.com/addyosmani/agent-skills) 2. [Software Engineering at Google (SWE Book)](https://abseil.io/resources/swe-book) 3. [Google Engineering Practices Guide](https://google.github.io/eng-practices/) --- *Fonte: [https://ainsights.it/blog/agent-skills-guida-agenti-ai](https://ainsights.it/blog/agent-skills-guida-agenti-ai)*