> For the complete documentation index, see [llms.txt](https://transizionedigitale.gitbook.io/ai-pa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://transizionedigitale.gitbook.io/ai-pa/skill/skill/13.-documentare-le-skill-scheda-e-metadati.md).

# 13. Documentare le SKILL: scheda e metadati

Cosa fare prima di caricare documenti sull'AI

Una SKILL senza documentazione è come un faldone senza etichetta: forse è utile, ma nessuno lo trova, nessuno si fida e nessuno sa chi lo ha scritto. La documentazione serve a quattro scopi: **trovare, capire, fidarsi**, dimostrare (la responsabilizzazione richiesta dal GDPR e dalla normativa sull'IA).

### 13.1 Che cosa sono i metadati

I **metadati** sono “dati che descrivono altri dati”: nel nostro caso, le informazioni che descrivono la SKILL (chi l'ha scritta, a cosa serve, quale versione, quando va rivista). Si possono scrivere in una **scheda** (un breve documento che accompagna la SKILL) e riportare nel **catalogo** (capitolo 14).

{% hint style="success" icon="comment-pen" %} <mark style="color:$success;">**CONSIGLIO PRATICO – Dove scrivere i metadati**</mark>

Nell'intestazione del file `SKILL.md` metti solo nome e descrizione, perché sono i campi riconosciuti dagli strumenti. Tutte le altre informazioni vanno in un file separato, chiamato per esempio `SCHEDA.md`, nella stessa cartella. In questo modo non si rischiano problemi di compatibilità, e la scheda può essere letta da chiunque
{% endhint %}

### 13.2 I metadati da compilare

<table data-header-hidden><thead><tr><th width="133"></th><th width="240"></th><th width="260"></th><th></th></tr></thead><tbody><tr><td><strong>Campo</strong></td><td><strong>Descrizione</strong></td><td><strong>Esempio</strong></td><td><strong>Obbl.</strong></td></tr><tr><td>Codice</td><td>Identificativo unico nell'ente</td><td>URP-001</td><td>Sì</td></tr><tr><td>Nome</td><td>Nome tecnico della SKILL (uguale a name)</td><td>bozza-risposta-urp</td><td>Sì</td></tr><tr><td>Titolo</td><td>Nome leggibile</td><td>Bozza di risposta a richieste di informazioni</td><td>Sì</td></tr><tr><td>Versione</td><td>Numero MAGGIORE.MINORE.REVISIONE</td><td>1.1.1</td><td>Sì</td></tr><tr><td>Stato</td><td>Bozza / In revisione / Approvata / In uso / Da rivedere / Ritirata</td><td>In uso</td><td>Sì</td></tr><tr><td>Ufficio proprietario</td><td>Servizio responsabile della SKILL</td><td>URP</td><td>Sì</td></tr><tr><td>Autore</td><td>Chi l'ha scritta (ruolo e nome)</td><td>M. Rossi, istruttore URP</td><td>Sì</td></tr><tr><td>Revisore</td><td>Chi ha verificato il contenuto</td><td>L. Bianchi, funzionario URP</td><td>Sì</td></tr><tr><td>Approvatore</td><td>Chi l'ha approvata e data</td><td>Dott.ssa V. Verdi, 15/10/2026</td><td>Sì</td></tr><tr><td>Data di creazione / ultima modifica</td><td>Date in formato gg/mm/aaaa</td><td>15/10/2026 – 12/11/2026</td><td>Sì</td></tr><tr><td>Data di prossima revisione</td><td>Scadenza del controllo periodico</td><td>12/05/2027</td><td>Sì</td></tr><tr><td>Scopo</td><td>Che cosa fa, in due frasi</td><td>Prepara la bozza di risposta…</td><td>Sì</td></tr><tr><td>Destinatari</td><td>Chi la può usare</td><td>Operatori URP</td><td>Sì</td></tr><tr><td>Processo collegato</td><td>Procedimento o attività</td><td>Risposta a richieste di informazioni</td><td>Sì</td></tr><tr><td>Riferimenti normativi e interni</td><td>Norme, regolamenti, manuali richiamati</td><td><ul><li>Carta dei servizi; </li><li>regolamento URP</li><li>.............</li></ul></td><td>Sì</td></tr><tr><td>Livello di rischio</td><td>Verde / Giallo / Rosso</td><td>Giallo</td><td>Sì</td></tr><tr><td>Livello di intervento umano</td><td>1, 2, 3 o X</td><td>2 – Revisione completa e firma</td><td>Sì</td></tr><tr><td>Dati ammessi</td><td>Categorie di dati che si possono inserire</td><td>Testo della richiesta senza dati identificativi</td><td>Sì</td></tr><tr><td>Dati vietati</td><td>Categorie che non si possono inserire</td><td>Codice fiscale, dati sanitari, dati di minori</td><td>Sì</td></tr><tr><td>Strumenti compatibili</td><td>Strumenti di IA autorizzati con cui è stata provata</td><td>Strumento X (versione Y)</td><td>Sì</td></tr><tr><td>Valutazione privacy</td><td>Riferimento al parere del DPO o alla DPIA</td><td>Parere DPO prot. n. …</td><td>Se dati personali</td></tr><tr><td>Esiti dei test</td><td>Data, banco di prova, risultati</td><td>12 casi; accettazione 85%</td><td>Sì</td></tr><tr><td>Indicatori di monitoraggio</td><td>Cosa si misura e con quale frequenza</td><td>Tempo medio; accettazione; mensile</td><td>Consigliato</td></tr><tr><td>Parole chiave</td><td>Per la ricerca</td><td>URP, risposta, informazioni, cittadini</td><td>Sì</td></tr><tr><td>Riuso</td><td>Se può essere condivisa con altri enti</td><td>Sì, previa anonimizzazione</td><td>Consigliato</td></tr><tr><td>Contatto</td><td>Dove inviare segnalazioni</td><td>urp.skill@ente.example</td><td>Sì</td></tr></tbody></table>

### 13.3 Il modello della scheda (`SCHEDA.md`)

```
// Esempio di SCHEDA.md

SCHEDA DELLA SKILL
 
Codice:                    URP-001
Nome:                      bozza-risposta-urp
Titolo:                    Bozza di risposta a richieste di informazioni
Versione / Stato:          1.1.1 / In uso
Ufficio proprietario:      URP
 
Autore:                    M. Rossi, istruttore
Revisore:                  L. Bianchi, funzionario
Approvato da / data:       V. Verdi, dirigente / 15/10/2026
Creazione / modifica:      15/10/2026 / 12/11/2026
Prossima revisione:        12/05/2027
 
SCOPO
Prepara la bozza di risposta a richieste di informazioni generali,
in linguaggio semplice, usando solo le schede informative dell'ente.
 
DESTINATARI
Operatori dell'URP.
 
PROCESSO E RIFERIMENTI
Risposta a richieste di informazioni - Carta dei servizi - Regolamento URP.
 
CLASSIFICAZIONE
Rischio: GIALLO     Intervento umano: Livello 2
 
DATI
Ammessi:  testo della richiesta, senza dati identificativi.
Vietati:  codice fiscale, dati sanitari, dati di minori, recapiti.
 
STRUMENTI E PROVE
Provata con: strumento X, versione Y, il 10/11/2026.
Banco di prova: 12 casi. Accettazione 85%. Errori gravi: 0.
 
PRIVACY
Parere del DPO: prot. n. ... del ...
 
PAROLE CHIAVE
urp, risposta, informazioni, cittadini, linguaggio semplice
 
LIMITI NOTI
Non gestisce reclami, accesso agli atti, casi personali.
 
CONTATTO PER SEGNALAZIONI
urp.skill@ente.example

```

### 13.4 Come dare il nome e il codice alle SKILL

Un'ordine nei nomi aiuta moltissimo la ricerca. Si propone la seguente convenzione, da adattare.

<table data-header-hidden><thead><tr><th width="193"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Elemento</strong></td><td><strong>Regola</strong></td><td><strong>Esempio</strong></td></tr><tr><td>Codice</td><td>Sigla dell'area + numero progressivo a tre cifre</td><td>URP-001, PROT-003, GARE-002, RUP-001, DEC-001, PERS-001, CONT-001</td></tr><tr><td>Nome della cartella</td><td>Verbo o sostantivo + oggetto, minuscolo, con trattini, senza accenti né spazi</td><td>bozza-risposta-urp</td></tr><tr><td>Versione</td><td>Numero a tre parti</td><td>1.1.1</td></tr><tr><td>Nome del file di rilascio</td><td>codice_nome_versione</td><td>URP-001_bozza-risposta-urp_1.1.1</td></tr></tbody></table>

### 13.5 La guida rapida per gli utenti

Per ogni SKILL è utile una **guida di una pagina** per chi la usa. Deve rispondere a poche domande. Eccone uno schema.

| **Sezione**                             | **Contenuto**                                  |
| --------------------------------------- | ---------------------------------------------- |
| A che cosa serve                        | Due righe                                      |
| Quando usarla / quando NON usarla       | Due elenchi brevi                              |
| Che cosa preparare                      | Dati da fornire e dati da non fornire          |
| Come si usa                             | I passaggi, con un esempio di richiesta        |
| Che cosa ottieni                        | Descrizione del risultato e un esempio         |
| Che cosa devi controllare               | Checklist del revisore dedicata a questa SKILL |
| A chi chiedere aiuto o segnalare errori | Contatto                                       |

### 13.6 Alcuni consigli di scrittura per la documentazione

* **Scrivi per chi non c'era**: tra un anno, un collega nuovo deve capire la SKILL senza chiederti nulla.
* **Usa parole semplici** e spiega le sigle la prima volta.
* **Indica sempre le date e il significato dei numeri** (“accettazione 85% su 12 casi”).
* **Non nascondere i limiti**: dire cosa la SKILL non fa è parte della documentazione.
* **Tieni la scheda allineata alla SKILL**: ogni modifica significativa aggiorna scheda e registro.