Come scrivere un file SKILL.md

L'intestazione: name e description

• name: obbligatorio, da 1 a 64 caratteri, solo lettere minuscole, numeri e trattini, senza trattini all'inizio, alla fine o doppi. Deve coincidere con il nome della cartella.
• description: obbligatoria, fino a 1.024 caratteri. Dice cosa fa la skill e quando usarla. È l'unica cosa che l'agente legge prima di decidere se attivarla: è la parte più importante.
• Campi facoltativi: license, compatibility (requisiti di ambiente), metadata; alcuni agenti supportano anche un elenco di strumenti pre-autorizzati, in forma sperimentale.

Un esempio completo

---
name: verifica-fattura-elettronica
description: Controlla una fattura elettronica XML (formato FatturaPA) e segnala campi mancanti, totali incoerenti e codici IVA errati. Usala quando l'utente carica un file XML di fattura o chiede di verificarne la correttezza.
license: MIT
---

# Verifica fattura elettronica

## Quando usarla
Quando l'utente fornisce un file .xml di fattura elettronica
o chiede di controllare una fattura prima dell'invio.

## Procedura
1. Esegui `python scripts/valida.py <file.xml>` per il controllo
   strutturale: restituisce un elenco JSON di errori.
2. Ricalcola imponibile, IVA e totale e confrontali con quelli
   dichiarati nel file.
3. Per il significato dei codici natura IVA consulta
   `references/codici-natura.md`.

## Output
Una tabella con: campo, valore trovato, problema, correzione
suggerita. Se non ci sono errori, dillo in una riga.

Il corpo: istruzioni che un collega capirebbe

• Scrivi i passaggi in ordine, all'imperativo, con un esempio di input e di output.
• Spiega il perché delle regole importanti: l'agente le applica meglio quando ne capisce lo scopo.
• Sposta tabelle, elenchi lunghi e documentazione nella cartella references/ e richiamali dalle istruzioni.
• Usa la cartella scripts/ per i calcoli e le operazioni che devono essere esatte: uno script testato è più affidabile di un'istruzione.

Errori comuni

• Descrizione generica («aiuta con le fatture»): l'agente non sa quando attivarla. Indica i segnali concreti: tipo di file, parole della richiesta.
• Skill tuttofare: meglio tre skill piccole e precise che una enorme.
• Dati reali nella skill: niente nomi di clienti, credenziali o chiavi API nei file.
• Script con effetti nascosti: niente chiamate di rete o scritture su file non dichiarate nelle istruzioni.

Prima di pubblicare

1. Prova la skill su almeno tre richieste diverse che dovrebbero attivarla, e su una che non dovrebbe.
2. Rileggi gli script come se li avesse scritti un altro.
3. Scegli una licenza e scrivila nel campo license.