Come scrivere una skill per il tuo agent
Crea una skill partendo da un errore reale: scopri la struttura di SKILL.md, la descrizione che ne decide l'attivazione e come testarla.
Scrivi una skill per il tuo agent a partire da un errore reale
Il modo migliore per scrivere una skill per il tuo agent consiste nel ricavarla da un errore reale. Individua un'attività che il tuo coding agent ha eseguito in modo errato due volte, annota la correzione che hai digitato in entrambe le occasioni e salva quella correzione in un file SKILL.md che l'agent possa caricare autonomamente. Da quel momento resta solo la parte meccanica: la struttura del file e la riga che determina se la skill verrà mai attivata.
L'ordine è importante. Una skill scritta per supposizione descrive un problema che non hai mai riscontrato e consuma comunque contesto in ogni sessione. Una skill ricavata da un errore osservato include già il proprio test: ripeti la stessa richiesta e verifica se questa volta l'agent la gestisce correttamente. Se il formato è nuovo per te, leggi prima cosa sono le skill per gli agent e come vengono caricate da un agent, quindi torna qui e scrivine una.
Partire da un compito che l'agente ha sbagliato due volte
Una volta è un caso. Due volte è uno schema, e uno schema merita un file.
Ecco un errore che si ripete sui server reali. Chiedi all'agente di aggiungere un blocco reverse proxy a nginx. Esso modifica /etc/nginx/conf.d/app.conf, poi esegue sudo systemctl restart nginx. La modifica contiene un errore di battitura, quindi nginx si rifiuta di avviarsi e il sito rimane offline finché non intervieni per risolvere:
nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.Correggi l'errore in chat. Testa la configurazione con sudo nginx -t prima di toccare il servizio, quindi applicala con reload invece di restart. Una settimana dopo, su un compito diverso, si ripete lo stesso errore. Quella seconda volta è il segnale.
Annota due cose mentre l'errore è ancora davanti a te: la richiesta che hai digitato e la correzione che hai fornito, usando le tue stesse parole. Quelle due righe diventano la skill. La richiesta ti dice cosa deve corrispondere al trigger. La correzione è il contenuto completo.
La guida alla creazione di Anthropic mette questo punto al primo posto. Esegui l'agente su compiti rappresentativi senza alcuna skill, registra dove fallisce, quindi scrivi le istruzioni minime che risolvono tali errori. Gli errori costituiscono la specifica: se una skill non può essere ricondotta a uno di essi, solitamente non era necessaria. Lo stesso filtro funziona sulle skill che installi invece di scrivere, e le 27 skill pubblicate da Matt Pocock si dividono tra quelle che uno sviluppatore singolo su una VPS dovrebbe installare e quelle che ripagano solo in un team.
Per un esempio pratico della stessa distillazione, Ponytail trasforma un errore ripetuto, ovvero un agente che riscrive molto più di quanto richiesto, in una skill che puoi leggere dall'inizio alla fine prima di scrivere la tua.
La struttura di una skill
Una skill è una directory che contiene un solo file obbligatorio.
.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│ └── proxy-headers.md
└── scripts/
└── check-and-reload.shSKILL.md inizia con un blocco frontmatter, cioè alcune impostazioni scritte in YAML (lo stesso formato di configurazione usato dai file Docker Compose) racchiuse tra i marker ---, seguito dalle istruzioni in markdown. Ecco la skill completa relativa al problema precedente.
---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---
## Rules
Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.
Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.
If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.
For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).Il file contiene meno di venti righe ed è una skill completa. Le sue parti sono:
name: massimo 64 caratteri, solo lettere minuscole, cifre e trattini; non può contenere le paroleclaudeoanthropic. In una skill personale o di progetto è soltanto l'etichetta visualizzata. Il comando da digitare deriva dal nome della directory, quindi questa skill risponde a/nginx-config-changes.description: descrive cosa fa la skill e quando utilizzarla, con un massimo di 1.024 caratteri. Questa riga svolge il lavoro principale; la sezione successiva riguarda esclusivamente questo aspetto.- Il corpo: contiene le istruzioni, caricate solo quando la skill viene effettivamente attivata.
reference/: file aggiuntivi che l'agent legge su richiesta. Collegali daSKILL.mde mantieni i collegamenti a un solo livello di profondità, perché un file referenziato da un altro file referenziato viene spesso letto solo parzialmente.scripts/: file che l'agent esegue invece di leggere. Solo il relativo output consuma contesto, quindi uno script di 300 righe ha un costo ridotto.
Una skill raggiunge la struttura completa quando il comportamento che deve correggere è abbastanza persistente da richiederla. La skill unlazy usa quello spazio per un Depth Tree, un insieme di file gate e un contratto PLAN.md, così da impedire all'agent di dichiarare concluso il lavoro mentre interi rami restano non elaborati.
La posizione della directory determina chi può usare la skill.
.claude/skills/<name>/SKILL.mdnel repository: solo questo progetto, e la skill viene distribuita a chiunque cloni il repository.~/.claude/skills/<name>/SKILL.md: ogni progetto sulla tua macchina, ma nessun progetto sulle macchine altrui.<plugin>/skills/<name>/SKILL.md: inclusa in un plugin e disponibile ovunque quel plugin sia abilitato.
Crea la skill con mkdir -p .claude/skills/nginx-config-changes e scrivi il file. Claude Code monitora queste directory, quindi le modifiche a una skill esistente diventano effettive nella sessione in esecuzione. La creazione di una directory skills di primo livello che non esisteva all'avvio della sessione richiede un riavvio, perché quando la sessione è iniziata non c'era nulla da monitorare.
Il campo description è la riga con il maggiore impatto sull'attivazione della skill
All'avvio, l'agent carica nel proprio contesto name e description di ogni skill disponibile. Non carica i relativi corpi. Quando arriva la richiesta, quella singola riga è l'unica base per decidere se la skill è pertinente. Di conseguenza, un corpo perfetto associato a una description vaga non viene mai letto.
Scrivi la description alla terza persona. «Tests and reloads nginx safely» funziona. «I can help you with nginx» invece no, perché il testo viene inserito nel system prompt e la prima persona fa sembrare che sia il modello a parlare di se stesso.
Inserisci due elementi: cosa fa la skill e in quale condizione si applica. Metti prima il caso d'uso più importante, perché Claude Code tronca la voce dell'elenco a 1,536 caratteri. È disponibile anche un campo opzionale when_to_use per ulteriori frasi di attivazione ed esempi di richieste; questo campo viene aggiunto alla description entro lo stesso limite.
Usa poi le parole che digiterai realmente. description: Helps with nginx non corrisponde a nulla, perché nessuno digita «helps with». La versione precedente contiene /etc/nginx, server block, reverse proxy e TLS (transport layer security) certificate path, cioè all'incirca il vocabolario di qualsiasi richiesta che dovrebbe attivarla.
Questo è il test per una description. Fornisci quella singola riga a una persona che non ha mai visto il corpo, insieme alla richiesta che stai per digitare, e chiedile se la skill è pertinente. Se non riesce a capirlo, non ci riuscirà neppure il modello.
Mantieni breve il corpo, perché resta nel contesto
Quando viene invocata, una skill entra nella conversazione come un unico messaggio e vi rimane per il resto della sessione. Claude Code non rilegge il file nei turni successivi. Ogni riga scritta rappresenta un costo per l'intera sessione, non per una sola risposta.
Anthropic consiglia di mantenere SKILL.md sotto le 500 righe e di spostare i dettagli in file separati. La compattazione mostra perché questo limite non è arbitrario. Quando la conversazione viene riepilogata per liberare spazio nel contesto, Claude Code riaggancia l'invocazione più recente di ogni skill, conserva solo i primi 5.000 token di ciascuna e riempie un budget combinato di 25.000 token iniziando dalla skill invocata più di recente. Una skill lunga viene troncata a metà. Più skill lunghe possono espellersi completamente a vicenda.
Scrivi quindi solo ciò che il modello non conosce già. Sa che cos'è nginx e che cosa fa un reverse proxy. Non conosce la regola interna relativa a reload su restart, e quella regola è l'unico motivo per cui esiste questo file.
Se la skill indica all'agente di eseguire uno script incluso nel pacchetto, specifica il percorso usando ${CLAUDE_SKILL_DIR}, in modo che venga risolto indipendentemente dalla posizione di installazione della skill, e autorizza preventivamente lo stesso comando per evitare che l'esecuzione si interrompa in attesa di una richiesta di autorizzazione.
---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---L'autorizzazione copre il turno in cui è stata invocata la skill e viene rimossa quando invii il messaggio successivo. Non diventa quindi silenziosamente un'autorizzazione permanente.
Come dimostrare che la skill viene attivata
Osservare il caricamento di una skill dimostra che l'agente l'ha individuata. Non dimostra che la risposta sia cambiata. Verifica entrambi gli aspetti e fallo in una sessione nuova, perché la sessione in cui hai scritto la skill contiene già tutto ciò che hai dichiarato durante la scrittura. Questo contesto residuo nasconde le lacune del file.
- Avvia una nuova sessione con
claudenel progetto. - Scrivi la richiesta come faresti in una normale giornata di lavoro, usando parole tue e senza nominare la skill.
- Verifica che la skill venga invocata. Se non si attiva, correggi la descrizione. Il corpo della skill non è ancora il problema.
- Invocala manualmente con
/nginx-config-changescome controllo. Se il comportamento è corretto quando la invochi manualmente ma non quando la richiesta dovrebbe attivarla, il problema riguarda il trigger e non le istruzioni. - Esegui la stessa richiesta con la skill disattivata e confronta le due risposte. Nel menu
/skills, seleziona la skill e premiSpaceper portarne lo stato aoff, quindi premiEnterper salvare. Questa operazione scrive una voceskillOverridesin.claude/settings.local.json; premendo di nuovoSpace, lo stato torna aonal termine della verifica. - Scrivi un paio di richieste che non dovrebbero attivare la skill e verifica che rimanga inattiva.
Per automatizzare questa procedura, installa il plugin skill-creator dal marketplace ufficiale.
/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-officialSe l'output dell'installazione contiene Run /reload-plugins to activate., esegui quel comando. Poi chiedi a Claude di valutare la skill indicandone il nome. Il plugin memorizza i casi di test in evals/evals.json nella directory della skill ed esegue ogni caso nel proprio subagent, quindi ogni esecuzione parte da un contesto pulito. Scrive quindi un confronto tra l'esecuzione con la skill e quella senza la skill. Questo è il valore corretto da considerare: il miglioramento del tasso di superamento misurato rispetto ai token e al tempo richiesti dalla skill.
Una skill può includere anche il proprio metodo di verifica, invece di affidarlo a un'esecuzione eval separata. È ciò che fa la skill Old Coder quando chiede all'agente di restituire un report delle evidenze che puoi eseguire di nuovo personalmente.
Modalità di errore: la skill non viene mai attivata
Inserisci la richiesta, l'agent esegue di nuovo l'operazione errata e non compare alcuna riga della skill. Verifica questi punti nell'ordine indicato.
- La descrizione spiega che cosa fa la skill, ma non specifica quando usarla. Di conseguenza, nulla nella richiesta corrisponde alla descrizione.
- La descrizione evita le parole che inserisci. Se scrivi "nginx", la descrizione deve contenere "nginx".
disable-model-invocation: trueè impostato nel frontmatter. In questo modo la descrizione viene esclusa completamente dal contesto del modello e la skill può essere richiamata soltanto da te con/name.- Un glob
pathsnel frontmatter limita l'attivazione ai file corrispondenti. Il file su cui stai lavorando non corrisponde al criterio. - La skill si trova in una directory
.claude/skills/annidata sotto la directory iniziale. Queste skill vengono caricate solo dopo che l'agent legge o modifica un file all'interno di quella sottodirectory. Fino a quel momento, la skill non è disponibile.
Modalità di errore: la skill si attiva continuamente
Il problema opposto si verifica quando la descrizione è così ampia che la skill si attiva durante attività non correlate. «Usare la skill quando si lavora sul server» corrisponde a quasi qualsiasi richiesta in un repository server. Il corpo viene quindi caricato per attività che non può supportare e resta nel contesto per il resto della sessione.
Restringi la descrizione alla condizione effettivamente rilevante e indica i file o i comandi a cui si applica. Aggiungi un glob paths quando la skill si applica soltanto a determinati file. Per qualsiasi operazione con effetti collaterali, come un deploy o un commit, imposta disable-model-invocation: true e richiamala tu tramite /name, in modo che l'agente non decida autonomamente che sia il momento opportuno per eseguire il deploy.
Modalità di errore: la competenza deve stare nel file delle regole
Un file delle regole come CLAUDE.md o AGENTS.md viene caricato all'inizio di ogni sessione e si applica a ogni attività. Il contenuto di una skill viene caricato solo quando la skill viene attivata. La frequenza è il criterio decisivo. Un fatto valido per ogni attività nel repository, come il package manager utilizzato, deve stare nel file delle regole. Una procedura applicabile solo a una parte limitata delle attività, come la regola nginx precedente, deve stare in una skill, dove non comporta costi nei giorni in cui nessuno modifica nginx.
Il vero errore consiste nel inserirla in entrambi i punti. Le due copie diventano diverse nel tempo e, quando l'agent esegue un'azione errata, non è possibile stabilire quale copia abbia seguito. Scegli una sola posizione per ogni istruzione. Se una regola si trova già in una sola posizione e viene comunque ignorata, si tratta di un problema diverso: prima di spostarla in una skill sperando che questo risolva il problema, conviene verificare i meccanismi alla base di un'istruzione ignorata. Il confine tra skill, server MCP e file delle regole consente di affrontare anche i casi più complessi, compreso quello in cui la scelta corretta è un server MCP (model context protocol) che fornisce all'agent un nuovo strumento invece di una nuova istruzione.
Condividila quando ha dimostrato il proprio valore
Una skill che resiste a una settimana di lavoro reale merita di essere salvata nel repository. Le skill di progetto in .claude/skills/ vengono revisionate come il codice e arrivano insieme al repository. Un collega che lo clona riceve quindi anche la correzione, senza dover eseguire passaggi di configurazione. Spostare una skill tra repository senza ricorrere al copia e incolla è un problema distinto, trattato in come condividere le skill degli agenti tra repository.
Una nota sulla portabilità. Claude Code accetta un elenco ampio di campi frontmatter, ma lo standard Agent Skills ne consente soltanto sei: name, description, license, compatibility, metadata e allowed-tools. Se carichi una skill su claude.ai o la prepari per la Skills API includendo altri elementi nel frontmatter, il caricamento fallisce completamente invece di ignorare il campo:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameLimita il frontmatter a questi sei campi. Lo stesso file potrà essere caricato in Claude Code e negli altri strumenti che leggono lo standard. Tuttavia, l'ambiente in cui il file viene caricato determina comunque ciò che la skill può fare, perché Cowork viene eseguito in un sandbox Anthropic, mentre Claude Code viene eseguito sul tuo computer o VPS. Di conseguenza, vale la pena portare la skill nginx descritta sopra nel checkout di un collega, ma è inutile in un sandbox che non può raggiungere il server. Scrivere istruzioni che restino efficaci anche passando a un modello diverso è un'attività separata, descritta in come scrivere skill compatibili con qualsiasi modello.
FAQ
Quanto deve essere lungo un file SKILL.md?
Mantienilo sotto le 500 righe e considera che la maggior parte delle skill utili sarà molto più breve. Il corpo viene inserito nel contesto quando la skill viene invocata e vi rimane per il resto della sessione. Ogni riga rappresenta quindi un costo ricorrente, non un costo una tantum. Sposta il materiale di riferimento più lungo in file separati nella directory della skill e collegali da SKILL.md, a un solo livello di profondità, in modo che l’agente li legga solo quando servono. Gli script inclusi vengono eseguiti anziché letti, quindi il loro costo corrisponde soltanto all’output.
Perché la mia skill non viene mai attivata?
La causa più comune è la descrizione, perché è l’unica parte della skill presente nel contesto quando il modello decide. Assicurati che indichi quando usare la skill, non soltanto cosa fa, e che contenga le parole che usi effettivamente nelle richieste. Se la descrizione è corretta, controlla il frontmatter per disable-model-invocation: true, che nasconde completamente la skill al modello, e per un glob paths che la limita ai file che non stai modificando. Un’altra causa può essere una skill contenuta in una directory .claude/skills/ annidata sotto la directory di avvio: viene caricata solo dopo che l’agente legge o modifica un file in quella sottodirectory.
Deve essere una skill o una riga nel mio file delle regole?
Chiediti a quanti dei tuoi task si applica. Un file delle regole viene caricato in ogni sessione, quindi dovrebbe contenere informazioni valide per ogni task, come il gestore dei pacchetti o la convenzione per i nomi dei branch. Una skill viene caricata solo quando si attiva, quindi è il posto corretto per una procedura rilevante per una parte ridotta dei task. Non scrivere mai la stessa istruzione in entrambe le posizioni, perché le due copie possono divergere e non riusciresti più a stabilire quale abbia seguito l’agente.
Come faccio a sapere se una skill è stata davvero utile?
Confrontala con una baseline. Raccogli alcune richieste reali, esegui ciascuna richiesta in una sessione nuova con la skill disponibile, quindi eseguila di nuovo con la skill disattivata dal menu /skills e leggi le due risposte una accanto all’altra. Una sessione nuova è importante perché la conversazione in cui hai scritto la skill contiene ancora le tue spiegazioni; questo può far sembrare completo un file incompleto. Il plugin skill-creator esegue questo confronto al posto tuo e indica il tasso di superamento accanto al costo in token.
Posso usare lo stesso SKILL.md con un agente diverso?
Sì, purché rimanga nei campi definiti dallo standard Agent Skills: name, description, license, compatibility, metadata e allowed-tools. Claude Code accetta molti altri campi e supporta anche funzionalità nel corpo, come l’iniezione di comandi shell, che altri strumenti non eseguono. Il caricamento di una skill con un campo non previsto dallo standard non riesce e restituisce un errore esplicito con l’elenco delle proprietà consentite. Decidi quindi in anticipo se la skill deve rimanere in Claude Code oppure essere trasferibile.