Come creare una Skill AI e come usarla
Le AI Skill permettono di insegnare a un agente AI come svolgere un determinato lavoro in modo ripetibile.
In pratica, invece di scrivere ogni volta lo stesso prompt, si crea una piccola cartella con un file SKILL.md che contiene istruzioni, regole ed eventualmente script, documentazione o altri file.
Il formato è oggi basato su uno standard aperto chiamato Agent Skills. La specifica definisce una struttura semplice e pensata per essere utilizzabile da diversi agenti AI.
Che cos’è una Skill?
Una Skill è una cartella che contiene almeno:
my-skill/
└── SKILL.mdPuò anche contenere file aggiuntivi:
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/SKILL.md contiene due elementi principali:
- Metadati YAML, che spiegano alla AI che cos’è la Skill e quando usarla.
- Istruzioni Markdown, cioè quello che l’agente deve fare quando la Skill è attivata.
Perché usare una Skill?
Immaginiamo di chiedere ogni giorno a un agente:
Cerca informazioni su una nuova tecnologia, controlla le fonti ufficiali, confronta i dati e scrivi un articolo breve in italiano.
Invece di ripetere tutto ogni volta, possiamo trasformare questa procedura in una Skill.
Da quel momento l’agente può riconoscere richieste simili e caricare automaticamente le istruzioni.
Questo è uno dei concetti più importanti delle Skills: le istruzioni complete non devono essere sempre presenti nel contesto.
L’agente normalmente vede prima solo il nome e la descrizione della Skill. Quando considera la Skill utile per il lavoro richiesto, carica il contenuto completo. Le risorse aggiuntive vengono caricate solo quando servono. Questo meccanismo viene chiamato progressive disclosure.
Skill, Prompt, MCP e Plugin: qual è la differenza?
| TecnologiaA cosa serve | |
|---|---|
| Prompt | Dice alla AI cosa fare in una singola richiesta |
| Skill | Insegna una procedura riutilizzabile |
| MCP | Collega l’agente a strumenti, dati e servizi esterni |
| Plugin | Può distribuire Skills insieme ad altri componenti, come connector o server MCP |
Una Skill quindi non è un nuovo modello AI e normalmente non crea da sola nuovi strumenti.
Per esempio, una Skill può dire:
“Per verificare le informazioni usa le fonti ufficiali e confronta almeno due fonti.”
Ma per visitare realmente un sito serve che l’agente disponga di uno strumento web appropriato.
MCP svolge proprio un ruolo diverso: collega le applicazioni AI a strumenti, API, dati e servizi esterni.
Come creare una Skill
Il modo più semplice è creare una cartella e aggiungere SKILL.md.
Per esempio:
ai-research/
└── SKILL.mdIl file può iniziare così:
---
name: ai-research
description: Ricerca informazioni aggiornate su tecnologie, modelli e strumenti AI. Usa questa skill quando l'utente chiede di verificare novità, confrontare prodotti o preparare una ricerca con fonti affidabili.
---Dopo il secondo --- iniziano le istruzioni.
Un esempio:
# AI Research
1. Identifica esattamente l'argomento richiesto.
2. Cerca prima le fonti ufficiali.
3. Controlla la data delle informazioni.
4. Confronta le informazioni importanti con altre fonti affidabili.
5. Non presentare come fatto ciò che non è stato verificato.
6. Riassumi il risultato in modo semplice.
7. Inserisci le fonti utilizzate.Ed è già una Skill funzionante.
La specifica richiede name e description. Il nome deve essere composto da caratteri minuscoli, numeri e trattini, avere massimo 64 caratteri e corrispondere al nome della cartella. La description può avere massimo 1024 caratteri e deve spiegare cosa fa la Skill e quando deve essere utilizzata.
La parte più importante: la description
La description è molto più importante di quanto sembri.
L’agente può utilizzarla per decidere se una Skill è pertinente alla richiesta. Una descrizione troppo generica può fare sì che la Skill non venga utilizzata; una descrizione troppo ampia può farla scattare quando non dovrebbe.
Questa è debole:
description: Aiuta con la ricerca.Questa è molto migliore:
description: Ricerca e verifica informazioni aggiornate su prodotti, aziende, tecnologie e strumenti AI. Usa questa skill quando l'utente chiede una ricerca, un confronto, dati recenti o un articolo basato su fonti affidabili.La regola pratica è:
description = quando usare la Skill
corpo di SKILL.md = come svolgere il lavoro
Come scrivere bene le istruzioni
Una Skill non deve essere un’enciclopedia.
La documentazione ufficiale consiglia di concentrarsi sulle informazioni che l’agente probabilmente non conoscerebbe da solo: procedure specifiche, convenzioni, casi particolari, strumenti da utilizzare e regole del progetto.
Meglio:
## Procedura
1. Leggi il documento.
2. Identifica i dati principali.
3. Controlla eventuali valori mancanti.
4. Produci la tabella finale.piuttosto che:
Un documento è un insieme di informazioni che può
essere rappresentato in diversi formati...La AI sa già cos’è un documento.
Un altro principio importante è dare un comportamento predefinito, invece di presentare dieci alternative equivalenti.
Non mettere tutto dentro SKILL.md
Una Skill può diventare grande.
La soluzione è spostare il materiale dettagliato in file separati:
ai-research/
├── SKILL.md
├── references/
│ ├── sources.md
│ └── writing-style.md
└── scripts/
└── check-sources.pyNel SKILL.md si può indicare:
Per le regole sulle fonti consulta:
references/sources.md
Per lo stile degli articoli consulta:
references/writing-style.mdLa specifica raccomanda di mantenere il file principale sotto circa 500 righe e di spostare il materiale dettagliato nei file di riferimento.
Questo mantiene la Skill più leggera e permette all’agente di caricare le informazioni solo quando servono.
Possiamo aggiungere anche degli script
Una Skill può contenere script Python, Bash o JavaScript.
Per esempio:
my-skill/
├── SKILL.md
└── scripts/
└── validate.pyNel file SKILL.md possiamo dire all’agente di utilizzare:
scripts/validate.pyGli script sono particolarmente utili quando un’operazione deve essere eseguita sempre nello stesso modo o in maniera deterministica.
Un esempio completo
Ecco una Skill semplice per creare articoli tecnologici:
---
name: tech-article
description: Ricerca e prepara brevi articoli in italiano su AI, robotica, software e tecnologia. Usa questa skill quando l'utente chiede di informarsi su una novità tecnologica e trasformarla in un articolo semplice e verificato.
---
# Tech Article
## Ricerca
1. Identifica l'argomento.
2. Controlla prima le fonti ufficiali.
3. Verifica la data delle informazioni.
4. Controlla i dati più importanti con fonti indipendenti quando necessario.
## Scrittura
1. Spiega subito che cos'è la tecnologia.
2. Spiega perché è interessante.
3. Descrivi le funzioni principali.
4. Evita tecnicismi non necessari.
5. Non inventare dati.
6. Mantieni l'articolo breve e facile da leggere.
## Struttura
# Titolo
Breve introduzione.
## Che cos'è?
Spiegazione semplice.
## Come funziona?
Spiegazione del funzionamento.
## Perché è interessante?
Punti principali.
## Fonti
Inserisci le fonti utilizzate.Questa Skill può poi essere migliorata nel tempo sulla base degli errori reali dell’agente.
Come usare una Skill
Esistono due modalità principali.
1. Attivazione automatica
L’agente decide di utilizzare la Skill perché la richiesta corrisponde alla sua description.
Per esempio:
Scrivi un articolo su un nuovo modello AI e verifica prima le fonti ufficiali.
La Skill tech-article potrebbe essere riconosciuta automaticamente.
2. Attivazione manuale
Alcuni strumenti permettono di chiamare direttamente una Skill.
OpenAI indica, per esempio, che in ChatGPT si può selezionare una Skill con @, mentre in Codex si può utilizzare $ e il comando /skills.
Claude Code utilizza invece il comando /nome-skill, per esempio:
/tech-articleDove si installa?
La struttura è standard, ma la posizione della cartella dipende dall’agente.
Per Codex, una Skill locale può essere collocata ad esempio in:
.agents/skills/tech-article/SKILL.mdoppure nella directory personale:
~/.agents/skills/tech-article/SKILL.mdCodex cerca Skills anche in altre posizioni di repository e di sistema.
Claude Code utilizza invece, tra le altre, queste posizioni:
.claude/skills/tech-article/SKILL.mdoppure:
~/.claude/skills/tech-article/SKILL.mdIn VS Code con GitHub Copilot, la documentazione Agent Skills utilizza:
.agents/skills/tech-article/SKILL.mdQuindi il formato può essere condiviso, ma cartelle, comandi e funzioni aggiuntive possono cambiare da un prodotto all’altro.
Oggi si può anche far creare la Skill alla AI
Non è necessario scrivere tutto a mano.
La documentazione OpenAI indica un skill-creator integrato: in ChatGPT Work può essere richiamato con @skill-creator, mentre in Codex con:
$skill-creatorIl creator chiede cosa deve fare la Skill, quando deve essere utilizzata e se deve contenere solamente istruzioni oppure anche script.
Anthropic dispone inoltre di esempi e strumenti per la creazione e valutazione delle Skills nel proprio repository pubblico.
Come capire se una Skill funziona davvero
Creare il file non basta.
Bisogna provarlo con richieste reali.
Per esempio, per una Skill di ricerca possiamo testare:
Deve attivarsi:
Cerca informazioni sull’ultimo modello AI di questa azienda.
Non dovrebbe attivarsi:
Correggi questa email in italiano.
La documentazione ufficiale suggerisce di testare sia richieste che devono attivare la Skill sia richieste simili che non devono attivarla. Per test seri, viene suggerito anche di usare circa 20 query, con esempi positivi e negativi.
Esiste anche uno strumento di riferimento per controllare la struttura:
skills-ref validate ./my-skillche verifica il formato e le convenzioni principali della Skill.
Una Skill non è perfetta al primo tentativo
Il modo migliore per costruirla è:
creare → provare → osservare gli errori → modificare → riprovare
La documentazione Agent Skills raccomanda esplicitamente di partire da un’attività reale, osservare cosa ha funzionato e quali correzioni sono state necessarie, quindi trasformare quel procedimento in una Skill.
Quando l’agente commette continuamente lo stesso errore, quella correzione può diventare una regola della Skill.
Questo rende la Skill sempre più utile senza dover aggiungere enormi quantità di testo.
Attenzione alla sicurezza
Una Skill può contenere script e istruzioni che fanno utilizzare strumenti all’agente.
Per questo bisogna trattare le Skills di terze parti con attenzione, soprattutto quando provengono da repository sconosciuti.
Una Skill che contiene solo istruzioni testuali è una cosa molto diversa da una Skill che può eseguire comandi, modificare file o interagire con servizi esterni.
Gli esempi reali più sofisticati mostrano infatti una forte attenzione a permessi, isolamento, validazione e limiti operativi. La security-audit-skill pubblicata da Cloudflare, per esempio, separa istruzioni, risorse e script e definisce in modo dettagliato i confini delle operazioni consentite.
La regola più semplice da ricordare
Una buona Skill dovrebbe rispondere a tre domande:
Quando deve essere usata?
→ description
Come deve svolgere il lavoro?
→ SKILL.md
Quali risorse deve utilizzare quando servono?
→ references/, scripts/, assets/
La struttura minima rimane quindi incredibilmente semplice:
my-skill/
└── SKILL.mdEd è proprio questa semplicità che rende il formato interessante: una procedura che prima viveva dentro un lungo prompt può diventare un componente riutilizzabile da diversi agenti compatibili con Agent Skills.
In sintesi
Una Skill è un manuale operativo per un agente AI.
Non sostituisce il modello e non è necessariamente uno strumento. Gli insegna invece come affrontare in modo consistente un determinato tipo di lavoro.
Per iniziare basta creare una cartella, aggiungere SKILL.md, scrivere una buona description e definire una procedura chiara. Poi si prova la Skill con richieste reali e la si migliora nel tempo.
Nel 2026 il formato è utilizzato in diversi ambienti, tra cui ChatGPT/Codex, Claude Code e VS Code, anche se le modalità di installazione e le funzioni specifiche possono differire tra piattaforme.