Le cinque regole
di Anthropic per le skill

Una skill è una cartella con dentro un file, SKILL.md: le istruzioni che Claude segue ogni volta che fa un certo lavoro. In cima al file ci sono due campi, il nome e la descrizione. Accanto possono stare altri file: esempi, listini, script.

All'avvio Claude legge solo il nome e la descrizione di tutte le skill che hai. Il SKILL.md lo apre quando la skill serve. Gli altri file li apre solo se il lavoro li richiede. Le cinque regole partono tutte da qui.

Vengono da Skill authoring best practices, la guida che Anthropic tiene nella sua documentazione. Le frasi in inglese che trovi sotto ogni regola sono citate parola per parola dalla guida, così puoi controllarle.

Partire da un foglio bianco è il modo più lento di scrivere una skill. Fai prima il lavoro una volta con Claude, in una chat normale. Mentre lavorate gli spieghi cosa vuoi, lo correggi, gli dici dove trovare le cose. Alla fine tutto quello che serve alla skill è già nella conversazione.

"Complete a task without a Skill: Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide."

Le cose che gli hai ripetuto due volte sono quelle che la skill deve sapere. Non ti serve una skill per scrivere skill: la guida dice che Claude conosce già il formato. A lavoro finito, nella stessa chat, incolla questo:

Abbiamo appena finito [il lavoro, per esempio il preventivo per Rossi Srl].
Trasformalo in una skill che rifaccia questo lavoro ogni volta che serve.

Prima rileggi tutta la conversazione e fammi la lista di quello che ti ho spiegato:
regole, preferenze, correzioni che ti ho fatto, file che hai dovuto aprire.
Segna le cose che ti ho ripetuto più di una volta.

Poi scrivi la skill in .claude/skills/[nome-skill]/SKILL.md con queste regole:
- name: solo minuscole, numeri e trattini
- description: in terza persona, cosa fa e quando va usata, con le parole che userei io per chiederla
- nel corpo solo quello che non sai già, senza spiegarmi cose ovvie
- un esempio vero preso da questo lavoro: la mia richiesta e il risultato finale
- sotto le 500 righe: tabelle, listini e testi lunghi in file a parte nella stessa cartella
- ogni file a parte richiamato direttamente dal SKILL.md, con una riga che dice quando aprirlo

Mostrami la skill prima di salvarla.

Il percorso .claude/skills/ è quello di Claude Code. Su Claude.ai togli quella riga e chiedigli la cartella della skill in un file ZIP: la carichi da Personalizza, nella sezione Skill.

Su Cowork puoi anche registrarlo. Se il lavoro lo fai più con il mouse che a parole, c'è Record a skill: registri lo schermo mentre lavori e Claude ti propone la skill.

1. Apri Cowork nell'app Claude per Mac. Serve un piano Pro, Max o Team. In chat e su Windows per ora non c'è.
2. Premi + nella casella di testo e scegli Record a skill. La prima volta il Mac ti chiede i permessi di accessibilità e di registrazione dello schermo.
3. Fai il lavoro come al solito e racconta a voce perché fai ogni passo. La voce dà a Claude il contesto che dallo schermo non vede. La registrazione dura al massimo una decina di minuti.
4. Premi Done. Claude guarda la registrazione e ti propone una skill nuova, oppure la modifica di una che hai già. La leggi e la salvi.

Prima di partire chiudi quello che non vuoi far vedere: viene registrato tutto lo schermo, voce compresa. I passi completi sono nella pagina di aiuto di Anthropic.

All'avvio Claude vede solo il nome e la descrizione di ogni skill. È con la descrizione che sceglie quale aprire. Se è vaga, la skill resta ferma quando ti serve e parte quando non c'entra.

"The description field enables Skill discovery and should include both what the Skill does and when to use it."

"Claude uses it to choose the right Skill from potentially 100+ available Skills."

1. Cosa fa e quando usarla. Due parti, sempre. La prima dice il lavoro, la seconda le situazioni in cui serve.
2. In terza persona. «Estrae il testo dai PDF». La descrizione finisce nel prompt di sistema di Claude e un «posso aiutarti» o un «puoi usarla» gli confondono la scelta.
3. Con le parole che usi tu. Se in ufficio dite «quotazione» al posto di «preventivo», scrivi tutte e due.
4. Al massimo 1.024 caratteri. Bastano due o tre frasi.

Vaga:
description: Aiuta con i documenti

Scritta bene:
description: Estrae testo e tabelle dai PDF, compila moduli e unisce documenti. Da usare quando si lavora con file PDF o quando l'utente nomina PDF, moduli o estrazione di dati da un documento.

Puoi scrivere tre paragrafi sul tono che vuoi nelle mail ai clienti. Oppure incollare tre mail che ti sono venute bene. Anthropic dice che la seconda strada funziona meglio.

"Examples convey the desired style and level of detail to Claude more clearly than descriptions alone."

La guida suggerisce coppie di ingresso e uscita, come nel prompting normale: la richiesta e il risultato che volevi. Mettine una per intero nel SKILL.md e le altre in una cartella esempi/ che la skill legge quando serve. Usa lavori veri: nella lista di controllo finale Anthropic chiede esempi concreti.

Se hai tanti lavori fatti, dagli anche quelli venuti male. Claude confronta i due gruppi e trova cosa li distingue, una cosa che a parole faresti fatica a spiegare.

Quando Claude apre il SKILL.md, ogni riga occupa spazio nella sua memoria di lavoro insieme alla conversazione e a tutto il resto. Per questo la guida mette un tetto: 500 righe. Listini, tabelle, documentazione e testi lunghi vanno in file a parte nella stessa cartella. Finché Claude non li apre non pesano niente.

"Keep SKILL.md body under 500 lines for optimal performance."

"Reference files, data, or documentation don't consume context tokens until actually read."

preventivi-clienti/
├── SKILL.md         letto quando la skill parte
├── listino.md       letto solo per i prezzi
├── condizioni.md    letto solo per i clienti nuovi
└── esempi/          letti prima di scrivere
    ├── rossi-srl.md
    └── conti-impianti.md

Richiama ogni file direttamente dal SKILL.md, con una riga che dice quando aprirlo. La guida chiede un livello solo: quando un file ne richiama un altro, Claude rischia di leggere solo l'inizio del secondo.

La chat che ha scritto la skill sa già tutto quello che le hai spiegato, quindi riempie da sola i buchi delle istruzioni. Per vedere quei buchi ti serve una chat nuova, con la skill installata e un lavoro vero da fare. Anthropic chiama la prima Claude A e la seconda Claude B.

"Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks."

Usa la skill [nome-skill] per fare questo lavoro:
[incolla una richiesta vera, diversa da quella con cui hai costruito la skill]

Lavora come faresti normalmente.
Quando hai finito, dimmi:
1. quali file della skill hai aperto e in che momento
2. dove le istruzioni non erano chiare o mancava qualcosa
3. cosa hai dovuto decidere da solo perché la skill non lo diceva

Controlla il risultato come faresti con il lavoro di un collega. Poi torna nella chat che ha scritto la skill con quello che hai visto:

Ho provato la skill in un'altra chat su questo lavoro: [la richiesta].
Ecco cosa è andato storto: [quello che hai visto, per esempio ha usato un prezzo che non è nel listino].
Ecco cosa ha risposto la chat di prova: [incolla le sue tre risposte].

Correggi il SKILL.md perché non succeda più.
Cambia solo quello che serve e mostrami le modifiche prima di salvarle.

Ripeti il giro finché la chat di prova fa il lavoro senza che tu debba correggerla. La guida lo dice chiaro: si migliora una skill guardando come la usa Claude sui lavori veri.

Un modello con tutte e cinque le regole dentro, su un lavoro che quasi ogni azienda fa: i preventivi. Cambia il lavoro, tieni la struttura. L'azienda e i prezzi sono inventati.

---
name: preventivi-clienti
description: Scrive i preventivi per i clienti nel formato dell'azienda, con le voci, i prezzi del listino, le condizioni di pagamento e la validità dell'offerta. Da usare quando l'utente chiede un preventivo, un'offerta o una quotazione per un cliente. Anche quando nomina un cliente insieme a un prodotto o a un servizio da prezzare.
---

# Preventivi per i clienti

## Come si lavora
1. Se mancano, chiedi il nome del cliente, cosa vuole e per quando.
2. Prendi i prezzi solo da listino.md. Se un prodotto non c'è, fermati e chiedi.
3. Scrivi il preventivo con la struttura qui sotto.
4. Prima di consegnarlo, passa la lista di controllo in fondo.

## Struttura
- Oggetto: preventivo per [cliente], [servizio]
- Due righe su cosa ha chiesto il cliente, con le sue parole
- Tabella delle voci: descrizione, quantità, prezzo, totale
- Condizioni di pagamento e validità

## Esempio
Richiesta: "Preventivo per Rossi Srl, tre giornate di formazione a novembre"

Preventivo:
Oggetto: preventivo per Rossi Srl, formazione in aula
Ci avete chiesto tre giornate di formazione per il vostro team a novembre.
| Voce                           | Quantità | Prezzo  | Totale  |
| Giornata di formazione in aula | 3        | 1.500 € | 4.500 € |
Pagamento: 50% alla firma, 50% a fine corso. Offerta valida 30 giorni.

Altri preventivi accettati dai clienti sono in esempi/.
Leggine almeno due prima di scrivere: tono, ordine delle voci e lunghezza vengono da lì.

## File a parte
- listino.md: prezzi e sconti. Aprilo per ogni preventivo.
- condizioni.md: condizioni di pagamento per tipo di cliente. Aprilo quando il cliente è nuovo o chiede una dilazione.
- esempi/: preventivi accettati, uno per file.

## Lista di controllo
- [ ] Ogni prezzo viene da listino.md
- [ ] I totali sono ricontrollati
- [ ] La validità dell'offerta è scritta

Cosa c'è dentro, pezzo per pezzo:

1. name. Solo minuscole, numeri e trattini, al massimo 64 caratteri. Le parole «claude» e «anthropic» sono riservate e non si possono usare.
2. description. Cosa fa, poi quando usarla, in terza persona e con le parole di chi la chiederà. È la regola 2.
3. Come si lavora. Passi numerati e corti. Solo quello che Claude non può sapere da solo: la guida parte dal presupposto che Claude sia già molto intelligente, quindi ogni spiegazione in più gli toglie spazio.
4. Esempio. Una coppia richiesta e risultato scritta per intero. Gli altri esempi stanno nella cartella. È la regola 3.
5. File a parte. Ogni file richiamato dal SKILL.md con il momento in cui aprirlo. È la regola 4.
6. Lista di controllo. I controlli che faresti tu prima di mandare il lavoro. Quando Claude B sbaglia qualcosa al punto 5, di solito la correzione finisce qui.

Il modello da mettere nella cartella della skill e i tre prompt di questa pagina, in ordine. Le parti da cambiare sono tra parentesi quadre.