Che cos'è davvero una skill dell'agente?

Che cos’è realmente una skill dell’agente

Una skill dell’agente è una directory su disco che contiene un file denominato SKILL.md. Questo file contiene un nome, una breve descrizione e istruzioni scritte in Markdown semplice. L’agente carica la descrizione all’avvio e legge le istruzioni soltanto quando la richiesta corrisponde a tale descrizione. Quasi tutto il resto del funzionamento delle skill deriva da queste due frasi.

La directory può contenere più file. La specifica Agent Skills definisce tre directory opzionali: scripts/ per il codice eseguito dall’agente, references/ per i documenti che l’agente legge quando ne ha bisogno e assets/ per template e dati. Nessuna di queste directory è obbligatoria. Una directory che contiene soltanto un file SKILL.md è una skill completa.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

La descrizione è la parte che viene spesso sottovalutata. È l’unico testo che l’agente vede prima di decidere se aprire la skill, quindi deve indicare che cosa fa la skill e quando usarla, usando le parole che una persona digiterebbe realmente.

Perché una skill costa quasi nulla finché non viene utilizzata

Questo è l’argomento che rende utile comprendere il formato, e riguarda il contesto, non le funzionalità. Il caricamento avviene per fasi, secondo il meccanismo che la specifica chiama divulgazione progressiva.

All’avvio, l’agente carica il name e il description di ogni skill installata, e nient’altro. La specifica Agent Skills indica un valore di circa 100 token per skill (indicazione pubblicata ad agosto 2026). Installare una dozzina di skill consuma quindi all’incirca il contesto di un paragrafo lungo.

Quando una richiesta corrisponde a una descrizione, l’agente legge il contenuto di quel singolo SKILL.md. La specifica raccomanda di mantenere il contenuto sotto i 5.000 token e il file sotto le 500 righe. I file in references/ e scripts/ non hanno ancora alcun costo. Un file di riferimento viene caricato solo se le istruzioni indirizzano l’agente verso di esso. Uno script incluso funziona in modo diverso: l’agente lo esegue tramite la shell, quindi il codice sorgente dello script non entra mai nella finestra di contesto e vi entra soltanto il suo output.

Confrontiamo questo approccio con quello a cui si ricorre per primo: un unico prompt enorme. Ogni riga di un system prompt o di un file di istruzioni sempre attivo viene conteggiata a ogni richiesta, in ogni sessione, anche quando l’attività non ne ha bisogno, e compete per l’attenzione con la domanda effettiva. Diecimila token di istruzioni permanenti sono un costo da sostenere anche solo per chiedere che ora è. Una dozzina di skill costa circa 1.200 token quando è inattiva e si espande solo per l’attività che ne ha bisogno. Questo è il motivo per cui le skill sono utili e per cui una piccola libreria è preferibile a un prompt più lungo.

C’è una precisazione che spesso viene trascurata. Quando una skill viene caricata, il suo contenuto rimane nel contesto per il resto della sessione. Di conseguenza, un SKILL.md lungo è un costo ricorrente, non un costo una tantum. Spostare i dettagli in references/ non è una questione di ordine. È il funzionamento previsto dal meccanismo.

Una skill dell’agente non è una chiamata a uno strumento

Uno strumento, chiamato anche chiamata di funzione, è un’operazione che il modello può invocare. L’harness invia al modello uno schema con un nome, una descrizione e la struttura degli argomenti. Il modello emette una chiamata, il codice la esegue e il risultato torna come messaggio. Gli strumenti eseguono operazioni. Entrambe le parti di questo scambio appartengono a l’harness, cioè il programma che esegue il ciclo intorno al modello, che è anche il componente che legge le descrizioni delle skill all’avvio e decide quando aprirne una.

Una skill non esegue nulla autonomamente. L’agente la legge, quindi agisce usando gli strumenti che ha già a disposizione. Il modello non può passare argomenti a una skill come fa con uno strumento. Una skill può invece indicare al modello quali strumenti usare, in quale ordine e quali controlli eseguire al termine.

In sintesi: uno strumento fornisce a un agente una nuova capacità, mentre una skill gli fornisce il criterio per usare una capacità che possiede già. Se un passaggio deve produrre ogni volta un risultato esatto e validato, è preferibile usare uno strumento o uno script. Se un passaggio richiede di applicare lo stesso ragionamento in modo coerente, è preferibile usare una skill. Una skill può consistere soltanto in criteri decisionali e restare comunque quella usata più spesso, come mostra Ponytail, che spinge un agente di coding ad apportare la modifica minima necessaria: non aggiunge nuove capacità e cambia soltanto il modo in cui l’agente usa quelle già disponibili.

Un’agent skill non è un server MCP

MCP (model context protocol) è un protocollo per collegare un agente a un sistema esterno. Un server MCP è un processo che viene eseguito, usa quel protocollo ed espone strumenti all’agente. In genere richiede configurazione, credenziali e un comando locale oppure un endpoint di rete. Una skill è una directory che contiene un file Markdown. Non prevede processi, porte o protocolli.

Anche il consumo di contesto è diverso. Ogni strumento esposto da un server MCP include un nome, una descrizione e uno schema degli argomenti; per impostazione predefinita, questi elementi vengono inseriti nella richiesta per l’intera sessione, indipendentemente dal loro utilizzo. Alcuni client hanno iniziato a recuperare gli schemi degli strumenti su richiesta, ma il caricamento iniziale è ancora la modalità più comune. Una skill inattiva occupa una sola riga di testo.

I due componenti sono complementari e le configurazioni più efficaci li usano entrambi. Il server MCP fornisce l’accesso. La skill fornisce la procedura: quali strumenti chiamare per il flusso di lavoro effettivo del team, in quale ordine e quali caratteristiche deve avere un buon risultato. Se gestisci un server autonomamente, eseguire server MCP su un VPS illustra questo aspetto.

Un agent skill non è un system prompt né un file AGENTS.md

Entrambe sono istruzioni in Markdown, quindi la confusione è comprensibile. La differenza riguarda il momento in cui vengono caricate. AGENTS.md, CLAUDE.md e il prompt di sistema sono sempre attivi. Una skill viene attivata su richiesta. Gli stili di output di Claude Code si collocano all’estremo opposto rispetto alle istruzioni sempre attive, perché la scelta di uno stile modifica direttamente il prompt di sistema. Di conseguenza, influenza ogni risposta della sessione, comprese quelle per cui non viene mai usata alcuna skill.

La verifica consiste in una sola domanda: ignorare questo paragrafo sarebbe sbagliato per un'attività che non ha nulla a che fare con l'argomento? Le regole relative allo stile del progetto, al comando di build e alla denominazione dei branch si applicano a ogni attività, quindi appartengono al file sempre attivo, che viene caricato ogni volta. La checklist di rilascio che esegui due volte al mese non si applica a ogni attività, quindi appartiene a uno skill. Quando una sezione del file sempre attivo si trasforma in una procedura numerata, è il segnale che va spostata.

Anche questi file hanno convenzioni specifiche che è importante applicare correttamente. Consulta cosa inserire in AGENTS.md e cosa inserire nel file destinato agli utenti e un file design.md che descrive la struttura di una codebase per i due file che utilizziamo.

Come si presenta una skill minima

In Claude Code, le skill personali si trovano in ~/.claude/skills/<name>/SKILL.md e si applicano a tutti i progetti. Le skill del progetto si trovano in .claude/skills/<name>/SKILL.md e vengono sottoposte a commit in git, quindi sono disponibili a ogni persona e a ogni agente che lavora in quel repository. GitHub Copilot e VS Code leggono invece le skill dell'area di lavoro da .github/skills/. Il file contenuto al suo interno è lo stesso.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Questa è una skill completa. Il nome della directory diventa il comando da digitare, quindi in questo caso è /restore-drill. In Claude Code, il menu /skills elenca gli elementi installati ed è il modo più rapido per verificare che il file sia stato rilevato. Se non compare nel menu, il nome non è corretto: il file deve chiamarsi SKILL.md e il nome della directory deve contenere solo lettere minuscole, cifre e singoli trattini. La stessa procedura, scritta in modo che l'agente possa eseguirla di nuovo, è un complemento naturale dei backup restic pianificati su un VPS, perché l'esecuzione del backup non equivale al ripristino del backup.

Quando una skill dovrebbe essere uno script

Qualsiasi passaggio che produce ogni volta una sola risposta corretta dovrebbe essere uno script. La skill va ridotta a poche righe che indicano quando eseguirlo e come interpretare l'output. Le ragioni sono due, ed entrambe sono pratiche.

Primo, il codice sorgente di uno script non entra mai nella finestra di contesto. Un parser di 300 righe richiede soltanto il suo output, mentre la stessa logica espressa come istruzioni Markdown richiede ogni volta tutto il testo quando la skill viene caricata.

Secondo, uno script restituisce la stessa risposta a ogni esecuzione. Se a un modello viene chiesto di ricavare nuovamente la stessa regola di analisi dei log a ogni esecuzione, in una giornata negativa la applicherà in modo leggermente diverso. Il problema potrebbe non essere rilevato finché due numeri non risultano discordanti.

Dividete quindi il lavoro in base alla sua natura. «Analizza il CSV e stampa ogni riga in cui il totale non corrisponde alle singole voci» è un'attività da script. «Esamina le righe stampate dallo script e spiega quali sembrano contenere un errore di inserimento dati» è un'istruzione per una skill. Mantenere il giudizio in Markdown e il comportamento deterministico nel codice segue lo stesso principio di creare un loop che un agente possa eseguire senza la vostra supervisione.

Perché la mia skill non si attiva mai?

Perché il suo description descrive cosa fa la skill, ma non indica mai quando usarla. Quella riga è tutto ciò che l'agente deve confrontare con la richiesta. «Aiuta con le attività sui database» non corrisponde a nulla di specifico. «Esegue una migrazione dello schema sul database di staging. Usare quando l'utente chiede di migrare una tabella, aggiungere una colonna o modificare uno schema» contiene le parole che una persona digita effettivamente, quindi la skill si attiva.

Il problema opposto è la skill che si attiva continuamente. Una descrizione come «Usare per qualsiasi modifica al codice in questo repository» corrisponde a tutto, quindi il corpo viene caricato per ogni attività e rimane nel contesto per il resto della sessione. Limita la descrizione al caso previsto. In Claude Code puoi anche impostare disable-model-invocation: true nel frontmatter. In questo modo disabiliti il caricamento automatico, ma mantieni la skill disponibile quando ne digiti il nome.

Il terzo problema è la skill che duplica uno strumento. Istruzioni che dicono all'agente di curl un'API già esposta dal relativo server MCP, oppure di cercare nei file con grep quando l'harness dispone di uno strumento di ricerca, aggiungono un percorso più lento e due insiemi di istruzioni che possono entrare in conflitto. Elimina la duplicazione e descrivi invece l'obiettivo.

Non cercare di indovinare quale dei tre problemi hai. Esegui lo stesso prompt 2 volte in una sessione nuova: una volta con la skill disponibile e una volta dopo averla disattivata. Poi confronta le risposte. La sessione nuova è importante, perché quella in cui hai scritto la skill contiene già tutto ciò che la skill descrive. Questo nasconde le lacune della versione scritta. Il plugin skill-creator di Anthropic automatizza questo confronto in Claude Code. Genera anche prompt che dovrebbero e non dovrebbero attivare la skill e misura la frequenza di attivazione per ciascun prompt.

È un formato proprietario o uno standard?

Anthropic ha pubblicato il formato alla fine del 2025, quindi lo ha rilasciato come standard aperto ospitato su agentskills.io. Ad agosto 2026, la specifica definisce i campi obbligatori name e description, i campi facoltativi license, compatibility, metadata e allowed-tools, le tre directory facoltative e il comportamento di caricamento progressivo. Include anche un validatore di riferimento, quindi skills-ref validate ./my-skill verifica una directory rispetto alla specifica prima che tu la condivida.

L'elenco dei client è l'indicatore più significativo. La stessa directory viene letta, tra gli altri, da Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands e opencode. Microsoft pubblica le proprie skill in questo formato su github.com/microsoft/skills e distribuisce uno strumento desktop chiamato Skill Recorder, che osserva l'esecuzione di un'attività, la ricostruisce come intento più sequenza ordinata di passaggi e salva il risultato come skill. Il fatto che un fornitore sviluppi un registratore il cui formato di output appartiene alla specifica di un altro soggetto è un buon segnale: il formato non è più una funzionalità di un singolo prodotto.

Cosa scrivere per prima cosa

Non pianificare una libreria. Aspetta di accorgerti che stai incollando le stesse istruzioni in una chat per la terza volta, quindi sposta quel testo in una SKILL.md ed elimina il testo incollato. La ripetizione che hai già sperimentato è l'unico criterio affidabile per individuare una competenza che vale la pena conservare. Una procedura di ricerca è un buon punto di partenza e una skill di ricerca basata sulla tua istanza SearXNG ne mostra la struttura.

Due abitudini mantengono la libreria in buone condizioni. Leggi ogni skill che non hai scritto tu prima di installarla, inclusi gli script, perché una skill contiene istruzioni che il tuo agente seguirà e codice che potrebbe eseguire: trattala come un software installato da uno sconosciuto. Tieni inoltre le credenziali fuori dalla cartella, perché una skill è un file di testo che può essere sottoposto a commit e condiviso. Come tenere i secret lontani dai tuoi agenti spiega invece dove collocare questi valori, mentre la roadmap per imparare a usare gli agenti quest'anno ordina le skill insieme al resto della configurazione.

FAQ

Qual è la differenza tra una skill dell'agente e un server MCP?

Un server MCP (Model Context Protocol) è un processo in esecuzione che espone strumenti a un agente tramite un protocollo. Richiede quindi configurazione e credenziali, e le definizioni degli strumenti occupano normalmente spazio nel contesto per l'intera sessione, anche se non vengono utilizzate. Una skill dell'agente è una cartella che contiene un file SKILL.md, senza processi né protocolli, e ha un costo di circa 100 token finché l'agente non decide di leggerla. Usa un server MCP per consentire a un agente di accedere a un sistema. Usa una skill per indicare all'agente la procedura corretta per usare quell'accesso. Molte configurazioni usano entrambi.

Le skill degli agenti funzionano solo con Claude Code?

No. Anthropic ha sviluppato il formato e lo ha poi rilasciato come standard aperto su agentskills.io. La stessa cartella viene letta da Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands e altri client. Ciò che cambia è il percorso in cui ogni client cerca le skill e i campi aggiuntivi del frontmatter che riconosce. Claude Code legge ~/.claude/skills/ e .claude/skills/, mentre GitHub Copilot e VS Code leggono .github/skills/ nel repository. Il file SKILL.md passa da un client all'altro senza modifiche.

Quante skill posso installare prima che le prestazioni peggiorino?

Il vincolo riguarda il budget di avvio, non il numero di skill. Ogni skill installata aggiunge il proprio nome e la propria descrizione, per circa 100 token secondo le indicazioni pubblicate nella specifica. Trenta skill costano quindi circa 3.000 token prima che venga utilizzata una di esse. Il primo aspetto a peggiorare è il riconoscimento della skill corretta, non la velocità: molte skill con descrizioni sovrapposte rendono più difficile per il modello scegliere quella appropriata. Scrivi descrizioni non sovrapposte ed elimina le skill che non usi più.

Questa istruzione deve essere inserita in una skill o in AGENTS.md?

Chiediti se si applica a tutte le attività del repository. I comandi di build, lo stile adottato dal progetto e le regole di denominazione si applicano a tutte le attività. Devono quindi trovarsi nel file sempre attivo, perché il suo caricamento a ogni esecuzione è previsto proprio per questo. Una procedura eseguita occasionalmente, come una checklist di rilascio o una simulazione di ripristino, dovrebbe essere una skill, così non ha alcun costo nelle attività che non ne hanno bisogno. Una sezione di AGENTS.md trasformata in una sequenza di passaggi numerati è in genere una skill pronta per essere spostata.