Un file SKILL.md è il cuore di ogni Skill di Claude: un file Markdown che inizia con una breve intestazione YAML (un name e una description) e prosegue con le istruzioni che Claude deve seguire. La description indica a Claude quando usare la Skill; il corpo gli spiega come.
Se hai visto il term e ti sei chiesto cosa ci sia davvero dentro, ecco l'anatomia di un SKILL.md, perché ogni parte è importante e come scriverne uno efficace.
Cos'è SKILL.md
Una Skill di Claude è una cartella, e SKILL.md è il file obbligatorio nella sua radice. È semplice Markdown, quindi si apre in qualsiasi editor di testo. Claude lo legge per imparare una capacità - i passaggi, le regole e le best practice per un tipo di attività. Gli extra opzionali (modelli, script e file di riferimento) possono essere inseriti nella stessa cartella, ma SKILL.md è l'unico file che ogni Skill deve avere.
Vuoi vedere uno SKILL.md ben definito invece di crearne uno da zero? Il frontmatter e le istruzioni di Yuri sono già scritti e testati per individuare bug, falle di sicurezza e problemi di prestazioni durante una revisione.
Visualizza Yuri - Skill AI per la revisione del codice →Le due parti di SKILL.md
1. Il frontmatter (metadati)
In cima trovi un piccolo blocco YAML racchiuso tra marcatori ---. Contiene i metadati essenziali - come minimo un name e una description:
---
name: weekly-report
description: Formatta le note grezze nel nostro report settimanale standard. Usalo quando l'utente chiede un aggiornamento settimanale, un report sullo stato o di “scrivere un resoconto della settimana”.
---Questo blocco è speciale: quando inizia una sessione, Claude precarica solo il nome e la descrizione di ogni Skill installata, non l'intero file. In questo modo la finestra di contesto rimane leggera, ed è per questo che la descrizione svolge un ruolo così importante.
2. Il corpo (istruzioni)
Sotto il frontmatter, in Markdown normale, scrivi cosa dovrebbe effettivamente fare Claude - idealmente come passaggi numerati e chiari, con eventuali regole o esempi:
## Passaggi
1. Raggruppa le note sotto “Vittorie”, “In corso” e “Blocchi”.
2. Mantieni ogni punto in una sola frase, al passato.
3. Concludi con un riepilogo di una riga intitolato "La prossima settimana".
4. Non inventare mai metriche che non compaiono negli appunti.Perché la descrizione è la riga più importante
L'attivazione dipende interamente dalla descrizione. Mentre lavori, Claude confronta la tua richiesta con la descrizione di ogni skill e carica il file completo solo quando corrisponde. Una descrizione vaga ("aiuta con i report") raramente si attiva. Una descrizione specifica ("usala quando l'utente chiede un aggiornamento settimanale o un report sullo stato") si attiva in modo affidabile. Se devi ricordare una sola regola, fa' che sia questa: scrivi la descrizione indicando quando usare la skill, non solo che cos'è.
Come Claude utilizza il file
- All'avvio: Claude legge il nome e la descrizione di ogni skill.
-
Durante l'attività: se la tua richiesta corrisponde a una descrizione, Claude carica il file
SKILL.mdcompleto di quella skill (e tutte le risorse allegate). - Poi: Claude segue le istruzioni del corpo del file per completare il lavoro.
Questo approccio del "caricala solo quando serve" si chiama divulgazione progressiva ed è ciò che ti permette di tenere molte skill installate senza appesantire il contesto del modello.
Scrivere un buon SKILL.md
- Cura la descrizione. Indica chiaramente quando la skill deve attivarsi.
- Mantieni ridotta la prima versione. Cinque-dieci righe di passaggi chiari sono meglio di un documento prolisso.
- Sii concreto. Passaggi numerati, regole esplicite, un breve esempio.
- Testala su attività reali. Ampliala solo nei punti in cui Claude non riesce.
Devi scriverne una personalmente?
No. Scriverne uno personalmente è ottimo per i flussi di lavoro unici per te, ma se vuoi solo il risultato, le skill già pronte includono il loro SKILL.md già creato e testato. Esplora la libreria KissMySkills con oltre 1.000 skill, raccolte di prompt e agenti, oppure la raccolta di skill per Claude Code. Vuoi vederne prima una in azione? Prova un generatore gratuito o scarica una skill gratuita.
Non tutti i file SKILL.md sono destinati ai programmatori - il frontmatter e le istruzioni di Ryan sono pensati per documenti per il consiglio di amministrazione, memo per riunioni generali e briefing dirigenziali, senza bisogno di modifiche.
Visualizza lo Skill AI Ryan - Chief of Staff →Domande frequenti
SKILL.md è semplicemente Markdown?
Sì - è un file Markdown standard con un blocco frontmatter YAML in cima. Si apre in qualsiasi editor di testo, senza bisogno di software speciali.
Cosa è richiesto in un file SKILL.md?
Come minimo, un blocco frontmatter con un nome e una descrizione. Il corpo con le istruzioni è ciò che rende utile lo Skill, ma i metadati sono ciò che lo rende individuabile e attivabile.
Dove va inserito il file SKILL.md?
Nella radice della cartella dello Skill. In Claude Code, gli Skill si trovano in ~/.claude/skills/<name>/ per uso personale o .claude/skills/<name>/ all'interno di un progetto, con SKILL.md nella radice della cartella.
Posso usare il contenuto di un file SKILL.md in ChatGPT o Gemini?
Sì. Le istruzioni sono portabili - incolla il corpo nelle istruzioni personalizzate di ChatGPT o Gemini per ottenere lo stesso comportamento. L'attivazione automatica tramite frontmatter è una funzionalità di Claude.
In sintesi:
Se preferisci evitare di scrivere personalmente il frontmatter YAML, Yuri - Code Reviewer è un'ottima scelta per gli sviluppatori, mentre Ryan - Chief of Staff si occupa della scrittura dirigenziale e aziendale. Tutti funzionano in Claude, ChatGPT e qualsiasi chat AI senza bisogno di programmare, con una garanzia di rimborso entro 30 giorni.
Inizia con un esempio funzionante
Il modo più rapido per capire SKILL.md è leggerne uno ben fatto. Scarica uno Skill gratuito, apri il file e osserva la struttura frontmatter più passaggi in azione - poi leggi come installarlo in tre minuti.
