> 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/4.-anatomia-di-una-skill-gli-elementi-da-scrivere.md).

# 4. Anatomia di una SKILL: gli elementi da scrivere

Una SKILL ben fatta ha sempre la stessa struttura. Avere uno schema fisso aiuta chi scrive (non si dimentica nulla), chi controlla (sa dove cercare) e chi usa (trova sempre le stesse sezioni). In questo capitolo vediamo i dodici elementi e, alla fine, un modello completo da copiare.

### 4.1 I dodici elementi

<table data-header-hidden><thead><tr><th width="73.18182373046875"></th><th width="153"></th><th width="241.00006103515625"></th><th></th></tr></thead><tbody><tr><td><strong>#</strong></td><td><strong>Elemento</strong></td><td><strong>A cosa serve</strong></td><td><strong>Come scriverlo</strong></td></tr><tr><td>1</td><td>Nome</td><td>Identifica la SKILL</td><td>Breve, in minuscolo, con trattini: ad esempio bozza-risposta-urp. Descrive il compito, non l'ufficio</td></tr><tr><td>2</td><td>Descrizione</td><td>Dice all'assistente quando usare la SKILL</td><td>Una o due frasi: cosa fa, quando si usa, cosa non fa. È la parte più importante dell'intestazione</td></tr><tr><td>3</td><td>Obiettivo</td><td>Spiega lo scopo in modo semplice</td><td>Una frase che inizia con un verbo: “Preparare…”, “Verificare…”, “Riassumere…”</td></tr><tr><td>4</td><td>Destinatari e contesto</td><td>Dice chi la usa e in quale ufficio</td><td>Ruolo (non nome di persona), ufficio, tipo di ente</td></tr><tr><td>5</td><td>Dati in ingresso</td><td>Elenca cosa deve fornire l'utente</td><td>Elenco di informazioni richieste; e dati vietati da non inserire</td></tr><tr><td>6</td><td>Procedura</td><td>I passaggi da seguire, in ordine</td><td>Numerati, brevi, un'azione per riga</td></tr><tr><td>7</td><td>Formato del risultato</td><td>Com'è fatto l'output</td><td>Struttura, titoli, lunghezza, tabella o testo, lingua e tono</td></tr><tr><td>8</td><td>Regole di stile</td><td>Linguaggio e tono</td><td>Ad esempio: frasi brevi, niente gergo, forma di cortesia</td></tr><tr><td>9</td><td>Controlli di qualità</td><td>L'assistente verifica se stesso</td><td>Elenco di controlli prima di consegnare: completezza, coerenza, assenza di dati vietati</td></tr><tr><td>10</td><td>Limiti e divieti</td><td>Cosa non deve mai fare</td><td>Frasi nette: “Non emanare decisioni”, “Non inventare riferimenti normativi”</td></tr><tr><td>11</td><td>Intervento umano</td><td>Dove si ferma e chiede conferma</td><td>Punti di arresto e istruzioni per chi rivede (capitolo 9)</td></tr><tr><td>12</td><td>Esempi</td><td>Mostrano il risultato atteso</td><td>Uno o due esempi buoni, e se utile un esempio da evitare</td></tr></tbody></table>

### 4.2 Il nome e la descrizione: le due righe che contano di più

Quando l'assistente ha a disposizione molte SKILL, non le legge tutte per intero: legge solo il nome e la descrizione di ciascuna e sceglie quella adatta alla richiesta. Solo dopo carica il testo completo. Se la descrizione è vaga, la SKILL non verrà scelta quando serve oppure verrà scelta quando non serve.

<table data-header-hidden><thead><tr><th width="222"></th><th></th></tr></thead><tbody><tr><td><strong>Descrizione debole</strong></td><td><strong>Descrizione efficace</strong></td></tr><tr><td>“Aiuta con le risposte ai cittadini.”</td><td>“Prepara la bozza di risposta a una richiesta di informazioni inviata all'URP, in linguaggio semplice e con rinvio ai riferimenti dell'ente. Da usare quando l'operatore ha il testo della richiesta e deve redigere la risposta. Non risponde a reclami formali né a richieste di accesso agli atti.”</td></tr><tr><td>“Gestione appalti.”</td><td>“Verifica che la documentazione amministrativa presentata da un operatore economico sia completa rispetto all'elenco dei documenti richiesti dal bando. Da usare nella fase di controllo formale. Non decide l'ammissione o l'esclusione.”</td></tr><tr><td>“Aiuto per i verbali.”</td><td>“Trasforma gli appunti di una riunione in una bozza di verbale con presenti, argomenti, decisioni e attività assegnate. Da usare dopo riunioni interne. Non attribuisce decisioni non presenti negli appunti.”</td></tr></tbody></table>

{% hint style="info" icon="user-doctor-message" %} <mark style="color:$success;">**CONSIGLIO PRATICO – La regola delle tre parti**</mark>

Una buona descrizione risponde a tre domande: cosa fa la SKILL, quando si usa, cosa non fa. Se manca una delle tre, riscrivila.
{% endhint %}

### 4.3 Scrivere la procedura: come si ragiona

La procedura è il cuore della SKILL. Per scriverla bene, immagina di spiegare il lavoro a un collega nuovo e molto diligente, che esegue alla lettera ciò che scrivi e non può chiederti chiarimenti. Quindi:

* un passaggio, un'azione: “Leggi l'oggetto” e poi “Individua l'argomento”, non “Leggi l'oggetto e individua l'argomento e proponi la classe”;
* ordine esplicito: usa numeri, non paragrafi discorsivi;
* condizioni chiare: “Se manca il codice del procedimento, chiedilo all'utente e non proseguire”;
* eccezioni scritte: cosa fare nei casi particolari (urgenza, atti anonimi, allegati illeggibili);
* fine definita: dì quando il lavoro è concluso e che cosa consegnare.

### 4.4 Il modello completo di <mark style="background-color:cyan;">`SKILL.md`</mark>

{% hint style="success" icon="markdown" %}
**Le Skill si scrivono in linguaggio Markdown (MD)**

Il linguaggio MD si basa su poche regole di formattazione del testo.

* [Sintassi linguaggio Markdown (MD)](https://www.markdownguide.org/basic-syntax/)  → in questo sito vengono elencate le regole di formattazione del testo.&#x20;
* [Markdown editor](https://www.jotbird.com/app)  → questo tool supporta l'utente nella corretta formattazione del testo.
  {% endhint %}

Ecco il modello da copiare per ogni nuova SKILL. **Le parti tra parentesi quadre vanno sostituite**. Una versione pronta da compilare si trova nell'Allegato A.

<pre><code>// Modello base di SKILL.md
---
name: [nome-della-skill]
description: [Cosa fa. Quando si usa. Cosa NON fa.]
---

# [Titolo leggibile della SKILL]

## Obiettivo
[Una frase che inizia con un verbo.]

## Chi la usa e in quale contesto
[Ruolo, ufficio, tipo di procedimento.]

## Dati da fornire
- [Informazione 1]
- [Informazione 2]

## Dati che NON vanno mai inseriti
- [Es.: codice fiscale, dati sanitari, dati giudiziari]
- Se l'utente li inserisce, avvisalo e chiedi di rimuoverli.

## Procedura
1. [Passaggio 1]
2. [Passaggio 2]
3. Se [condizione], allora [azione]; altrimenti [azione].

## Formato del risultato
[Struttura, lunghezza, tabella o testo, lingua, tono.]

## Regole di stile
- [Frasi brevi, linguaggio semplice, ecc.]

<strong>## Controlli prima di consegnare
</strong>- [ ] [Controllo 1]
- [ ] [Controllo 2]

## Limiti e divieti
- Non [azione vietata 1].
- Non inventare norme, date, importi o riferimenti: se non li
  conosci, scrivi "DA VERIFICARE".

## Intervento umano obbligatorio
- Il risultato è una BOZZA: va riletto e approvato da [ruolo].
- Fermati e chiedi conferma quando [situazione].

## Esempio
[Un esempio breve di input e di risultato corretto.]
</code></pre>