Validatore SKILL.md: controlla il formato Agent Skills online

Un file SKILL.md è il cuore di una skill per agenti AI come Claude Code. Si tratta di un semplice file di testo in formato Markdown, ma con una struttura ben precisa: nella parte superiore troviamo un blocco YAML chiamato frontmatter, mentre sotto ci sono le istruzioni in Markdown che l'agente eseguirà quando attiverà la skill. Il nome del file deve essere esattamente SKILL.md (maiuscole incluse) e va posizionato nella cartella principale della skill.

Il frontmatter contiene i metadati essenziali: il nome della skill, una descrizione breve e altri campi opzionali come la compatibilità o le licenze. Quando un agente cerca una skill adatta a un compito, legge prima questi metadati, in particolare il nome e la descrizione. Solo se la descrizione corrisponde alla richiesta dell'utente, l'agente caricherà il corpo del file per eseguire le istruzioni. Questo significa che anche una skill ben scritta potrebbe non essere mai utilizzata se la descrizione è poco chiara o troppo generica.

Un esempio pratico: immagina di creare una skill per generare un riepilogo di una riunione. Il nome potrebbe essere riepilogo-riunione, la descrizione potrebbe essere "Crea un riepilogo strutturato di una riunione da una trascrizione", e il corpo conterrebbe le istruzioni su come analizzare il testo e formattare l'output. Se la descrizione fosse semplicemente "Genera testo", l'agente potrebbe ignorarla perché troppo vaga.

Il Validatore SKILL.md aiuta proprio a verificare che questi elementi siano corretti e conformi alle specifiche di Agent Skills, evitando errori comuni che potrebbero impedire all'agente di riconoscere o utilizzare la skill.

Il frontmatter di un file SKILL.md è scritto in YAML e deve rispettare regole precise per essere valido. Il Validatore SKILL.md controlla che tutti i campi obbligatori siano presenti e che i valori rispettino i limiti imposti dalla specifica Agent Skills. Ecco una tabella riassuntiva dei campi principali:

Il campo name deve essere scritto in minuscolo, può contenere solo lettere, numeri e trattini singoli (non consecutivi), e non può superare i 64 caratteri. Inoltre, se la skill è contenuta in una cartella, il nome deve corrispondere a quello della cartella. Ad esempio, se la cartella si chiama calcola-iva, il campo name deve essere calcola-iva.

La description è il campo più critico: deve spiegare in modo chiaro e conciso cosa fa la skill e quando usarla. Non può superare i 1024 caratteri, ma il Validatore SKILL.md segnala anche un avviso se è troppo corta (meno di 60 caratteri), perché una descrizione troppo breve rischia di non essere riconosciuta dagli agenti.

I campi opzionali come compatibility (che specifica per quali agenti o versioni è stata progettata la skill) o license (che indica la licenza d'uso) non sono obbligatori, ma se presenti devono rispettare i limiti di lunghezza. Il campo metadata è utile per aggiungere informazioni aggiuntive, come campi specifici di Claude Code (ad esempio model o hooks), che verranno ignorati da altri agenti ma sono validi per Claude Code.

Un errore comune è dimenticare di chiudere correttamente il blocco YAML: il frontmatter deve iniziare e terminare con tre trattini (---). Se manca la chiusura o l'indentazione non è corretta, il Validatore SKILL.md segnalerà un errore di parsing.

La descrizione di una skill è l'elemento che determina se un agente la sceglierà o meno per un compito. Una descrizione efficace deve rispondere a due domande: cosa fa la skill? e quando va usata? Ad esempio, una descrizione come "Genera un report" è troppo generica, mentre "Crea un report finanziario mensile da un file CSV con entrate e uscite" è molto più chiara e specifica.

Il Validatore SKILL.md segnala due tipi di problemi legati alla descrizione: se è troppo lunga (più di 1024 caratteri) o troppo corta (meno di 60 caratteri). Una descrizione troppo corta rischia di non contenere abbastanza informazioni per essere riconosciuta dagli agenti, mentre una troppo lunga potrebbe essere troncata o ignorata. L'ideale è mantenersi tra i 60 e i 200 caratteri.

Un altro suggerimento utile è includere parole chiave che gli utenti potrebbero usare per cercare la skill. Ad esempio, se la skill serve per tradurre testi dall'italiano all'inglese, la descrizione potrebbe essere: "Traduci testi dall'italiano all'inglese, mantenendo il tono formale o informale". In questo modo, se un utente chiede "Traduci questo paragrafo in inglese", l'agente riconoscerà la skill come adatta al compito.

Il Validatore SKILL.md segnala anche un note se la descrizione non contiene frasi come "usa quando" o "utilizza per", che aiutano a chiarire il contesto d'uso. Ad esempio, una descrizione come "Riformatta un documento Word" potrebbe essere migliorata in "Riformatta un documento Word quando vuoi applicare uno stile uniforme ai titoli e ai paragrafi".

Un errore comune è usare descrizioni troppo tecniche o piene di dettagli inutili. Ricorda che la descrizione deve essere letta e compresa rapidamente da un agente AI, quindi è meglio essere diretti e concisi.

Il corpo di un file SKILL.md contiene le istruzioni che l'agente eseguirà quando attiverà la skill. Anche se non ci sono limiti rigidi imposti dalla specifica Agent Skills, il Validatore SKILL.md fornisce alcune linee guida per garantire che la skill sia efficiente e facile da gestire.

La prima raccomandazione riguarda la lunghezza del corpo: è consigliabile mantenersi sotto le 500 linee. Un file troppo lungo può rallentare l'agente e rendere difficile la manutenzione. Se la skill richiede molte istruzioni, è meglio suddividerle in più file e usare riferimenti relativi (ad esempio, references/istruzioni-dettagliate.md).

Un altro aspetto importante è il conteggio dei token. Il Validatore SKILL.md stima il numero di token moltiplicando il numero di caratteri per 0,25 (cioè 4 caratteri per token). Questa stima è approssimativa e può variare a seconda della lingua: ad esempio, per testi in italiano o altre lingue con parole lunghe, il conteggio reale potrebbe essere leggermente diverso. L'obiettivo è mantenersi sotto i 5000 token stimati, per evitare che l'agente debba elaborare troppe informazioni.

Per rendere il corpo più leggibile, è utile usare titoli e sottotitoli in Markdown (ad esempio, ## Istruzioni principali o ### Passo 1). Questo aiuta sia l'agente che gli sviluppatori a navigare il file. Inoltre, è importante evitare riferimenti assoluti a file (come C:\documenti\file.txt) o percorsi troppo profondi (come ../../../cartella/file.md): usa sempre percorsi relativi alla cartella della skill.

Il Validatore SKILL.md segnala anche la presenza di placeholder come TODO o Lorem ipsum, che dovrebbero essere rimossi prima di pubblicare la skill. Questi elementi possono confondere l'agente o portare a risultati imprevisti. Infine, se il corpo contiene meno di 20 parole, il Validatore segnala un avviso, perché potrebbe essere troppo breve per fornire istruzioni utili.

Una delle sfide nello scrivere una skill per agenti AI è garantire la compatibilità tra piattaforme diverse. La specifica Agent Skills definisce una serie di campi standard che tutti gli agenti dovrebbero riconoscere, ma alcune piattaforme, come Claude Code, introducono campi aggiuntivi che estendono le funzionalità. Il Validatore SKILL.md aiuta a distinguere tra questi due tipi di campi.

I campi obbligatori della specifica sono name e description, mentre campi opzionali come compatibility, license e metadata sono riconosciuti da tutti gli agenti. Ad esempio, il campo compatibility può essere usato per specificare che una skill è stata testata solo con una determinata versione di un agente, mentre license indica la licenza d'uso (ad esempio, MIT o Apache 2.0).

Claude Code, invece, supporta campi aggiuntivi come model (per specificare il modello AI da usare), hooks (per definire azioni pre o post-esecuzione) o allowed-tools (per limitare gli strumenti che la skill può utilizzare). Questi campi sono validi solo su Claude Code e verranno ignorati da altri agenti. Il Validatore SKILL.md segnala questi campi come note, per ricordare che la skill potrebbe non funzionare allo stesso modo su altre piattaforme.

Un caso particolare è il campo allowed-tools, che nella specifica Agent Skills è sperimentale e dovrebbe essere una stringa separata da spazi (ad esempio, allowed-tools: calculator web-search). Tuttavia, alcuni sviluppatori lo scrivono come una lista YAML, che il Validatore segnala come warning perché potrebbe non essere supportata da tutti gli agenti.

Se vuoi aggiungere campi personalizzati che non fanno parte della specifica né delle estensioni di Claude Code, è meglio inserirli nel campo metadata. Ad esempio, se vuoi aggiungere un campo author per indicare chi ha creato la skill, puoi scriverlo così:

metadata:
  author: Mario Rossi

In questo modo, il campo non interferirà con il parsing del frontmatter e verrà ignorato dagli agenti che non lo riconoscono.

Il Validatore SKILL.md fornisce un report dettagliato che aiuta a identificare e correggere i problemi nel file SKILL.md. Il report è diviso in tre sezioni principali: verdetto, statistiche e risultati.

Il verdetto indica se il file è valido o meno. Un file è considerato valido solo se non contiene errori: anche se ci sono avvisi o note, la skill può comunque essere utilizzata dagli agenti. Gli errori, invece, impediscono il corretto funzionamento e devono essere corretti.

La sezione statistiche fornisce informazioni utili sul file, come il numero di linee, il numero di caratteri e la stima dei token. Questi dati aiutano a capire se il file rispetta le linee guida sulla dimensione e sulla struttura.

La sezione risultati elenca tutti i problemi trovati, suddivisi in tre categorie:

1. Errori: problemi che impediscono il corretto parsing o l'utilizzo della skill. Ad esempio, un frontmatter non valido, un campo name troppo lungo o una description mancante.
2. Avvisi: problemi che non impediscono il funzionamento, ma potrebbero influire sulle prestazioni o sulla compatibilità. Ad esempio, una descrizione troppo corta, un corpo troppo lungo o la presenza di placeholder.
3. Note: suggerimenti o informazioni aggiuntive. Ad esempio, la presenza di campi specifici di Claude Code o l'uso di allowed-tools come lista YAML.

Ogni problema è accompagnato da una breve spiegazione e, quando possibile, da un suggerimento su come risolverlo. Ad esempio, se il campo name contiene caratteri non validi, il Validatore suggerirà di usare solo lettere minuscole, numeri e trattini singoli.

Il report può essere esportato in formato CSV o come immagine, utile per condividere i risultati con altri sviluppatori o per documentare le modifiche apportate. Tuttavia, è importante ricordare che il Validatore SKILL.md non verifica che i file collegati esistano realmente o che le istruzioni siano di alta qualità: si limita a controllare la conformità alla specifica Agent Skills e a fornire suggerimenti sulle dimensioni e sulla struttura.

Un esempio pratico: se il Validatore segnala un errore per un frontmatter non chiuso correttamente, basterà aggiungere i tre trattini (---) alla fine del blocco YAML. Se invece segnala un avviso per una descrizione troppo corta, sarà sufficiente aggiungere qualche dettaglio in più per renderla più chiara e specifica.

Se hai creato una skill ma l'agente non la utilizza mai, il problema potrebbe essere legato a uno degli errori più comuni che il Validatore SKILL.md aiuta a identificare. Ecco le cause più frequenti e come risolverle.

1. Descrizione troppo vaga o generica: La descrizione è il primo elemento che l'agente legge per decidere se la skill è adatta a un compito. Se è troppo breve (meno di 60 caratteri) o non specifica chiaramente cosa fa la skill e quando usarla, l'agente potrebbe ignorarla. Ad esempio, una descrizione come "Analizza testo" è troppo generica, mentre "Analizza un testo in italiano per estrarre date, nomi e luoghi" è molto più efficace.

1. Errori nel frontmatter: Se il blocco YAML non è valido (ad esempio, manca la chiusura con --- o l'indentazione è scorretta), l'agente non riuscirà a leggere i metadati e la skill verrà scartata. Il Validatore SKILL.md segnala questi errori in modo chiaro, permettendoti di correggerli rapidamente.

1. Nome della skill non valido: Il campo name deve rispettare regole precise: solo lettere minuscole, numeri e trattini singoli, max 64 caratteri. Se contiene spazi, caratteri speciali o trattini consecutivi, l'agente potrebbe non riconoscerlo. Inoltre, se la skill è in una cartella, il nome deve corrispondere a quello della cartella.

1. Corpo troppo lungo o complesso: Se il corpo supera le 500 linee o i 5000 token stimati, l'agente potrebbe avere difficoltà a elaborarlo. In questo caso, è meglio suddividere le istruzioni in più file e usare riferimenti relativi.

1. Campi sconosciuti o mal formattati: Se usi campi non previsti dalla specifica Agent Skills (ad esempio, model o hooks per Claude Code) senza inserirli nel campo metadata, altri agenti potrebbero ignorare la skill. Il Validatore SKILL.md segnala questi campi come note, ricordandoti di spostarli in metadata se vuoi garantire la compatibilità.

1. Placeholder o contenuti temporanei: Se nel corpo ci sono frasi come TODO o Lorem ipsum, l'agente potrebbe eseguire istruzioni incomplete o errate. Il Validatore segnala questi elementi come avvisi, invitandoti a rimuoverli prima di pubblicare la skill.

Un altro problema comune è l'uso di riferimenti assoluti a file (ad esempio, C:\documenti\file.txt), che non funzionano su sistemi diversi. È sempre meglio usare percorsi relativi, come references/file.txt.

Se dopo aver corretto tutti gli errori la skill continua a non essere utilizzata, prova a riformulare la descrizione aggiungendo parole chiave che gli utenti potrebbero usare per attivarla. Ad esempio, se la skill serve per generare un preventivo, la descrizione potrebbe essere: "Crea un preventivo dettagliato da una lista di prodotti e prezzi, quando vuoi inviare una proposta commerciale".