Agent skills: come scrivere skill brevi ed efficaci per gli agenti AI

In pochi mesi le agent skills sono passate da funzionalità di nicchia a standard di fatto. Claude Code, Codex, Gemini e molti altri agenti le supportano, e i repository di skill condivise si moltiplicano su GitHub. Il risultato prevedibile: skill sempre più lunghe, piene di spiegazioni, eccezioni e “nel caso in cui”.

A metà ottobre Matt Pocock ha pubblicato un video dal titolo eloquente, “Your skills are WAY TOO LONG”, in cui invita a tagliare senza pietà. Pochi giorni dopo AICodeKing ha mostrato una skill di appena 8 KB che svolge lo stesso lavoro di un server MCP da 25 MB, più velocemente e a costo inferiore. Il messaggio è chiaro: una skill vale per quanto è precisa, non per quanto è completa.

In questa guida vediamo come funzionano le skill, come scriverne una che l’agente attiva al momento giusto, come strutturarla per non sprecare contesto e come verificare che funzioni davvero.

Per un’azienda le skill sono interessanti per un motivo che va oltre lo sviluppo software: sono il modo in cui le procedure interne, come preparare un’offerta, controllare un contratto o rispondere a un reclamo, diventano istruzioni che un agente segue sempre allo stesso modo. È conoscenza aziendale resa eseguibile.

In breve

• Una skill è una cartella con un file SKILL.md (nome, descrizione, istruzioni) e, se serve, script e documenti di riferimento.
• Le skill si caricano in modo progressivo: all’avvio l’agente vede solo nome e descrizione, il resto solo quando serve.
• La descrizione decide se la skill viene attivata: deve dire cosa fa e quando usarla, con le parole che l’utente userebbe.
• Scrivi solo ciò che il modello non sa già. Spiegazioni generiche sprecano contesto e diluiscono le istruzioni utili.
• Per le operazioni fragili, uno script è meglio di un paragrafo di istruzioni.
• Prima di scrivere la skill, crea tre casi di prova e misura come si comporta l’agente senza.
• Per chi decide: le skill trasformano le procedure aziendali in istruzioni riutilizzabili da qualsiasi agente compatibile. Sono un modo concreto per standardizzare il lavoro e conservare il know-how quando le persone cambiano ruolo.

Che cosa sono le agent skills

Le agent skills sono pacchetti di conoscenza procedurale che un agente carica quando un compito lo richiede. Sono nate in Anthropic e sono poi state rilasciate come standard aperto su agentskills.io, oggi adottato da un numero crescente di agenti e strumenti.

La struttura minima è una cartella con un file:

esportazione-ordini/
├── SKILL.md          # obbligatorio: metadati e istruzioni
├── scripts/          # facoltativo: codice eseguibile
├── references/       # facoltativo: documentazione di dettaglio
└── assets/           # facoltativo: template, risorse

Il file SKILL.md inizia con un’intestazione YAML con due campi obbligatori, name e description, seguita dalle istruzioni in markdown. Le skill vivono nel repository del progetto (condivise con il team) o nella configurazione personale dello sviluppatore.

Anthropic ha spiegato le motivazioni del formato nel post Equipping agents for the real world with Agent Skills: gli agenti sono capaci, ma spesso non hanno il contesto necessario per lavorare in modo affidabile su compiti specifici di un’azienda o di un progetto. Le skill impacchettano quel contesto in cartelle portabili e versionate.

Le skill come patrimonio aziendale

Le skill sono nate per gli sviluppatori, ma il formato funziona per qualsiasi procedura. Anche i divulgatori italiani se ne sono accorti: Vincenzo Cosenza ha dedicato un video alle skill AI per il marketing con ChatGPT e Claude, e il canale IA per tutti ha mostrato come Gemini automatizza il lavoro ripetitivo con le skill.

Esempi per una PMI

• Commerciale: preparare un’offerta secondo il modello aziendale, con listino, condizioni e clausole standard.
• Servizio clienti: rispondere a un reclamo seguendo tono, tempi e politiche di rimborso dell’azienda.
• Amministrazione: controllare una fattura fornitore rispetto all’ordine e al documento di trasporto.
• Marketing: scrivere una scheda prodotto per l’e-commerce con struttura, lunghezza e parole chiave definite.
• Risorse umane: preparare il materiale di inserimento per una nuova persona in base al ruolo.

Perché conviene

• Uniformità: tutti, persone e agenti, seguono la stessa procedura, aggiornata in un solo punto.
• Know-how che resta: le procedure smettono di vivere solo nella testa di chi le conosce meglio.
• Inserimento più rapido: una persona nuova lavora da subito con le procedure dell’azienda, attraverso l’agente.
• Portabilità: il formato è uno standard aperto, quindi le skill non legano l’azienda a un unico fornitore di AI.

Governance

Se le skill diventano procedure aziendali, vanno trattate come tali: un responsabile per ciascuna, una revisione quando cambia la procedura, un controllo prima di installare skill di terzi. Una skill sbagliata viene applicata da tutti, sempre: l’errore si moltiplica come il beneficio.

Come funziona il caricamento progressivo

Il motivo per cui le skill sono più efficienti di un unico lungo file di istruzioni è il caricamento progressivo (progressive disclosure), che avviene in tre fasi:

1. Scoperta: all’avvio l’agente carica solo nome e descrizione di ogni skill disponibile. Poche decine di token ciascuna.
2. Attivazione: quando un compito corrisponde alla descrizione, l’agente legge il SKILL.md completo.
3. Esecuzione: l’agente segue le istruzioni, eseguendo script o leggendo documenti di riferimento solo se necessario.

Questo significa che puoi avere decine di skill installate con un costo minimo in contesto. Ma significa anche che, una volta attivata, ogni riga della skill compete con il resto del contesto: istruzioni del progetto, codice letto, cronologia. È lo stesso principio che abbiamo visto nell’articolo sul context engineering: il contesto è un budget, e una skill lunga lo consuma tutto.

Skill, file di istruzioni, subagent, MCP: quando usare cosa

Gli agenti offrono diversi meccanismi di estensione, e scegliere quello sbagliato è uno degli errori più comuni.

Meccanismo	Quando si carica	Ideale per	Da evitare per
AGENTS.md / CLAUDE.md	Sempre, a ogni sessione	Comandi del progetto, convenzioni valide ovunque	Procedure usate di rado
Skill	Quando il compito corrisponde alla descrizione	Procedure ricorrenti: release, migrazioni, nuovi endpoint, revisioni	Regole sempre valide
Subagent	Quando viene delegato un compito	Esplorazioni e compiti che sporcano il contesto	Istruzioni brevi
Hook	A eventi precisi del ciclo dell’agente	Controlli automatici e deterministici	Conoscenza da interpretare
Server MCP	Le definizioni degli strumenti sono sempre presenti, salvo caricamento differito	Accesso a sistemi esterni con autenticazione: API, database, servizi	Procedure che usano solo strumenti già disponibili

L’ultima riga merita attenzione. Il caso di LeanREA è istruttivo: per fare reverse engineering di applicazioni, il progetto originale usava un server MCP con oltre duecento strumenti. LeanREA lo sostituisce con una skill di 8 KB che dice all’agente quali normali strumenti da riga di comando usare per ogni tipo di file. Nei test dell’autore (pochi, su un solo modello, quindi da prendere con cautela) ha ridotto tempi del 38% e costi del 35% con accuratezza quasi identica. Se l’agente ha già una shell, spesso una skill basta.

Anatomia di una buona SKILL.md

Vediamo un esempio completo, poi analizziamo le scelte.

---
name: creating-api-endpoints
description: Crea un nuovo endpoint REST nel backend seguendo le convenzioni
  del progetto (validazione, permessi, test). Da usare quando l'utente chiede
  un nuovo endpoint, una nuova rotta API o di esporre dati al frontend.
---

# Nuovo endpoint API

## Procedura
1. Genera lo scheletro: `pnpm gen:endpoint nome-risorsa`
2. Definisci lo schema di input con Zod in `schema.ts`. Mai validare a mano.
3. Controlla i permessi con `requireRole()` prima di qualsiasi query.
4. Le query passano da `src/server/repo/`, mai dal file della rotta.
5. Aggiungi almeno: un test con input valido, uno con input invalido (400),
   uno senza permessi (403).
6. Esegui `pnpm check` e correggi finché non passa.

## Errori frequenti in questo progetto
- Le date in risposta sono stringhe ISO in UTC: non formattarle qui.
- La paginazione usa cursori (`?after=`), non offset.

## Riferimenti
- Esempio completo di endpoint: `src/server/routes/ordini/`
- Codici di errore ammessi: [references/errori.md](references/errori.md)

Il nome

La guida alle buone pratiche di Anthropic consiglia nomi in minuscolo, con trattini, massimo 64 caratteri, preferibilmente nella forma “attività in corso” (come creating-api-endpoints). Evita nomi vaghi come helper o utils.

La descrizione

È la parte più importante, perché è l’unica che l’agente vede sempre. Deve rispondere a due domande: cosa fa la skill e quando usarla. Tre regole:

• Usa le parole dell’utente: “nuovo endpoint, nuova rotta API, esporre dati al frontend”. Se l’utente dirà “aggiungi una API per i clienti”, la descrizione deve contenere termini simili.
• Scrivi in terza persona: la descrizione viene inserita nel prompt di sistema. “Crea un endpoint” funziona meglio di “Ti aiuto a creare”.
• Sii specifico: “Aiuta con il backend” non distingue questa skill dalle altre dieci che riguardano il backend.

Il corpo

Nel nostro esempio non c’è una riga che spieghi cos’è un endpoint REST, cos’è Zod o perché i test sono importanti. Il modello lo sa già. Ci sono solo le informazioni specifiche del progetto: quale comando genera lo scheletro, dove stanno le query, quali errori sono già stati commessi. È esattamente ciò che il modello non può sapere.

I riferimenti

I dettagli che servono solo a volte (l’elenco completo dei codici di errore) stanno in un file separato, collegato direttamente dal SKILL.md. La guida di Anthropic raccomanda di tenere i riferimenti a un solo livello di profondità: se un file rimanda a un altro che rimanda a un altro, l’agente rischia di leggerli solo in parte.

Perché le skill lunghe funzionano peggio

Il video di Matt Pocock Your skills are WAY TOO LONG parte da un’osservazione che chiunque abbia scritto skill riconoscerà: la tentazione è aggiungere ogni caso, ogni eccezione, ogni spiegazione. Il risultato sono skill che l’agente segue peggio.

I motivi sono tre.

• Diluizione: in un testo lungo, le istruzioni importanti hanno lo stesso peso di quelle marginali. L’agente non sa quali sono critiche.
• Contesto: ogni riga occupa spazio che servirebbe per il codice e il ragionamento.
• Contraddizioni: più regole scrivi, più è probabile che due regole entrino in conflitto in un caso che non avevi previsto.

La guida di Anthropic indica un limite massimo di 500 righe per il corpo di SKILL.md, ma è un tetto, non un obiettivo. La maggior parte delle skill efficaci che vediamo sta tra 20 e 80 righe. Per ogni paragrafo chiediti: il modello lo sa già? Questo paragrafo vale i token che costa?

Gradi di libertà: istruzioni, pseudocodice o script

Non tutte le procedure richiedono lo stesso livello di precisione. La guida di Anthropic usa un’immagine efficace: un ponte stretto con precipizi ai lati richiede istruzioni esatte; un prato aperto richiede solo una direzione.

Libertà	Forma	Quando	Esempio
Alta	Istruzioni testuali	Più approcci validi, decisioni dipendenti dal contesto	Revisione del codice, analisi di un bug
Media	Template o pseudocodice con parametri	Esiste un modello preferito ma con variazioni	Struttura di un report, nuovo componente
Bassa	Script da eseguire senza modifiche	Operazioni fragili, sequenze obbligate, coerenza critica	Migrazioni del database, release, deploy

Per le operazioni a bassa libertà, uno script è quasi sempre meglio delle istruzioni. È più affidabile del codice generato al volo, non occupa contesto (l’agente lo esegue senza leggerlo) e garantisce lo stesso risultato ogni volta. Uno script ben scritto gestisce gli errori e restituisce messaggi chiari, invece di lasciare all’agente il compito di capire cosa è andato storto.

Skill come flussi di lavoro

Le skill più utili spesso non insegnano una tecnica, ma un flusso: una sequenza di passi con verifiche intermedie. Matt Pocock ne ha pubblicate diverse nel suo repository mattpocock/skills: una per intervistare l’utente prima di iniziare un lavoro, una per implementare una specifica, una per preparare pull request, una per le retrospettive. Nel video New Skills! v1.3 le presenta in dettaglio.

Un altro esempio è pstack, la raccolta di skill di Lauren Tan (poteto), mostrata da AICodeKing nel video Poteto Mode + Claude Code. La skill di debug impone un metodo: riprodurre il problema, scartare le ipotesi smentite dalle prove, scrivere un test che fallisce, fare una correzione piccola, ripetere l’interazione per dimostrare che funziona.

Un pattern comune nei flussi è la checklist copiabile: la skill chiede all’agente di copiare una lista di passi e spuntarli man mano. Sembra banale, ma riduce molto i passi saltati, soprattutto le verifiche finali. Se lavori con le specifiche, una skill di questo tipo è il modo naturale per codificare il flusso descritto nella nostra guida allo spec-driven development.

Come testare una skill

Una skill non testata è un’ipotesi. La guida di Anthropic propone un approccio che chiama sviluppo guidato dalle valutazioni:

1. Individua il problema: fai svolgere all’agente alcuni compiti reali senza la skill e annota dove sbaglia o cosa gli manca.
2. Crea tre scenari di prova che coprano quei problemi.
3. Misura la situazione di partenza: come si comporta l’agente senza skill?
4. Scrivi il minimo indispensabile per superare gli scenari.
5. Ripeti: esegui gli scenari, confronta con la partenza, correggi.

Il secondo passo è quello che quasi tutti saltano, ed è il più importante. Il caso LeanREA lo mostra bene: il modello senza alcuna skill otteneva già 67 punti su 75. Il valore della skill era reale ma più piccolo di quanto sembrasse confrontandola solo con l’alternativa MCP.

Un metodo pratico consigliato da Anthropic: usa una sessione dell’agente per scrivere e migliorare la skill, e una sessione nuova, pulita, per usarla su compiti reali. Osserva dove la seconda sessione sbaglia e porta le osservazioni alla prima. Testa la skill con tutti i modelli che userai: ciò che basta a un modello grande può essere insufficiente per uno piccolo.

Sei skill utili per un team di sviluppo web

Se non sai da dove partire, queste sono le procedure che nei progetti web tornano più spesso e che si prestano bene a diventare skill. Per ognuna indichiamo cosa dovrebbe contenere, non come scriverla parola per parola: ogni progetto ha le sue convenzioni.

• Nuovo endpoint o nuova rotta: comando per generare lo scheletro, dove vanno validazione, permessi e query, quali test sono obbligatori. È l’esempio che abbiamo visto sopra.
• Migrazione del database: lo script da usare, come verificare la migrazione su una copia dei dati, come scrivere la migrazione inversa, cosa non fare mai in produzione. È una procedura a bassa libertà: meglio uno script con controlli che istruzioni in prosa.
• Nuovo componente di interfaccia: dove si trovano i componenti base del design system, come si gestiscono testi e traduzioni, quali controlli di accessibilità eseguire prima di chiudere il lavoro.
• Preparazione di una release: aggiornamento del changelog, versione, controlli finali, comandi di build e verifica dell’ambiente di staging. Una checklist copiabile funziona molto bene qui.
• Analisi di un bug segnalato: riprodurre il problema, raccogliere log e dati, scrivere un test che fallisce prima di correggere. È un flusso a libertà alta, ma con passi obbligatori.
• Revisione di una pull request: cosa controllare nel vostro progetto in particolare (permessi, query, prestazioni, testi), in che ordine e come formulare i commenti.

Sei skill da 30-50 righe ciascuna coprono buona parte del lavoro quotidiano di un team web, e all’avvio pesano sul contesto solo per le loro sei descrizioni.

Errori comuni

Spiegare ciò che il modello sa già

Paragrafi su cos’è un PDF, cos’è una API REST, perché i test sono utili. Costano token e non aggiungono nulla.

Descrizioni vaghe

“Aiuta con i documenti” non verrà mai attivata nel momento giusto, oppure verrà attivata sempre. La descrizione deve contenere i termini concreti della richiesta.

Troppe opzioni

“Puoi usare la libreria A, oppure B, oppure C”. L’agente perde tempo a scegliere. Indica un default e, se serve, un’alternativa per un caso specifico.

Informazioni con scadenza

“Fino ad agosto usa la vecchia API”. Tra tre mesi la skill sarà sbagliata. Descrivi il metodo attuale e sposta quello vecchio in una sezione storica, se proprio serve.

Skill che duplicano il file di istruzioni

Se una regola vale sempre, sta nel file di progetto. Se vale solo per un compito, sta nella skill. Mai in entrambi.

Skill installate da repository pubblici senza leggerle

Una skill può includere script eseguibili e istruzioni che l’agente seguirà con i tuoi permessi. Leggi sempre una skill di terzi prima di installarla, come faresti con una dipendenza.

Portarlo in produzione nel team

• Versiona le skill nel repository del progetto, in modo che tutto il team e tutti gli agenti usino la stessa versione.
• Revisione obbligatoria: una modifica a una skill cambia il comportamento dell’agente per tutti. Passa da pull request come il codice.
• Un responsabile per skill: qualcuno che la tiene aggiornata quando cambiano le convenzioni.
• Portabilità: usa il formato standard di agentskills.io così le skill funzionano anche cambiando agente. OpenAI documenta il supporto in Codex, Anthropic in Claude Code.
• Revisione periodica: ogni trimestre controlla quali skill vengono usate davvero. Quelle mai attivate vanno riscritte o eliminate.

Vuoi trasformare le procedure del tuo team in skill che gli agenti seguono davvero? Nei percorsi di formazione aziendale lavoriamo sulle procedure reali del team, e come partner tecnico per agenzie costruiamo librerie di skill condivise tra progetti.

Da dove partire questa settimana

1. Rileggi il file di istruzioni del progetto e individua le procedure usate solo in alcuni compiti: sono candidate a diventare skill.
2. Scegline una ricorrente e fragile, per esempio la creazione di una migrazione o la preparazione di una release.
3. Prepara tre scenari di prova e osserva come lavora l’agente senza skill.
4. Scrivi una skill di massimo 50 righe che risolva solo i problemi osservati; sposta i dettagli in riferimenti.
5. Testala in una sessione pulita, misura e correggi. Poi condividila con il team tramite pull request.

Checklist per una skill efficace

• Il nome è specifico, in minuscolo, con trattini.
• La descrizione dice cosa fa la skill e quando usarla, con le parole dell’utente.
• Il corpo contiene solo informazioni che il modello non può sapere.
• Il corpo sta sotto le 100 righe; i dettagli sono in file di riferimento.
• I riferimenti sono collegati direttamente da SKILL.md, a un livello di profondità.
• Le operazioni fragili sono affidate a script con errori chiari.
• C’è un default chiaro invece di un elenco di alternative.
• Nessuna informazione legata a date destinate a scadere.
• Esistono almeno tre scenari di prova e un confronto con l’agente senza skill.
• La skill è versionata e ogni modifica passa da revisione.

Domande frequenti

Fonti e approfondimenti

• Agent Skills: standard aperto e specifica
• Anthropic: Skill authoring best practices
• Anthropic Engineering: Equipping agents for the real world with Agent Skills
• Repository ufficiale di skill di esempio
• LeanREA: benchmark skill contro server MCP
• Matt Pocock: raccolta di skill per lo sviluppo

Il tuo team usa gli agenti ma ognuno a modo suo? Raccontaci come lavorate: partiamo dalle procedure che ripetete ogni settimana.