Come scrivere una skill personalizzata per un agente

Scrivi la tua skill per l’agente a partire da un errore reale

Il modo migliore per scrivere una skill personalizzata per il tuo agente consiste nel ricavarla da un errore reale. Individua un’attività che il coding agent ha eseguito in modo errato per due volte, annota la correzione che hai digitato in entrambe le occasioni e salva quella correzione in un file SKILL.md che l’agente possa caricare autonomamente. Da quel momento, tutto il resto è meccanico: la struttura del file e l’unica riga che determina se la skill verrà mai attivata.

L’ordine è importante. Una skill scritta a partire dall’immaginazione documenta un problema che non hai mai avuto 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’agente la gestisce correttamente. Se il formato è nuovo per te, leggi prima che cosa sono le skill per gli agenti e come le carica un agente, quindi torna qui e scrivine una.

Inizia da un'attività che l'agente ha eseguito male due volte

Una volta può essere un caso. Due volte indicano 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. Modifica /etc/nginx/conf.d/app.conf, quindi esegue sudo systemctl restart nginx. La modifica contiene un errore di sintassi, quindi nginx non si avvia e il sito resta inattivo finché non correggi il problema:

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 il problema nella chat. Verifica la configurazione con sudo nginx -t prima di intervenire sul servizio, quindi applica la modifica con reload invece di restart. Una settimana dopo, durante un'attività diversa, si verifica lo stesso errore. La seconda volta è il segnale.

Annota subito due elementi, mentre l'errore è ancora sotto gli occhi: la richiesta che hai digitato e la correzione che hai fornito, usando le parole esatte che hai scelto. Queste due righe diventano la skill. La richiesta indica quali condizioni deve soddisfare il trigger. La correzione costituisce l'intero contenuto.

Le linee guida di authoring di Anthropic indicano proprio questo come primo passaggio. Esegui l'agente su attività rappresentative senza skill, annota i punti in cui commette errori, quindi scrivi le istruzioni minime necessarie per correggerli. Gli errori costituiscono la specifica. Una skill che non puoi ricondurre a un errore concreto, in genere, è una skill di cui nessuno aveva bisogno.

Per un esempio completo dello stesso processo di distillazione, puoi leggere Ponytail trasforma in una skill un errore ripetuto: l'agente riscrive una parte molto più ampia di quella richiesta.

Anatomia di una skill

Una skill è una directory che contiene un unico file obbligatorio.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.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 marcatori ---, 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: fino a 64 caratteri, solo lettere minuscole, cifre e trattini; inoltre non può contenere le parole claude o anthropic. In una skill personale o di progetto, questo è 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 deve essere usata, fino a 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'agente legge su richiesta. Collegali da SKILL.md e 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'agente esegue invece di leggerli. Solo il relativo output occupa il 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, una serie di file gates e un contratto PLAN.md, così impedisce all'agente di dichiarare concluso il lavoro mentre interi rami restano non esaminati.

La posizione della directory determina chi può usare la skill.

• .claude/skills/<name>/SKILL.md nel repository: solo per questo progetto, e viene distribuita a chiunque cloni il repository.
• ~/.claude/skills/<name>/SKILL.md: per ogni progetto sul tuo computer, ma non su quello di altre persone.
• <plugin>/skills/<name>/SKILL.md: distribuita all'interno di un plugin, disponibile ovunque il plugin sia abilitato.

Creane una con mkdir -p .claude/skills/nginx-config-changes e scrivi il file. Claude Code monitora queste directory, quindi la modifica di una skill esistente diventa effettiva nella sessione in corso. 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 nel file

All'avvio, l'agent carica nel proprio contesto name e description di ogni skill disponibile. Non carica i contenuti. Quando arriva la richiesta, quella riga è l'unica base su cui decidere se la skill è pertinente; quindi un contenuto perfetto dietro una description vaga non verrà mai letto.

Scrivi la description alla terza persona. «Tests and reloads nginx safely» funziona. «I can help you with nginx» no, perché il testo viene inserito nel system prompt e la prima persona fa sembrare che sia il modello a parlare di sé.

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. Esiste anche un campo when_to_use opzionale per ulteriori frasi di attivazione ed esempi di richieste, che 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, che rappresentano approssimativamente il vocabolario di ogni richiesta che dovrebbe attivarla.

Ecco il test per una description. Mostra quella singola riga a qualcuno che non ha mai visto il contenuto, insieme alla richiesta che stai per digitare, e chiedigli se la skill si applica. Se non riesce a capirlo, non può riuscirci neppure il modello.

Mantieni contenuto il corpo, perché resta nel contesto

Quando viene richiamata una skill, il relativo contenuto elaborato entra nella conversazione come un messaggio e vi rimane per il resto della sessione. Claude Code non rilegge il file nei turni successivi. Ogni riga scritta è un costo sostenuto per l’intera sessione, non per una sola risposta.

Anthropic consiglia di mantenere SKILL.md al di sotto di 500 righe e di spostare i dettagli in file separati. La compattazione spiega perché questo valore 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 escludersi completamente a vicenda.

Scrivi quindi solo ciò che il modello non conosce già. Sa cos’è nginx e cosa fa un reverse proxy. Non conosce la regola interna relativa a reload sopra 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 directory in cui è installata la skill, e autorizza preventivamente lo stesso comando affinché l’esecuzione non si interrompa per 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 che ha invocato la skill e viene revocata quando invii il messaggio successivo, quindi non diventa inavvertitamente un permesso permanente.

Come dimostrare che la skill viene attivata

Osservare il caricamento di una skill indica che l'agent l'ha trovata. Non indica però 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 detto durante la scrittura. Questo contesto residuo nasconde le lacune presenti nel file.

1. Avvia una nuova sessione con claude nel progetto.
2. Scrivi la richiesta come faresti in una normale giornata di lavoro, usando parole tue e senza nominare la skill.
3. Verifica che venga invocata. Se la skill non viene attivata, correggi la descrizione. Il problema non è ancora nel corpo della skill.
4. Invocala manualmente con /nginx-config-changes come controllo. Se il comportamento è corretto quando viene invocata manualmente e non lo è quando viene invocata dalla richiesta, il problema riguarda l'attivazione e non le istruzioni.
5. Esegui la stessa richiesta con la skill disattivata e confronta le due risposte. Nel menu /skills, seleziona la skill e premi Space per portarne lo stato a off, quindi premi Enter per salvare. Questa operazione scrive una voce skillOverrides in .claude/settings.local.json. Quando hai finito, premi di nuovo Space per riportarla ciclicamente a on.
6. Scrivi un paio di richieste che non dovrebbero attivare la skill e verifica che non intervenga.

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-official

Se l'output dell'installazione indica Run /reload-plugins to activate., esegui quel comando. Quindi chiedi a Claude di valutare la skill specificandone il nome. Il plugin memorizza i casi di test in evals/evals.json all'interno della directory della skill ed esegue ogni caso nel proprio subagent, così ogni esecuzione parte da un contesto pulito. Scrive quindi un confronto tra with-skill e without-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ò anche contenere la propria verifica, invece di delegarla a un'esecuzione eval separata. È ciò che fa la skill Old Coder quando chiede all'agent di restituire un rapporto delle evidenze che puoi eseguire di nuovo in autonomia.

Modalità di errore: la skill non viene mai attivata

Inserisci la richiesta, l'agente esegue nuovamente 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 mai quando usarla. Di conseguenza, nulla nella richiesta corrisponde alla descrizione.
• La descrizione non contiene le parole che utilizzi. Se scrivi "nginx", la descrizione deve contenere nginx.
• Nel frontmatter è impostato disable-model-invocation: true. In questo modo la descrizione viene completamente esclusa dal contesto del modello e la skill può essere richiamata soltanto da te tramite /name.
• Un glob paths nel 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 di avvio. Queste skill vengono caricate solo dopo che l'agente 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ì generica che la skill si attiva durante attività non correlate. "Usa questa skill quando lavori 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.

Limita la descrizione alla condizione realmente rilevante e indica i file o i comandi interessati. 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 richiama la skill manualmente con /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 tutte le attività. Il contenuto di una competenza viene caricato solo quando la competenza viene attivata. La frequenza è il criterio decisivo. Un fatto valido per tutte le attività del repository, come il gestore dei pacchetti utilizzato, appartiene al file delle regole. Una procedura applicabile solo a una parte limitata delle attività, come la regola nginx precedente, appartiene a una competenza, dove non comporta costi nei giorni in cui nessuno modifica nginx.

Il vero errore consiste nel inserirla in entrambi i punti. Le due copie divergono e, quando l’agente esegue l’azione sbagliata, non è possibile capire quale copia abbia seguito. Ogni istruzione deve avere una sola collocazione. Se una regola si trova già in una sola collocazione e viene comunque ignorata, si tratta di un problema diverso; prima di spostarla in una competenza nella speranza che questo risolva il problema, conviene verificare i meccanismi alla base di un’istruzione ignorata. Il confine tra competenze, server MCP e file delle regole consente di gestire anche i casi più complessi, incluso quello in cui la soluzione corretta è un server MCP (model context protocol) che fornisce all’agente un nuovo strumento anziché una nuova istruzione.

Condividila quando ha dimostrato il proprio valore

Una skill che supera una settimana di lavoro reale merita di essere sottoposta al controllo di versione. Le skill di progetto in .claude/skills/ vengono revisionate come il codice e arrivano insieme al repository, quindi un collega che lo clona riceve la correzione senza dover eseguire alcuna configurazione. Spostare una skill tra repository senza usare il copia e incolla è un problema distinto, trattato in come condividere le skill degli agenti tra repository.

Una nota sulla portabilità. Claude Code accetta un lungo elenco di campi frontmatter, ma lo standard Agent Skills ne consente soltanto sei: name, description, license, compatibility, metadata e allowed-tools. Se carichi su claude.ai una skill con altri elementi nel frontmatter, oppure la prepari per la Skills API, 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, name

Limita il frontmatter a questi sei campi e lo stesso file verrà caricato in Claude Code e in tutti gli altri strumenti che leggono lo standard. L'ambiente in cui il file viene caricato determina comunque ciò che può fare, perché Cowork viene eseguito in una sandbox Anthropic, mentre Claude Code viene eseguito sul tuo computer o VPS, quindi vale la pena portare la skill nginx precedente nel checkout di un collega, ma è inutile in una sandbox che non può raggiungere il server. Scrivere istruzioni che restino efficaci anche con un modello diverso è un'attività separata, descritta in 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 del file entra nella conversazione quando la skill viene richiamata 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ù esteso 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 invece di essere letti, quindi il loro costo è limitato all'output.

Perché la mia skill non viene mai attivata?

La descrizione è di norma la causa, perché è l'unica parte della skill presente nel contesto quando il modello decide. Assicurati che specifichi quando usare la skill, non soltanto che cosa fa, e che contenga le parole che usi effettivamente nelle richieste. Se la descrizione è corretta, controlla nel frontmatter la presenza di disable-model-invocation: true, che nasconde completamente la skill al modello, e di un glob paths che la limita ai file che non stai modificando. Un'altra causa può essere una skill in una directory .claude/skills/ annidata sotto la directory di partenza: 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 quante delle tue attività si applica. Un file delle regole viene caricato in ogni sessione, quindi deve contenere fatti validi per ogni attività, come il gestore dei pacchetti o la convenzione per i nomi dei branch. Una skill viene caricata solo quando si attiva, quindi è la scelta corretta per una procedura rilevante per una parte limitata delle attività. Non scrivere mai la stessa istruzione in entrambi i posti, perché le due copie diventano incoerenti e non puoi più stabilire quale delle due abbia seguito l'agente.

Come posso sapere se una skill è stata realmente utile?

Confrontala con una baseline. Raccogli alcune richieste reali, esegui ciascuna richiesta in una nuova sessione con la skill disponibile, quindi ripetila con la skill disattivata dal menu /skills e leggi le due risposte affiancate. Una nuova sessione è importante perché la conversazione in cui hai scritto la skill contiene ancora le tue spiegazioni, facendo sembrare completo un file incompleto. Il plugin skill-creator esegue questo confronto per te e indica il tasso di superamento accanto al costo in token.

Posso usare lo stesso SKILL.md con un agente diverso?

Sì, purché resti 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 del file, 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 subito se la skill deve restare in Claude Code o se deve essere trasferibile.