MANUALE COMPLETO – UTILIZZO E CREAZIONE DELLE SKILL

Versione 1.0 — 15 aprile 2026 — Autore: Luca Borio

Indice

Scopo del documento e destinatari
Cos’è una Skill
Quando usare una Skill e quando NO
Struttura ufficiale di una Skill
Il file SKILL.md: YAML frontmatter e corpo Markdown
Campi del frontmatter: guida completa
user-invocable: true – significato e uso
Cartelle opzionali e cosa inserirci
Come funziona il progressive disclosure
Skill vs Prompt vs MCP: confronto pratico
Esempi completi
Checklist qualità prima di distribuire una Skill
Errori comuni da evitare
Appendice A1: Standard e vincoli tecnici
Appendice A2: Note di compatibilità e portabilità
Appendice A3: Suggerimenti per test e manutenzione
Appendice A4: Glossario
Riferimenti ufficiali

1. Scopo del documento e destinatari

1.1 Scopo

Questo manuale fornisce una guida completa e operativa per comprendere, creare, distribuire e manutenere le Agent Skills (di seguito “Skill”). Il documento copre sia gli aspetti concettuali sia quelli tecnici, con esempi concreti e indicazioni pratiche pronte all’uso.

1.2 Destinatari

Product owner e project manager che devono decidere quando creare una Skill
Sviluppatori e tecnici che devono implementare, testare e distribuire le Skill
Power user che utilizzano assistenti AI (GitHub Copilot, Claude Code, Cursor, ecc.) e vogliono personalizzarne il comportamento
Responsabili IT che devono valutare compatibilità, sicurezza e manutenzione

1.3 Prerequisiti

Per seguire gli esempi di questo manuale è utile avere una conoscenza di base di:

Formato YAML (struttura chiave-valore con indentazione)
Markdown (formattazione testo con simboli come #, *, ecc.)
Struttura a cartelle di un filesystem

Non è richiesta esperienza di programmazione, anche se l’appendice tecnica approfondisce aspetti utili per i profili sviluppatore.

2. Cos’è una Skill

2.1 Definizione

Una Skill è un pacchetto di istruzioni, risorse e (opzionalmente) script che permette a un assistente AI di svolgere un compito specifico in modo affidabile e ripetibile. Tecnicamente, è una cartella contenente almeno un file SKILL.md che descrive cosa fa la Skill, quando usarla e come.

2.2 Analogia pratica

Immagina di dover spiegare a un nuovo collega come redigere un report trimestrale. Potresti:

Dargli istruzioni a voce ogni volta (lento, soggetto a errori)
Scrivere una procedura operativa su un documento Word (meglio, ma va cercata ogni volta)
Creare una Skill che l’assistente AI carica automaticamente quando serve (ottimale)

La Skill è l’equivalente digitale di una procedura operativa standardizzata, ma progettata per essere letta e seguita da un agente AI.

2.3 Perché servono le Skill

Ripetibilità: le stesse istruzioni vengono seguite ogni volta, riducendo errori e variabilità
Efficienza: grazie al progressive disclosure, le Skill consumano risorse (token) solo quando servono
Portabilità: lo standard aperto Agent Skills funziona su più piattaforme (GitHub Copilot, Claude Code, Cursor, Gemini CLI, Codex CLI)
Manutenibilità: aggiornare una Skill aggiorna il comportamento dell’AI per tutti gli utenti che la usano
Modularità: ogni Skill è indipendente e può essere aggiunta, rimossa o sostituita senza impattare le altre

2.4 Dove vengono usate

Le Skill sono supportate nativamente dai principali assistenti AI per sviluppatori e knowledge worker:

Piattaforma	Supporto Skill
GitHub Copilot (Cloud, CLI, VS Code)	Completo
Claude Code (Anthropic)	Completo + estensioni proprietarie
Cursor	Base (cartella `.cursor/skills/`)
Gemini CLI	Base (cartella `.gemini/skills/`)
Codex CLI	Base (cartella `.codex/skills/`)
Microsoft Agent Framework	Completo (SDK C#/Python)

(vedi Riferimenti ufficiali – Microsoft e Anthropic per la documentazione di ciascuna piattaforma)

3. Quando usare una Skill e quando NO

3.1 Criteri per creare una Skill

Crea una Skill quando:

Hai una procedura che si ripete frequentemente (es. generare report, validare dati, fare code review)
Le istruzioni sono complesse (più di 10 righe) e richiedono passi precisi
Vuoi che il comportamento sia identico ogni volta, indipendentemente da chi usa l’assistente
Hai bisogno di allegare risorse (template, script, documentazione di riferimento)
Vuoi condividere una procedura standardizzata con il team o l’intera organizzazione

3.2 Quando NON serve una Skill

Non creare una Skill quando:

L’istruzione è breve e generica (es. “usa sempre il tono formale”) → usa CLAUDE.md o le impostazioni del progetto
Hai bisogno di accedere a un’API esterna o a un servizio web → usa un server MCP
La procedura è unica e non verrà mai ripetuta → dai le istruzioni direttamente nella chat
Stai definendo regole globali del progetto (stile codice, comandi di build) → usa AGENTS.md o CLAUDE.md

3.3 Tabella decisionale

Scenario	Strumento consigliato	Motivazione
Regole di stile sempre attive	CLAUDE.md / AGENTS.md	Contesto permanente, sempre in memoria
Procedura complessa ripetibile	Skill (SKILL.md)	Caricata on-demand, con risorse allegate
Accesso ad API/servizi esterni	Server MCP	Integrazione tool con protocollo standard
Istruzione una tantum	Messaggio diretto in chat	Nessuna infrastruttura necessaria
Template + istruzioni + script	Skill (SKILL.md)	Tutto il necessario in un unico pacchetto

4. Struttura ufficiale di una Skill

4.1 Struttura a cartelle

Ogni Skill è una cartella il cui nome deve corrispondere al campo name nel frontmatter YAML. La struttura minima e quella completa sono:

Struttura minima

nome-skill/
├── SKILL.md          # Obbligatorio: metadati + istruzioni

Struttura completa

nome-skill/
├── SKILL.md          # Obbligatorio: metadati + istruzioni
├── scripts/           # Opzionale: codice eseguibile
│   ├── validate.py
│   └── generate.sh
├── references/        # Opzionale: documentazione aggiuntiva
│   ├── REFERENCE.md
│   └── policy.json
└── assets/            # Opzionale: risorse statiche
    ├── template.xlsx
    └── logo.png

(vedi Riferimenti ufficiali – Microsoft per la specifica completa della struttura)

4.2 Convenzioni di naming

Il nome della cartella deve rispettare le seguenti regole, identiche a quelle del campo name nel frontmatter:

Solo lettere minuscole (a-z), numeri (0-9) e trattini (-)
Lunghezza massima: 64 caratteri
Non deve iniziare o terminare con un trattino
Non deve contenere trattini consecutivi (--)
Il nome della cartella deve corrispondere esattamente al campo name

Esempi validi e non validi

Nome	Valido?	Motivo
`expense-report`	Sì	Solo minuscole e trattini
`data-validator-v2`	Sì	Numeri consentiti
`PDF-Processing`	No	Lettere maiuscole non ammesse
`-report-builder`	No	Inizia con trattino
`code--review`	No	Trattini consecutivi
`report_generator`	No	Underscore non ammesso (usare trattino)

4.3 Dove posizionare le Skill

La posizione della cartella Skill dipende dalla piattaforma e dall’ambito (progetto o personale):

Piattaforma	Cartella progetto	Cartella personale
GitHub Copilot	`.github/skills/`, `.claude/skills/`, `.agents/skills/`	`~/.copilot/skills/`, `~/.claude/skills/`
Claude Code	`.claude/skills/`	`~/.claude/skills/`
Codex CLI	`.codex/skills/`	`~/.codex/skills/`
Cursor	`.cursor/skills/`	Non documentata
Gemini CLI	`.gemini/skills/`	Non documentata

Nota: Per massima portabilità, posizionare le Skill nella cartella .claude/skills/ oppure .agents/skills/, riconosciute dalla maggior parte delle piattaforme.

5. Il file SKILL.md: YAML frontmatter e corpo Markdown

5.1 Formato generale

Il file SKILL.md ha due sezioni distinte:

Frontmatter YAML: racchiuso tra due righe --- (tre trattini). Contiene i metadati strutturati della Skill.
Corpo Markdown: tutto il testo dopo il secondo ---. Contiene le istruzioni operative, gli esempi e le spiegazioni.

Esempio di struttura base

---
name: expense-report
description: >
  Crea e valida le note spese secondo la policy aziendale.
  Usare quando si parla di rimborsi, spese o trasferte.
license: Apache-2.0
compatibility: Richiede python3
metadata:
  author: team-finance
  version: "1.0"
---

# Istruzioni per la creazione di note spese

## Passaggi
1. Raccogli i dati della spesa...
2. Verifica i limiti di policy...
3. Genera il documento...

5.2 Best practice per il corpo Markdown

Usa titoli Markdown (##, ###) per strutturare le istruzioni in sezioni chiare
Includi esempi concreti di input e output attesi
Documenta i casi limite e le eccezioni
Mantieni il file sotto 500 righe – sposta i contenuti di dettaglio nella cartella references/
Scrivi le istruzioni come se dovessi formare un collega nuovo: passi chiari, completi, senza ambiguità

Importante: Il limite di 500 righe per SKILL.md è raccomandato sia dallo standard aperto sia da Microsoft e Anthropic. Non esiste un limite ufficiale in byte, ma superare 500 righe degrada le prestazioni perché il contenuto occupa troppo contesto.

6. Campi del frontmatter: guida completa

Questa sezione descrive in dettaglio ciascun campo del frontmatter YAML secondo lo standard aperto Agent Skills (vedi Riferimenti ufficiali – Microsoft).

6.1 name (obbligatorio)

Proprietà	Valore
Obbligatorio	Sì (nello standard). In Claude Code: no, usa il nome della cartella come fallback
Lunghezza massima	64 caratteri
Caratteri consentiti	Lettere minuscole (a-z), numeri (0-9), trattini (-)
Restrizioni	No trattino iniziale/finale; no trattini consecutivi (`--`)
Regola fondamentale	Deve corrispondere esattamente al nome della cartella

Il campo name serve come identificatore univoco della Skill. In Claude Code, diventa anche il comando di invocazione (/nome-skill).

6.2 description (obbligatorio)

Proprietà	Valore
Obbligatorio	Sì (nello standard). In Claude Code: raccomandato (fallback sul primo paragrafo del corpo)
Lunghezza massima (standard/Microsoft)	1.024 caratteri
Lunghezza massima (Claude Code)	1.536 caratteri (sommando `description` + `when_to_use`)
Consiglio pratico	Usare il limite di 1.024 caratteri per massima portabilità

La description deve spiegare sia cosa fa la Skill sia quando usarla. Deve contenere parole chiave che aiutino l’agente AI a riconoscere quando la Skill è pertinente.

Esempio di buona descrizione

description: >
  Genera report trimestrali sulle vendite con grafici, tabelle
  e analisi comparativa anno su anno. Usare quando viene chiesto
  un report vendite, un consuntivo trimestrale o un riepilogo
  delle performance commerciali.

Esempio di descrizione insufficiente

description: Fa i report.

Una descrizione troppo corta impedisce all’AI di capire quando usare la Skill.

6.3 license (opzionale)

Specifica la licenza sotto cui la Skill viene distribuita. Può essere un identificatore SPDX (es. Apache-2.0, MIT) o un riferimento a un file LICENSE nella cartella della Skill.

license: MIT

6.4 compatibility (opzionale)

Proprietà	Valore
Lunghezza massima	500 caratteri
Scopo	Descrive requisiti ambientali: linguaggi, pacchetti, accesso a rete, sistema operativo

compatibility: >
  Richiede python3 con pandas installato.
  Necessita accesso alla rete per API interne.

6.5 metadata (opzionale)

Mappa chiave-valore arbitraria (chiavi e valori devono essere stringhe) per informazioni aggiuntive come autore, versione, tag, team di appartenenza.

metadata:
  author: team-operations
  version: "2.1"
  department: finance
  tags: report, vendite, trimestrale

6.6 allowed-tools (opzionale, sperimentale)

Elenco di tool (strumenti) che la Skill è pre-autorizzata a usare, senza richiedere conferma all’utente. Accetta una lista separata da spazi oppure un array YAML.

Importante: Questo campo è sperimentale: il supporto varia tra le piattaforme. Non limita i tool disponibili, ma pre-approva quelli elencati. (vedi Riferimenti ufficiali – Microsoft)

# Formato stringa (separata da spazi)
allowed-tools: Read Write Bash

# Formato array YAML
allowed-tools:
  - Read
  - Write
  - Bash

6.7 Riepilogo dei limiti ufficiali

Campo	Standard aperto	Microsoft	Claude Code	Consiglio portabilità
`name`	Max 64 car., a-z 0-9 –	Max 64 car.	Max 64 car. (opzionale)	Usare max 64 car., sempre minuscolo
`description`	Max 1.024 car.	Max 1.024 car.	Troncata a 1.536 car. (con `when_to_use`)	Usare max 1.024 car.
`compatibility`	Max 500 car.	Max 500 car.	Max 500 car.	Usare max 500 car.
SKILL.md	Sotto 500 righe	Sotto 500 righe	Sotto 500 righe	Usare max 500 righe
Dimensione file	Non specificata	Non specificata	Non specificata	Mantenersi sotto 500 righe

Nota: Quando i limiti differiscono tra piattaforme, usare sempre il limite più restrittivo per garantire portabilità. In pratica: max 64 caratteri per name, max 1.024 caratteri per description, max 500 righe per SKILL.md.

7. user-invocable: true – significato e uso

7.1 Cos’è user-invocable

Il campo user-invocable è un’estensione proprietaria di Claude Code che controlla se una Skill appare nel menu dei comandi / (slash commands) dell’utente.

Valore	L’utente può invocarla?	L’AI la invoca da sola?	Visibile nel menu /?
`true` (default)	Sì	Sì	Sì
`false`	No	Sì	No
(campo assente)	Sì	Sì	Sì

7.2 Quando usare user-invocable: false

Imposta user-invocable: false quando la Skill contiene conoscenza di background che l’AI deve usare autonomamente, senza che l’utente debba (o possa) invocarla manualmente. Esempi tipici:

Policy aziendali che l’AI deve applicare automaticamente quando rileva il contesto giusto
Regole di validazione che devono essere applicate ogni volta che si modifica un certo tipo di file
Istruzioni di sicurezza che devono essere sempre attive in certi contesti

7.3 Quando usare user-invocable: true (o lasciare il default)

Lascia il valore predefinito (true, o non specificare il campo) quando:

La Skill è una procedura che l’utente vuole avviare consapevolmente (es. /genera-report)
La Skill ha bisogno di input dell’utente per funzionare
Vuoi che la Skill sia visibile e scopribile nel menu dei comandi

7.4 Interazione con disable-model-invocation

Claude Code offre anche il campo disable-model-invocation che funziona come “opposto” parziale:

Combinazione	Utente invoca	AI invoca	Caso d’uso
(default)	Sì	Sì	Skill standard
`user-invocable: false`	No	Sì	Conoscenza di background per l’AI
`disable-model-invocation: true`	Sì	No	Solo su richiesta esplicita dell’utente

7.5 Compatibilità tra piattaforme

Importante: Il campo user-invocable NON fa parte dello standard aperto Agent Skills (agentskills.io). È un’estensione specifica di Claude Code. Altre piattaforme (GitHub Copilot, Cursor, Gemini CLI) lo ignoreranno silenziosamente. Il concetto esiste anche in VS Code agent mode per i file .agent.md, ma con implementazione diversa. (vedi Riferimenti ufficiali – Anthropic)

Se includi user-invocable nel frontmatter per Claude Code, non causerai errori sulle altre piattaforme: il campo verrà semplicemente ignorato. È quindi sicuro includerlo anche in Skill multi-piattaforma.

8. Cartelle opzionali e cosa inserirci

8.1 scripts/ – Codice eseguibile

La cartella scripts/ contiene codice che l’agente AI può eseguire durante l’uso della Skill. I formati supportati dipendono dalla piattaforma, ma le estensioni standard sono:

Estensione	Linguaggio	Note
`.py`	Python	Il più comune; preferire script self-contained
`.js`	JavaScript/Node.js	Per manipolazione dati e generazione file
`.sh`	Bash	Per automazioni di sistema (Linux/macOS)
`.ps1`	PowerShell	Per ambienti Windows

Best practice per gli script

Ogni script deve essere autocontenuto (non dipendere da variabili d’ambiente non documentate)
Includere messaggi di errore chiari e leggibili
Documentare gli argomenti attesi (es. con commenti in testa al file)
Se lo script ha dipendenze, elencarle nel campo compatibility del frontmatter

Esempio di script Python

# scripts/validate_expense.py
"""Valida una nota spese secondo la policy aziendale."""
import sys, json

def validate(data):
    errors = []
    if data['amount'] > 500:
        errors.append("Importo sopra il limite: serve approvazione dirigente")
    if not data.get('receipt'):
        errors.append("Ricevuta mancante")
    return errors

if __name__ == "__main__":
    data = json.loads(sys.argv[1])
    errors = validate(data)
    if errors:
        for e in errors: print(f'ERRORE: {e}')
        sys.exit(1)
    print("Validazione superata")

8.2 references/ – Documentazione aggiuntiva

La cartella references/ contiene documentazione supplementare caricata on-demand dall’agente AI solo quando necessaria. Questo è il cuore del progressive disclosure: le informazioni dettagliate non vengono caricate all’inizio, ma solo quando servono.

Cosa mettere in references/

REFERENCE.md – documentazione estesa sulle procedure
File JSON/YAML con configurazioni o policy
Specifiche tecniche, diagrammi testuali, regole di business

Esempio

references/
├── REFERENCE.md       # Dettagli completi della procedura
├── policy.json        # Limiti di spesa per categoria
└── faq.md             # Domande frequenti e risposte

Nota: Mantenere ogni file in references/ focalizzato su un singolo argomento per minimizzare il consumo di contesto. Un file grande e generico vanifica il vantaggio del progressive disclosure.

8.3 assets/ – Risorse statiche

La cartella assets/ contiene risorse statiche: template, immagini, file di dati, schemi. Questi file non vengono “letti” per il loro contenuto testuale ma usati come input o output di operazioni.

Cosa mettere in assets/

Template di documenti (Word, Excel, PowerPoint)
Immagini e loghi da inserire nei documenti generati
File di dati di esempio o di configurazione
Schemi JSON per la validazione

Esempio

assets/
├── template-report.xlsx     # Template Excel per report
├── logo-aziendale.png       # Logo da inserire nei documenti
└── schema-spese.json        # Schema di validazione JSON

9. Come funziona il progressive disclosure

9.1 Il problema del contesto limitato

Ogni assistente AI lavora con una “finestra di contesto” limitata: la quantità di testo che può tenere in memoria durante una conversazione. Caricare tutte le Skill disponibili all’inizio di ogni sessione consumerebbe rapidamente questa risorsa, lasciando poco spazio per la conversazione effettiva.

9.2 La soluzione: caricamento a stadi

Il progressive disclosure risolve il problema caricando le informazioni in quattro stadi successivi, ciascuno con un budget di token dedicato:

Stadio	Budget token	Cosa viene caricato	Quando
1. Advertise (Annuncio)	~100 token per Skill	Solo nome e descrizione di ogni Skill	Sempre, all’inizio di ogni sessione
2. Load (Caricamento)	< 5.000 token (raccomandato)	Contenuto completo di SKILL.md	Quando l’AI rileva che la Skill è pertinente
3. Read Resources (Risorse)	Secondo necessità	File dalla cartella `references/`	Solo quando servono dettagli aggiuntivi
4. Run Scripts (Esecuzione)	Secondo necessità	Script dalla cartella `scripts/`	Solo quando serve eseguire codice

9.3 Esempio pratico

Supponiamo di avere 20 Skill installate. Ecco cosa succede:

Inizio sessione: L’AI riceve la lista delle 20 Skill (20 × ~100 token = ~2.000 token). Sa cosa c’è a disposizione.
L’utente chiede un report vendite: L’AI riconosce che la Skill “sales-report” è pertinente e carica il suo SKILL.md completo (~3.000 token aggiuntivi).
L’AI ha bisogno del template: Legge il file assets/template-report.xlsx.
L’AI genera il report: Esegue lo script scripts/generate_report.py.

Le altre 19 Skill hanno consumato solo ~1.900 token totali (le loro brevi descrizioni) e non hanno impattato sulla capacità dell’AI.

9.4 Motivazione architetturale

Il progressive disclosure è la ragione per cui le Skill hanno limiti precisi:

description max 1.024 caratteri: lo stadio Advertise deve restare sotto ~100 token per Skill
SKILL.md max 500 righe: lo stadio Load deve restare sotto ~5.000 token
references/ con file separati: lo stadio Read Resources carica solo ciò che serve

Violare questi limiti non causa errori ma degrada le prestazioni: più token consuma una Skill, meno spazio resta per le altre Skill e per la conversazione dell’utente. (vedi Riferimenti ufficiali – Microsoft)

9.5 Comportamento post-compattazione (Claude Code)

In Claude Code, quando la conversazione si avvicina al limite di contesto, avviene una compattazione automatica. Dopo la compattazione:

Viene ri-allegato il contenuto delle Skill invocate più di recente
Di ciascuna Skill vengono mantenuti i primi 5.000 token
Il budget combinato per tutte le Skill ri-allegate è di 25.000 token
Le Skill più vecchie possono essere eliminate se il budget si esaurisce

(vedi Riferimenti ufficiali – Anthropic)

10. Skill vs Prompt vs MCP: confronto pratico

10.1 Tabella comparativa

Caratteristica	Prompt / CLAUDE.md	Skill (SKILL.md)	Server MCP
Tipo di contenuto	Regole, preferenze, fatti	Procedure, playbook, checklist	Integrazioni con tool/API esterni
Quando viene caricato	Sempre (inizio sessione)	On-demand (quando serve)	Quando il server è connesso
Costo in contesto	Costante (sempre in memoria)	Quasi zero fino all’uso	Per singola chiamata
Come si invoca	Passivo (sempre presente)	`/nome-skill` o auto-rilevamento	L’AI chiama il tool via `tool_use`
Portabilità	Specifico per piattaforma	Cross-platform (standard aperto)	Cross-platform (standard MCP)
Risorse allegate	No	Sì (`scripts/`, `references/`, `assets/`)	Definite dal server
Quando usare	Regole sempre attive	Procedure ripetibili	Accesso a dati/servizi esterni

10.2 Esempi pratici di scelta

Esempio A: Stile di comunicazione

Esigenza: “Tutte le email devono avere tono formale e firmate con il ruolo del mittente.”

Soluzione: CLAUDE.md / prompt di sistema. È una regola sempre attiva, non una procedura.

Esempio B: Generazione report trimestrale

Esigenza: “Ogni trimestre devo generare un report vendite con template standard, dati dal CRM e grafici comparativi.”

Soluzione: Skill. Contiene le istruzioni passo-passo, il template in assets/ e lo script di generazione in scripts/.

Esempio C: Accesso ai dati CRM

Esigenza: “L’AI deve poter leggere i dati aggiornati dal nostro CRM Salesforce.”

Soluzione: Server MCP. L’accesso ad API esterne richiede un’integrazione tool, non semplici istruzioni.

Esempio D: Procedura di code review

Esigenza: “Ogni code review deve seguire la nostra checklist di 30 punti con riferimento alla guida di stile interna.”

Soluzione: Skill. La checklist va nel corpo di SKILL.md, la guida di stile completa in references/.

11. Esempi completi

Di seguito tre esempi completi di Skill, dalla struttura cartelle al file SKILL.md fino alle indicazioni di invocazione.

11.1 Esempio 1: report-vendite (Skill semplice)

Struttura cartelle

report-vendite/
└── SKILL.md

File SKILL.md completo

---
name: report-vendite
description: >
  Genera un report di vendite mensile in formato tabellare con totali
  e variazioni percentuali rispetto al mese precedente. Usare quando
  viene chiesto un "report vendite", "riepilogo mensile vendite"
  o "consuntivo commerciale".
license: MIT
metadata:
  author: team-sales
  version: "1.0"
---

# Report Vendite Mensile

## Obiettivo
Generare un report vendite mensile strutturato e leggibile.

## Dati richiesti
- Periodo di riferimento (mese/anno)
- Dati vendite per prodotto o area geografica
- Dati del mese precedente per il calcolo delle variazioni

## Struttura del report
1. **Intestazione**: titolo, periodo, data generazione
2. **Tabella principale**: prodotto, vendite mese corrente,
   vendite mese precedente, variazione %
3. **Riga totali**: somma vendite e variazione % complessiva
4. **Note**: eventuali anomalie o commenti

## Regole di calcolo
- Variazione % = ((corrente - precedente) / precedente) * 100
- Arrotondare a 1 decimale
- Evidenziare variazioni negative con nota esplicativa

## Formato output
- Tabella Markdown per visualizzazione in chat
- Se richiesto file, generare come foglio Excel (.xlsx)

Invocazione

Manuale: l’utente digita /report-vendite nella chat
Automatica: l’AI riconosce frasi come “fammi il report vendite di marzo” e carica la Skill

11.2 Esempio 2: data-validator (Skill con script)

Struttura cartelle

data-validator/
├── SKILL.md
├── scripts/
│   └── validate.py
└── references/
    └── validation-rules.md

File SKILL.md completo

---
name: data-validator
description: >
  Valida file CSV e JSON secondo regole di business configurabili.
  Segnala errori con riga/colonna, tipo e suggerimento di correzione.
  Usare quando l'utente carica dati da validare o chiede un controllo
  qualità sui dati.
compatibility: Richiede python3 con pandas
allowed-tools: Bash Read
metadata:
  author: team-data
  version: "2.0"
---

# Validazione Dati

## Quando usare questa Skill
- L'utente carica un file CSV o JSON e chiede di verificarlo
- L'utente menziona "validazione", "controllo dati", "data quality"

## Procedura
1. Identificare il file da validare (chiedere se non chiaro)
2. Caricare le regole da references/validation-rules.md
3. Eseguire: python scripts/validate.py <file>
4. Presentare i risultati in formato tabellare:
   - Riga | Colonna | Errore | Suggerimento
5. Proporre correzioni automatiche se possibile

## Regole base (sempre applicate)
- Nessun campo obbligatorio vuoto
- Formati data coerenti (ISO 8601)
- Valori numerici entro i range definiti
- Nessun duplicato nelle colonne chiave

## Regole avanzate
Vedere references/validation-rules.md per le regole specifiche
per dominio.

File scripts/validate.py (estratto)

#!/usr/bin/env python3
"""Valida file CSV/JSON secondo le regole di business."""
import sys, csv, json

def validate_csv(filepath):
    errors = []
    with open(filepath) as f:
        reader = csv.DictReader(f)
        for i, row in enumerate(reader, start=2):
            for col, val in row.items():
                if val is None or val.strip() == '':
                    errors.append({
                        'row': i, 'col': col,
                        'error': 'Campo vuoto',
                        'fix': 'Compilare il campo obbligatorio'
                    })
    return errors

if __name__ == "__main__":
    filepath = sys.argv[1]
    errors = validate_csv(filepath)
    if errors:
        print(f'Trovati {len(errors)} errori:')
        for e in errors:
            print(f"  Riga {e['row']}, {e['col']}: {e['error']}")
        sys.exit(1)
    print('Validazione superata: nessun errore.')

File references/validation-rules.md (estratto)

# Regole di validazione per dominio

## Dati finanziari
- Importi: sempre positivi, max 2 decimali
- Valuta: deve essere un codice ISO 4217 valido
- Date: formato YYYY-MM-DD

## Dati anagrafici
- Email: formato valido (contiene @ e dominio)
- Codice fiscale: 16 caratteri alfanumerici
- Telefono: prefisso internazionale obbligatorio

Invocazione

Manuale: l’utente digita /data-validator e allega il file
Automatica: l’AI riconosce “valida questo CSV” e carica la Skill

11.3 Esempio 3: code-reviewer (Skill avanzata con references)

Struttura cartelle

code-reviewer/
├── SKILL.md
├── scripts/
│   └── lint-check.sh
├── references/
│   ├── style-guide.md
│   └── security-checklist.md
└── assets/
    └── review-template.md

File SKILL.md completo

---
name: code-reviewer
description: >
  Esegue code review strutturate seguendo la guida di stile aziendale
  e la checklist di sicurezza. Produce un report con severità,
  posizione nel codice e suggerimento di fix. Usare quando l'utente
  chiede una review, un controllo del codice o una verifica di
  sicurezza sul codice.
compatibility: Richiede bash e shellcheck per script .sh
allowed-tools: Read Grep Bash
metadata:
  author: team-engineering
  version: "3.1"
  scope: backend
---

# Code Review Strutturata

## Procedura di review

### Fase 1: Analisi preliminare
1. Leggere tutti i file modificati (usare Read)
2. Identificare il linguaggio e il contesto
3. Caricare la guida di stile: references/style-guide.md

### Fase 2: Controllo automatico
4. Eseguire scripts/lint-check.sh se sono presenti script
5. Annotare tutti i warning e gli errori

### Fase 3: Review manuale
6. Verificare ogni punto di references/security-checklist.md
7. Controllare leggibilità, naming, struttura del codice
8. Verificare che i test coprano i casi critici

### Fase 4: Report
9. Usare il template da assets/review-template.md
10. Classificare ogni finding:
    - **CRITICO**: blocca il merge
    - **IMPORTANTE**: da correggere, non blocca
    - **SUGGERIMENTO**: miglioramento opzionale
11. Per ogni finding indicare: file, riga, problema, fix

## Tono della review
- Costruttivo e professionale
- Spiegare il PERCHÉ, non solo il COSA
- Riconoscere le parti fatte bene

Invocazione

Manuale: l’utente digita /code-reviewer
Automatica: l’AI riconosce “fammi una review di questo codice” e carica la Skill
Differenza chiave: questa Skill sfrutta tutte e tre le cartelle opzionali (scripts/, references/, assets/), dimostrando il progressive disclosure in azione: le istruzioni in SKILL.md vengono caricate per prime, poi le references e gli assets solo quando serve.

12. Checklist qualità prima di distribuire una Skill

Prima di condividere una Skill con i colleghi, verificare tutti i punti seguenti:

#	Controllo	Criterio
1	Nome valido	Solo a-z, 0-9, trattini. Max 64 char. Corrisponde alla cartella.
2	Descrizione efficace	Spiega cosa fa E quando usarla. Max 1.024 char.
3	SKILL.md sotto 500 righe	Contenuti dettagliati spostati in `references/`.
4	Frontmatter YAML valido	Nessun errore di sintassi. Testare con un parser YAML.
5	Script funzionanti	Ogni script in `scripts/` è stato testato manualmente.
6	Dipendenze documentate	Se servono tool/librerie, sono elencate in `compatibility`.
7	Istruzioni chiare	Un collega può capire la procedura senza spiegazioni aggiuntive.
8	Esempi inclusi	Almeno un esempio di input/output nel corpo Markdown.
9	Nessun dato sensibile	Nessuna password, token API, dato personale nel file.
10	Percorsi relativi	Tutti i riferimenti a file usano percorsi relativi (`references/file.md`).
11	Portabilità testata	Se multi-piattaforma: solo campi standard nel frontmatter.
12	Versione aggiornata	Il campo `metadata.version` riflette la versione corrente.

13. Errori comuni da evitare

Di seguito i 12 errori più frequenti nella creazione e nell’uso delle Skill, con sintomo, conseguenza e correzione.

Errore 1: Nome con lettere maiuscole o underscore

Aspetto	Dettaglio
Sintomo	La Skill non viene riconosciuta o il validatore segnala errore
Conseguenza	La Skill non appare nella lista dei comandi / non viene mai caricata
Correzione	Usare solo lettere minuscole, numeri e trattini. Es: `report-vendite`, non `Report_Vendite`

Errore 2: Nome cartella diverso dal campo name

Aspetto	Dettaglio
Sintomo	La Skill viene ignorata silenziosamente
Conseguenza	L’AI non trova la Skill; nessun errore visibile
Correzione	Assicurarsi che il nome della cartella sia identico al valore di `name` nel frontmatter

Errore 3: Descrizione troppo generica

Aspetto	Dettaglio
Sintomo	L’AI non invoca la Skill quando dovrebbe
Conseguenza	La Skill viene ignorata anche in contesti pertinenti
Correzione	Scrivere una descrizione che spiega cosa fa E quando usarla, con parole chiave specifiche

Errore 4: SKILL.md troppo lungo (oltre 500 righe)

Aspetto	Dettaglio
Sintomo	L’AI rallenta, perde il filo della conversazione, risponde in modo impreciso
Conseguenza	Consumo eccessivo di token, possibile troncamento del contenuto della Skill
Correzione	Spostare dettagli in `references/`, mantenere SKILL.md focalizzato sulle istruzioni essenziali

Errore 5: YAML frontmatter con errori di sintassi

Aspetto	Dettaglio
Sintomo	La Skill non viene caricata; possibile errore di parsing
Conseguenza	La Skill è completamente non funzionante
Correzione	Verificare la sintassi YAML: indentazione con spazi (non tab), valori stringa tra virgolette se contengono caratteri speciali

Errore 6: Percorsi assoluti invece di relativi

Aspetto	Dettaglio
Sintomo	I file referenziati non vengono trovati su altre macchine o piattaforme
Conseguenza	La Skill funziona solo sulla macchina dell’autore
Correzione	Usare percorsi relativi dalla root della Skill: `references/file.md`, non `/home/user/skills/mia-skill/references/file.md`

Errore 7: Usare campi estensione credendoli standard

Aspetto	Dettaglio
Sintomo	Campi come `user-invocable` o `when_to_use` non funzionano su GitHub Copilot o Cursor
Conseguenza	Comportamento diverso da quello atteso su piattaforme diverse da Claude Code
Correzione	Sapere quali campi sono standard (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`) e quali sono estensioni. Documentare le estensioni come “solo per Claude Code”

Errore 8: Script con dipendenze non documentate

Aspetto	Dettaglio
Sintomo	Lo script fallisce con errore “ModuleNotFoundError” o simile
Conseguenza	La Skill non può completare la procedura
Correzione	Elencare tutte le dipendenze nel campo `compatibility`. Esempio: “Richiede python3 con pandas e openpyxl”

Errore 9: Dati sensibili nel repository della Skill

Aspetto	Dettaglio
Sintomo	Password, token API, dati personali visibili nel codice della Skill
Conseguenza	Rischio di sicurezza grave; violazione potenziale delle normative sulla privacy
Correzione	Mai includere segreti nel file SKILL.md o negli script. Usare variabili d’ambiente o file di configurazione esterni non inclusi nella Skill

Errore 10: Nessun esempio nel corpo Markdown

Aspetto	Dettaglio
Sintomo	L’AI interpreta le istruzioni in modo troppo libero o impreciso
Conseguenza	Output non conforme alle aspettative, necessità di correzioni manuali
Correzione	Includere almeno un esempio concreto di input e output attesi nel corpo di SKILL.md

Errore 11: Confondere Skill e MCP

Aspetto	Dettaglio
Sintomo	Si crea una Skill per accedere a un’API esterna, ma non funziona
Conseguenza	La Skill non può effettuare chiamate di rete o accedere a servizi esterni
Correzione	Per integrazioni con API/servizi esterni, usare un server MCP. Le Skill contengono istruzioni e risorse locali, non connessioni a servizi

Errore 12: Non testare la Skill prima della distribuzione

Aspetto	Dettaglio
Sintomo	I colleghi segnalano errori, comportamenti inattesi o istruzioni incomplete
Conseguenza	Perdita di tempo per tutto il team, sfiducia nello strumento
Correzione	Testare sempre la Skill in un ambiente di sviluppo. Verificare: parsing YAML, invocazione manuale (`/nome`), invocazione automatica (frase naturale), esecuzione degli script

Appendice A1: Standard e vincoli tecnici

A1.1 Lo standard aperto Agent Skills

Lo standard Agent Skills è mantenuto su agentskills.io ed è nato dal repository open-source anthropics/skills. Definisce un formato portabile e basato su filesystem per impacchettare competenze di dominio in directory che gli assistenti AI possono scoprire e utilizzare.

A1.2 Riepilogo dei vincoli

Vincolo	Valore	Fonte
Lunghezza campo `name`	1–64 caratteri	Standard aperto (vedi Rif. uff. – Microsoft)
Set caratteri `name`	a-z, 0-9, – (no inizio/fine trattino, no `--`)	Standard aperto
Lunghezza `description`	1–1.024 caratteri	Standard aperto
Lunghezza `compatibility`	Max 500 caratteri	Standard aperto
Righe SKILL.md	Raccomandato < 500 righe	Standard aperto, Microsoft, Anthropic
Budget Advertise	~100 token per Skill	Microsoft Agent Framework
Budget Load	< 5.000 token raccomandati	Microsoft Agent Framework
Budget post-compattazione (Claude Code)	5.000 token/Skill, 25.000 totali	Claude Code docs (vedi Rif. uff. – Anthropic)
Profondità ricerca cartelle (MS)	2 livelli	Microsoft Agent Framework

A1.3 Campi frontmatter: standard vs estensioni

Campo	Standard aperto	Claude Code
`name`	Obbligatorio	Opzionale (fallback su nome cartella)
`description`	Obbligatorio	Raccomandato (fallback su primo paragrafo)
`license`	Opzionale	Opzionale
`compatibility`	Opzionale	Opzionale
`metadata`	Opzionale	Opzionale
`allowed-tools`	Opzionale (sperimentale)	Opzionale (stringa o lista YAML)
`when_to_use`	NON presente	Estensione Claude Code
`user-invocable`	NON presente	Estensione Claude Code
`disable-model-invocation`	NON presente	Estensione Claude Code
`context`	NON presente	Estensione Claude Code
`model`	NON presente	Estensione Claude Code
`effort`	NON presente	Estensione Claude Code
`hooks`	NON presente	Estensione Claude Code
`paths`	NON presente	Estensione Claude Code
`shell`	NON presente	Estensione Claude Code
`argument-hint`	NON presente	Estensione Claude Code
`agent`	NON presente	Estensione Claude Code

Appendice A2: Note di compatibilità e portabilità

A2.1 Cosa è portabile

I seguenti elementi funzionano su tutte le piattaforme che supportano lo standard Agent Skills:

Il formato SKILL.md (frontmatter YAML + corpo Markdown)
I sei campi standard: name, description, license, compatibility, metadata, allowed-tools
La struttura a cartelle (scripts/, references/, assets/)
Il pattern di progressive disclosure

A2.2 Cosa NON è portabile

I seguenti elementi sono specifici di Claude Code e vengono ignorati dalle altre piattaforme:

I campi estensione (when_to_use, user-invocable, disable-model-invocation, context, model, effort, hooks, paths, shell, argument-hint, agent)
Le variabili di sostituzione ($ARGUMENTS, ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR})
L’iniezione dinamica di contesto (sintassi !`comando`)

A2.3 Consiglio pratico per la portabilità

Se la Skill deve funzionare su più piattaforme:

Usare solo i sei campi standard nel frontmatter
Non usare variabili di sostituzione o iniezione di contesto nel corpo
Usare il limite più restrittivo per ogni campo (64 char name, 1.024 char description, 500 righe SKILL.md)
Testare su almeno due piattaforme diverse

Se la Skill è esclusivamente per Claude Code, è sicuro usare i campi estensione: le altre piattaforme li ignorano senza errori.

A2.4 Differenze chiave Microsoft vs Anthropic

Aspetto	Microsoft / GitHub Copilot	Anthropic / Claude Code
Campi `name` e `description`	Obbligatori	Opzionali (con fallback)
Campi estensione	Non supportati (ignorati)	11 campi aggiuntivi
Invocazione utente	Automatica (descrizione)	Via `/nome-skill` o automatica
Compattazione contesto	Non documentata	5.000 token/Skill, 25.000 totali
Ricerca cartelle	Fino a 2 livelli	Solo livello diretto
Estensioni script	`.py`, `.js`, `.sh`, `.ps1`, `.cs`, `.csx`	Qualsiasi eseguibile
Rilevamento modifiche	Non documentato	Live (senza restart)

Appendice A3: Suggerimenti per test e manutenzione

A3.1 Come testare una Skill

Validazione YAML: copiare il frontmatter in un validatore YAML online o usare il comando skills-ref validate ./mia-skill se disponibile.
Test di invocazione manuale: digitare /nome-skill nella chat dell’assistente AI e verificare che la Skill venga caricata correttamente.
Test di invocazione automatica: scrivere una frase naturale che dovrebbe attivare la Skill (es. “fammi un report vendite”) e verificare che l’AI la carichi.
Test degli script: eseguire ciascuno script manualmente da terminale con input di test, verificando output ed errori.
Test cross-platform: se la Skill deve essere portabile, testarla su almeno due piattaforme diverse.

A3.2 Versionamento

Usare il campo metadata.version per tracciare le versioni della Skill
Adottare il versionamento semantico (MAJOR.MINOR): incrementare MAJOR per cambiamenti che rompono la compatibilità, MINOR per aggiunte e correzioni
Se si usa un sistema di controllo versione (Git), committare la cartella della Skill nel repository del progetto

A3.3 Manutenzione periodica

Rivedere le Skill ogni trimestre per verificare che le istruzioni siano ancora accurate
Aggiornare le dipendenze degli script quando cambiano le versioni dei linguaggi
Raccogliere feedback dagli utenti e aggiornare la descrizione se le parole chiave di attivazione non sono efficaci
Monitorare le dimensioni: se SKILL.md cresce oltre 400 righe, è il momento di spostare contenuti in references/

A3.4 Ciclo di vita di una Skill

Fase	Attività	Output
1. Analisi	Identificare l’esigenza e i criteri di successo	Requisiti della Skill
2. Sviluppo	Creare SKILL.md, script, references, assets	Skill completa
3. Test	Validazione, invocazione manuale e automatica	Report di test
4. Distribuzione	Posizionare nella cartella corretta	Skill disponibile
5. Monitoraggio	Raccogliere feedback e metriche di utilizzo	Backlog di miglioramenti
6. Aggiornamento	Correggere, migliorare, aggiornare versione	Nuova release

Appendice A4: Glossario

Termine	Definizione
Agent Skills	Standard aperto per impacchettare competenze, istruzioni e risorse in cartelle che gli assistenti AI possono scoprire e usare. Definito su agentskills.io.
SKILL.md	Il file obbligatorio in ogni cartella Skill. Contiene frontmatter YAML (metadati) e corpo Markdown (istruzioni).
Frontmatter	La sezione iniziale di SKILL.md, racchiusa tra `---` e `---`. Contiene metadati strutturati in formato YAML (`name`, `description`, ecc.).
YAML	Yet Another Markup Language. Formato di serializzazione dati basato su indentazione, usato per il frontmatter delle Skill.
Markdown	Linguaggio di markup leggero per la formattazione del testo. Usato per il corpo delle Skill dopo il frontmatter.
MCP	Model Context Protocol. Standard aperto per l’integrazione di tool e servizi esterni con gli assistenti AI. Diverso dalle Skill (che sono istruzioni locali).
Progressive disclosure	Pattern architetturale che carica le informazioni in stadi successivi (annuncio, caricamento, risorse, script) per minimizzare il consumo di contesto.
Token	Unità di testo usata dai modelli AI. Un token corrisponde circa a ¾ di una parola in italiano.
Contesto	La “memoria di lavoro” dell’AI durante una sessione. Ha una dimensione limitata, misurata in token.
user-invocable	Campo estensione di Claude Code che controlla se una Skill appare nel menu `/` dell’utente. Non fa parte dello standard aperto.
CLAUDE.md	File di configurazione specifico di Claude Code. Contiene regole e preferenze sempre attive (a differenza delle Skill, caricate on-demand).
AGENTS.md	File standard della Linux Foundation per le istruzioni a livello di progetto (build, stile codice, test). Complementare, non alternativo alle Skill.
Compattazione	Processo automatico di Claude Code che riduce il contesto quando si avvicina al limite, ri-allegando solo le Skill più recenti.
Slash command	Comando invocato dall’utente digitando `/` seguito dal nome (es. `/report-vendite`). In Claude Code corrisponde al campo `name` della Skill.

Riferimenti ufficiali

Nota: Tutti i link sopra puntano a domini ufficiali. Verificare periodicamente che siano ancora validi, poiché la documentazione delle Agent Skills è in evoluzione.

— Fine del documento —