Cosa sono davvero le skill per agenti?

Che cos’è realmente una skill per agenti

Una skill per agenti è una directory sul disco che contiene un file chiamato SKILL.md. Questo file contiene un nome, una breve descrizione e istruzioni scritte in Markdown semplice. L’agent carica la descrizione all’avvio e legge le istruzioni soltanto quando la richiesta corrisponde a quella descrizione. Quasi tutto il resto del funzionamento delle skill deriva da queste due regole.

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

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

La descrizione è l’elemento che viene più spesso sottovalutato. È l’unico testo che l’agent vede prima di decidere se aprire la skill. Deve quindi indicare 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 (linee guida pubblicate ad agosto 2026). Installare una dozzina di skill richiede quindi il contesto di un solo paragrafo lungo.

Quando una richiesta corrisponde a una descrizione, l’agente legge il corpo di quel SKILL.md. La specifica raccomanda di mantenere il corpo 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 quel file. 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; vi entra soltanto il relativo output.

Confronta questo approccio con quello a cui si ricorre per primo: un unico prompt enorme. Ogni riga di un prompt di sistema o di un file di istruzioni sempre attivo viene conteggiata a ogni richiesta e 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 l’ora. Una dozzina di skill costa circa 1.200 token a riposo e si espande soltanto per l’attività che ne ha bisogno. Questo è l’intero motivo per cui usare le skill, ed è per questo che una piccola libreria è migliore di un prompt più lungo.

C’è però un aspetto che spesso viene trascurato. Quando una skill viene caricata, il suo corpo resta nel contesto per il resto della sessione; quindi un SKILL.md lungo rappresenta un costo ricorrente, non un costo una tantum. Spostare i dettagli in references/ non è una semplice questione di ordine. È il meccanismo che funziona come previsto.

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

Uno strumento, chiamato anche function call, è 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.

Una skill non esegue nulla autonomamente. L'agente la legge e poi agisce usando gli strumenti che ha già a disposizione. Il modello non può passare argomenti a una skill nello stesso modo in cui li passa a uno strumento. Una skill può invece indicare al modello quali strumenti usare, in quale ordine e quali controlli eseguire al termine.

In breve: uno strumento fornisce a un agente una nuova capacità, mentre una skill gli fornisce criteri operativi per usare una capacità che possiede già. Se un passaggio deve produrre ogni volta un risultato esatto e convalidato, serve uno strumento o uno script. Se un passaggio richiede di applicare lo stesso ragionamento in modo coerente, serve una skill.

Un agent skill non è un server MCP

MCP (Model Context Protocol) è un protocollo per collegare un agent a un sistema esterno. Un server MCP è un processo che viene eseguito, utilizza quel protocollo ed espone strumenti all'agent. 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 differisce per lo stesso motivo. 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 tutta la durata della sessione, anche quando non vengono utilizzati. Alcuni client hanno iniziato a recuperare gli schemi degli strumenti su richiesta, ma il caricamento iniziale è ancora il comportamento più comune. Una skill inattiva consiste in una riga di testo.

I due componenti sono complementari e le configurazioni più efficaci li utilizzano 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 come deve essere un risultato corretto. Se gestisci un'infrastruttura autonoma, eseguire server MCP su un VPS descrive questo aspetto.

Una competenza dell’agente non è un prompt di sistema né un file AGENTS.md

Entrambi contengono istruzioni in formato Markdown, quindi è comprensibile confonderli. La differenza riguarda il momento in cui vengono caricati. AGENTS.md, CLAUDE.md e il prompt di sistema sono sempre attivi. Una competenza viene attivata su richiesta.

La verifica consiste in una sola domanda: ignorare questo paragrafo sarebbe sbagliato per un’attività che non ha nulla a che fare con esso? Lo stile del progetto, il comando di build e la regola per i nomi dei branch si applicano a ogni attività, quindi devono essere inseriti nel file sempre attivo, perché il suo scopo è proprio essere caricato ogni volta. La checklist di rilascio che esegui due volte al mese non si applica a ogni attività, quindi deve essere inserita in una competenza. Quando una sezione del file sempre attivo si è trasformata in una procedura numerata, è il momento di spostarla.

Anche questi file hanno convenzioni specifiche che è importante applicare correttamente. Consulta cosa inserire in AGENTS.md e cosa nel file per gli esseri umani e un design.md che spiega 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 salvate nel repository Git, quindi sono disponibili per ogni persona e 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 al loro 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 mostra 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, descritta in modo che l'agente possa eseguirla nuovamente, è un complemento naturale di backup restic pianificati su un VPS, perché l'esecuzione del backup non equivale al ripristino del backup.

Quando una competenza dovrebbe essere uno script

Ogni passaggio che produce sempre una sola risposta corretta dovrebbe essere uno script. La competenza 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 aggiunge soltanto il suo output, mentre la stessa logica descritta come istruzioni Markdown ne aggiunge l'intera lunghezza ogni volta che la competenza viene caricata.

Secondo, uno script restituisce la stessa risposta in esecuzioni diverse. Se a un modello viene chiesto di ricavare ogni volta la stessa regola per analizzare i log, in una giornata negativa potrebbe produrre una regola leggermente diversa. Il problema potrebbe emergere solo quando due numeri non coincidono.

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 compito per uno script. «Esamina le righe stampate dallo script e spiega quali sembrano contenere un errore di inserimento dati» è un'istruzione per una competenza. Mantenere il giudizio in Markdown e il comportamento deterministico nel codice segue lo stesso principio di creare un ciclo che un agente possa eseguire senza supervisione.

Perché la mia skill non viene mai attivata?

Perché il relativo description descrive cosa fa la skill, ma non specifica mai quando utilizzarla. Quella riga è tutto ciò che l'agent può confrontare con la richiesta. "Aiuta con le attività sui database" non corrisponde a nulla di preciso. "Esegue una migrazione dello schema sul database di staging. Utilizzare 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 viene attivata.

Il problema opposto riguarda la skill che viene attivata continuamente. Una descrizione come "Utilizzare per qualsiasi modifica al codice in questo repository" corrisponde a tutto. Il contenuto viene quindi caricato per ogni attività e resta 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 e mantieni la skill disponibile quando ne digiti il nome.

Il terzo problema riguarda la skill che duplica uno strumento. Istruzioni che dicono all'agent 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, creano un percorso più lento e due serie di istruzioni che possono entrare in conflitto. Elimina il duplicato e descrivi invece l'obiettivo.

Non cercare di indovinare quale dei tre problemi si verifica. Esegui lo stesso prompt 2 volte in una nuova sessione: una volta con la skill disponibile e una volta con la skill disattivata. Poi confronta le risposte. La nuova sessione è importante, perché la sessione in cui hai scritto la skill contiene già tutte le informazioni 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 ciascuno.

È il formato di un singolo fornitore 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 graduale. Include anche un validator di riferimento, quindi skills-ref validate ./my-skill verifica una directory rispetto alla specifica prima che venga condivisa.

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 all'indirizzo github.com/microsoft/skills e distribuisce uno strumento desktop chiamato Skill Recorder. Lo strumento osserva l'esecuzione di un'attività, la ricostruisce come un'intenzione seguita da una sequenza ordinata di passaggi e salva il risultato come skill. Un fornitore che sviluppa un recorder il cui formato di output appartiene alla specifica di un altro soggetto è un buon segnale del fatto che il formato non è più una funzionalità di un singolo prodotto.

Cosa scrivere per prima cosa

Non progettare una libreria in anticipo. Aspetta di sorprenderti a incollare per la terza volta le stesse istruzioni in una chat, quindi sposta quel testo in una SKILL.md ed elimina il testo incollato. La ripetizione che hai già sperimentato è l’unico indicatore affidabile che una procedura meriti di essere conservata. Una procedura di ricerca è un buon punto di partenza e una skill di ricerca basata sulla propria istanza SearXNG ne mostra la struttura.

Due abitudini mantengono la libreria in buono stato. Leggi ogni skill che non hai scritto tu prima di installarla, inclusi gli script, perché una skill contiene istruzioni che l’agente seguirà e codice che potrebbe eseguire: trattala come un software installato da una persona sconosciuta. Inoltre, non conservare le credenziali nella cartella, perché una skill è un file di testo che viene sottoposto a commit e condiviso. Come tenere i secret lontani dagli agenti spiega invece dove devono essere conservati questi valori, mentre la roadmap per imparare a usare gli agenti quest’anno colloca le skill nel giusto ordine insieme al resto della configurazione.

FAQ

Qual è la differenza tra una skill di un agent e un server MCP?

Un server MCP (Model Context Protocol) è un processo in esecuzione che espone strumenti a un agent tramite un protocollo. Richiede quindi configurazione e credenziali. Le definizioni degli strumenti occupano normalmente parte del contesto per l’intera sessione, anche quando non vengono utilizzate. Una skill di un agent è una directory che contiene un file SKILL.md. Non richiede processi né protocolli e costa circa 100 token finché l’agent non decide di leggerla. Usare un server MCP per dare a un agent accesso a un sistema. Usare una skill per indicare all’agent la procedura corretta per utilizzare tale accesso. Molte configurazioni usano entrambi.

Le skill degli agent funzionano solo con Claude Code?

No. Anthropic ha sviluppato il formato e lo ha poi rilasciato come standard aperto su agentskills.io. La stessa directory 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 resta invariato quando viene spostato tra questi client.

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 ne venga utilizzata una. Il primo aspetto a peggiorare è il matching, non la velocità. Molte skill con descrizioni sovrapposte rendono più difficile per il modello scegliere quella corretta. Scrivere descrizioni non sovrapposte e rimuovere le skill non più utilizzate.

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

Chiedersi se si applica a ogni attività del repository. I comandi di build, lo stile del progetto e le regole di denominazione si applicano a tutte le attività, quindi devono essere inseriti nel file sempre attivo, perché il suo caricamento a ogni esecuzione è proprio la sua funzione. Una procedura utilizzata occasionalmente, come una checklist di rilascio o un’esercitazione di ripristino, dovrebbe essere una skill, così non ha costi nelle attività che non ne richiedono l’utilizzo. Una sezione di AGENTS.md trasformata in una serie di passaggi numerati è in genere una skill che deve essere spostata.