Come scrivere una skill personalizzata per un agent

Scrivi una skill personalizzata dell'agent a partire da un errore reale

Il modo migliore per scrivere una skill personalizzata dell'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 operativa: la struttura dei file e l'unica riga che determina se la skill verrà mai attivata.

L'ordine è importante. Una skill scritta per supposizione documenta un problema che non hai mai incontrato e continua comunque a consumare 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 che cosa sono le agent skill e come le carica un agent, quindi torna qui e scrivine una.

Parti 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 non disponibile 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 applicala con reload invece di restart. Una settimana dopo, durante un'attività diversa, si verifica lo stesso errore. La seconda volta è il segnale.

Annota due elementi mentre l'errore è ancora sotto esame: la richiesta che hai digitato e la correzione che hai fornito, usando le parole originali. Queste due righe diventano la skill. La richiesta indica ciò a cui deve corrispondere il trigger. La correzione costituisce l'intero contenuto.

Le indicazioni per la creazione delle skill pubblicate da Anthropic mettono questo passaggio al primo posto. Esegui l'agente su attività rappresentative senza skill, registra i punti in cui fallisce, quindi scrivi le istruzioni minime necessarie per correggere quei fallimenti. I fallimenti sono la specifica; se non puoi ricondurre una skill a uno di essi, di solito è una skill di cui nessuno aveva bisogno.

Per un esempio completo della stessa distillazione, puoi leggere da cima a fondo Ponytail trasforma un fallimento ripetuto, cioè un agente che riscrive molto più di quanto hai chiesto, in una skill prima di scrivere la tua.

Anatomia di una skill

Una skill è una directory che contiene un file obbligatorio.

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

SKILL.md si apre 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: fino a 64 caratteri, solo lettere minuscole, cifre e trattini; non può contenere le parole claude o anthropic. In una skill personale o di progetto è solo l'etichetta visualizzata. Il comando da digitare deriva dal nome della directory, quindi questa skill risponde a /nginx-config-changes.
• description: indica cosa fa la skill e quando usarla, per un massimo di 1.024 caratteri. Questa riga svolge il lavoro principale; la sezione successiva riguarda esclusivamente questo aspetto.
• Il corpo: 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, perché un file referenziato da un altro file referenziato spesso viene letto solo in parte.
• scripts/: file che l'agente esegue invece di leggere. Solo il relativo output consuma contesto, quindi uno script di 300 righe ha un costo ridotto.

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

• .claude/skills/<name>/SKILL.md nel repository: solo questo progetto, e la skill viene distribuita a tutti quelli che clonano il repository.
• ~/.claude/skills/<name>/SKILL.md: ogni progetto sul tuo computer, ma nessun progetto su altri computer.
• <plugin>/skills/<name>/SKILL.md: inclusa in 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 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'agente carica nel proprio contesto name e description di ogni skill disponibile. Non ne carica i contenuti. Quando arriva la richiesta, quella riga è l'unico elemento su cui si basa per decidere se la skill è pertinente. Di conseguenza, un contenuto perfetto con una description vaga non viene mai letto.

Scrivi la description alla terza persona. Tests and reloads nginx safely è corretto. I can help you with nginx non lo è, perché il testo viene inserito nel prompt di sistema, dove la prima persona sembra riferirsi al modello.

Includi due elementi: cosa fa la skill e in quale condizione si applica. Inserisci prima il caso d'uso più importante, perché Claude Code tronca la voce dell'elenco a 1,536 caratteri. È disponibile anche un campo when_to_use facoltativo per ulteriori frasi di attivazione ed esempi di richieste. Questo campo viene aggiunto alla description entro lo stesso limite.

Usa quindi le parole che digiterai realmente. description: Helps with nginx non trova corrispondenze, perché nessuno digita helps with. La versione precedente contiene /etc/nginx, server block, reverse proxy e TLS (transport layer security) certificate path, che corrispondono all'incirca al vocabolario di qualsiasi richiesta che dovrebbe attivarla.

Ecco il test per una description. Fornisci quella singola riga a una persona che non ha mai visto il contenuto della skill, insieme alla richiesta che stai per digitare, e chiedile se la skill è pertinente. Se non riesce a stabilirlo, non può farlo nemmeno il modello.

Mantieni il corpo breve, perché resta nel contesto

Quando viene richiamata una skill, il suo contenuto renderizzato 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 ha 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 spiega perché questo numero non è arbitrario. Quando la conversazione viene riepilogata per liberare spazio nel contesto, Claude Code riassocia 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 richiamata più di recente. Una skill lunga viene troncata a metà. Diverse skill lunghe possono estromettersi 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 oltre restart, e questa regola è l'unico motivo per cui esiste questo file.

Se la skill indica all'agente di eseguire uno script incluso, specifica il percorso usando ${CLAUDE_SKILL_DIR}, in modo che venga risolto indipendentemente dalla posizione in cui è installata la skill, e preautorizza lo stesso comando affinché l'esecuzione non si interrompa a causa 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 che ha richiamato la skill e viene revocata quando invii il messaggio successivo; non si trasforma quindi silenziosamente in 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 ripeti il controllo 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 nel file.

1. Avvia una nuova sessione con claude nel progetto.
2. Scrivi la richiesta come faresti durante una normale giornata di lavoro, usando parole tue e senza menzionare la skill.
3. Controlla che venga invocata. Se la skill non viene attivata, correggi la descrizione. Il corpo della skill non è ancora il problema.
4. Invocala manualmente con /nginx-config-changes come controllo. Se il comportamento è corretto quando la invochi manualmente ma non quando la richiesta la attiva, il problema riguarda il trigger e non le istruzioni.
5. Esegui la stessa richiesta con la skill disattivata e confronta le due risposte. Nel menu /skills, seleziona la skill, 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 terminato, premi di nuovo Space per riportarla a on.
6. Scrivi un paio di richieste che non dovrebbero attivare la skill e verifica che rimanga inattiva.

Per automatizzare questo ciclo, 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. Poi chiedi a Claude di valutare la skill specificandone 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 with-skill e without-skill, che rappresenta il dato più affidabile: il miglioramento del tasso di superamento misurato rispetto ai token e al tempo richiesti dalla skill.

Modalità di errore: la skill non viene mai attivata

Si inserisce la richiesta, l’agente esegue di nuovo l’operazione errata e non compare alcuna riga relativa alla skill. Verificare questi punti nell’ordine indicato.

• La descrizione spiega cosa fa la skill, ma non indica mai quando usarla. Di conseguenza, nulla nella richiesta corrisponde alla descrizione.
• La descrizione non contiene le parole utilizzate nella richiesta. Se si scrive "nginx", la descrizione deve contenere nginx.
• disable-model-invocation: true è impostato nel frontmatter. In questo modo la descrizione viene completamente esclusa dal contesto del modello e la skill può essere richiamata soltanto dall’utente tramite /name.
• Un glob paths nel frontmatter limita l’attivazione ai file corrispondenti. Il file su cui si sta lavorando non corrisponde al criterio.
• La skill si trova in una directory .claude/skills/ annidata sotto la directory di partenza. Queste skill vengono caricate solo dopo che l’agente legge o modifica un file in quella sottodirectory. Fino a quel momento, la skill non è disponibile.

Modalità di errore: l’abilità si attiva continuamente

Il problema opposto si verifica quando la descrizione è talmente generica da attivare l’abilità durante attività non correlate. «Usa questa abilità quando lavori sul server» corrisponde a quasi ogni richiesta in un repository server. Il corpo dell’abilità viene quindi caricato per attività in cui non è utile e rimane nel contesto per il resto della sessione.

Limita la descrizione alla condizione effettivamente rilevante e indica i file o i comandi coperti. Aggiungi un glob paths quando l’abilità 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 l’abilità manualmente con /name, in modo che l’agente non decida autonomamente che sia il momento opportuno per eseguire il deploy.

Modalità di errore: la skill deve trovarsi 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à del repository, come il package manager utilizzato, deve trovarsi nel file delle regole. Una procedura applicabile solo a una parte limitata delle attività, come la regola nginx precedente, deve trovarsi in una skill, perché non comporta alcun costo nei giorni in cui nessuno modifica nginx.

Il vero errore consiste nel duplicare l’istruzione in entrambe le posizioni. Le due copie divergono e, quando l’agente esegue un’operazione errata, non è possibile capire quale copia abbia seguito. Ogni istruzione deve avere una sola collocazione. il confine tra skill, server MCP e file delle regole analizza 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 a commit. Le skill di progetto in .claude/skills/ vengono revisionate come codice e distribuite insieme al repository. Un collega che clona il repository riceve quindi la correzione senza alcuna configurazione aggiuntiva. Spostare una skill tra repository senza copiare e incollare è 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 una skill su claude.ai o la prepari per la Skills API con 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, name

Limita il frontmatter a questi sei campi. Lo stesso file verrà così caricato in Claude Code e in qualsiasi altro strumento che legga lo standard. Scrivere istruzioni che restino efficaci quando vengono trasferite 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 del file viene inserito nella conversazione quando la skill viene invocata e vi resta 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à, così l'agente li legge solo quando servono. Gli script inclusi vengono eseguiti anziché letti, quindi il loro costo corrisponde soltanto al relativo output.

Perché la mia skill non viene mai attivata?

La causa più comune è la descrizione, perché è l'unica parte della skill disponibile nel contesto quando il modello decide se attivarla. Assicurati che indichi quando usare la skill, non soltanto cosa fa, e che contenga le parole che inserisci 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 è la presenza della 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.

È meglio usare una skill o aggiungere una riga al file delle regole?

Chiediti a quanti dei tuoi task si applica. Un file delle regole viene caricato in ogni sessione, quindi deve contenere informazioni valide per ogni task, come il package manager o la convenzione per i nomi dei branch. Una skill viene caricata solo quando si attiva, quindi è la scelta corretta per una procedura rilevante soltanto per una parte limitata dei task. Non scrivere mai la stessa istruzione in entrambi i posti: le due copie possono divergere e non puoi più stabilire quale delle due abbia seguito l'agente.

Come faccio a sapere se una skill è stata realmente utile?

Confrontala con una baseline. Raccogli alcune richieste reali, esegui ciascuna in una sessione nuova con la skill disponibile, quindi ripetile con la skill disattivata dal menu /skills e leggi entrambe le risposte affiancate. Una sessione nuova è 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 automaticamente e mostra 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 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 fin dall'inizio se la skill deve rimanere in Claude Code o essere trasferita.