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.
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 |
| Scrivere la specifica prima del codice |
Pianificare lo sviluppo |
| Scomporre in task atomici e ridotti |
Sviluppare in modo incrementale |
| Implementare una "vertical slice" alla volta |
Dimostrare il funzionamento |
| I test sono l'unica prova di validità |
Revisionare prima del merge |
| Preservare e migliorare la salute del codice |
Semplificare la base codice |
| La chiarezza prevale sull'astuzia algoritmica |
Rilasciare in produzione |
| 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.
- ✓Automazione fluida tra fasi di pianificazione ed esecuzione
- ✓Applicazione rigorosa di standard qualitativi industriali
- ✓Integrazione nativa con i principali strumenti e IDE di mercato
- ✗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
- 1Installazione su Claude CodeEsegui 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.
- 2Configurazione per CursorCopia il contenuto del file `SKILL.md` desiderato all'interno della cartella `.cursor/rules/` del tuo progetto, oppure fai riferimento all'intera directory `skills/`.
- 3Integrazione con Antigravity CLIAggiungi Agent Skills come plugin nativo digitando a terminale il comando: `agy plugin install https://github.com/addyosmani/agent-skills.git`.
- 4Configurazione per Gemini CLIUsa 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.mde l'apposito strumento di sistemaskill.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 |
|---|---|---|
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 |
|---|---|---|
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"). | |
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à. | |
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 |
|---|---|---|
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 |
|---|---|---|
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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 |
|---|---|---|
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. | |
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 |
|---|---|---|
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. | |
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. | |
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. | |
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 |
|---|---|---|
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. | |
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. | |
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. | |
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. | |
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. | |
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): 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): Specialista di QA (Quality Assurance) focalizzato sull'analisi della copertura e sulla definizione delle strategie di test.
security-auditor (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): Esegue audit automatici e analisi dei Core Web Vitals tramite il comando rapido
/webperf.
Checklist di riferimento
references/testing-patterns.md: Esempi pratici di mocking, unit test, test E2E e pattern architetturali per i test.
references/security-checklist.md: Controlli pre-commit per header HTTP, CORS, gestione dei segreti e sanitizzazione degli input.
references/performance-checklist.md: Target quantitativi per i Core Web Vitals, checklist ottimizzazione frontend/backend e istruzioni di profilazione.
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:
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.
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.
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).
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.mdfunge 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.
Il Verdetto della Redazione
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.
