Cosa sono davvero le competenze per agenti?

Che cos'è realmente una competenza per agenti

Una competenza per agenti è una directory sul disco che contiene un file denominato SKILL.md. Il 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 quella descrizione oppure quando si richiama la competenza per nome. Quasi tutto il resto delle competenze deriva da queste due regole.

La directory può contenere più di un 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 necessario e assets/ per modelli e dati. Nessuna di queste directory è obbligatoria. Una directory che contiene soltanto un file SKILL.md costituisce una competenza completa.

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

La descrizione è la parte che viene più spesso sottovalutata. È l'unico testo che l'agente vede prima di decidere se aprire la competenza, quindi deve indicare cosa fa la competenza e quando utilizzarla, 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. 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 name e description di ogni skill installata, e nient’altro. La specifica Agent Skills indica un valore di circa 100 token per skill (indicazione pubblicata a ottobre 2026). Installando una dozzina di skill, si utilizza all’incirca il contesto di un paragrafo lungo.

Quando una richiesta corrisponde a una descrizione, l’agente legge il corpo di quella sola 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 di esso. Uno script incluso funziona in modo ancora diverso: l’agente lo esegue tramite la shell, quindi il codice sorgente dello script non entra nella finestra di contesto; vi entra soltanto il suo output.

Confrontate questo approccio con quello a cui si ricorre per primo: un prompt enorme. Ogni riga di un prompt di sistema o di un file di istruzioni sempre attivo viene conteggiata per ogni richiesta e in ogni sessione, indipendentemente dal fatto che l’attività ne abbia bisogno, e compete per l’attenzione con la domanda effettiva. Diecimila token di istruzioni permanenti sono un costo da sostenere anche per chiedere l’ora. Una dozzina di skill utilizza circa 1.200 token quando non sono attive e si espande soltanto per l’attività che ne ha bisogno. Questo è il motivo principale per usare le skill e spiega perché una piccola libreria è più efficace 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. Un SKILL.md lungo rappresenta quindi un costo ricorrente, non un costo una tantum. Spostare i dettagli in references/ non è solo una questione di ordine. È il funzionamento previsto dal meccanismo.

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

Uno strumento, chiamato anche function call, è qualcosa 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, il programma che esegue il ciclo attorno 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 e poi agisce usando gli strumenti di cui dispone già. Il modello non può passare argomenti a una skill come li passa a uno strumento. Una skill può invece indicare al modello quali strumenti usare, in quale ordine e quali controlli eseguire in seguito. Affidare un’attività a un secondo agente è l’esempio più chiaro: una sessione di Claude Code può già inviare messaggi a un’altra sessione, mentre la skill è il punto in cui si specifica quando conviene farlo e quali dati inviare.

In breve: uno strumento fornisce a un agente una nuova capacità, mentre una skill gli fornisce soprattutto criteri per usare capacità che possiede già. Quando una skill aggiunge una capacità, lo fa tramite uno script incluso che l’agente esegue usando la shell di cui dispone già. Se un passaggio deve produrre ogni volta un risultato esatto e validato, serve uno strumento o uno script. Se un passaggio richiede di applicare sempre lo stesso ragionamento, serve una skill. Una skill può consistere soltanto in criteri operativi e restare comunque quella a cui si ricorre più spesso, come mostra Ponytail, che spinge un agente di programmazione ad apportare la modifica minima necessaria: non aggiunge alcuna nuova capacità e modifica soltanto il modo in cui l’agente usa quelle già disponibili. Questi criteri possono anche portare nella direzione opposta: la skill unlazy, che percorre un Depth Tree per impedire a un agente di dichiarare completata un’attività troppo presto applica lo stesso principio alla completezza invece che alla limitazione degli interventi.

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, comunica tramite quel protocollo ed espone strumenti all’agent. In genere richiede una configurazione, credenziali e un comando locale oppure un endpoint di rete. Una skill è una directory che contiene un file Markdown. Non ci sono processi, porte o protocolli.

Anche il costo in termini di contesto è diverso. Ogni strumento esposto da un server MCP include un nome, una descrizione e uno schema degli argomenti. In un client che li carica in anticipo, questi elementi restano nella richiesta per tutta la sessione, indipendentemente dal loro utilizzo. Claude Code non funziona più così per impostazione predefinita: da ottobre 2026 la ricerca degli strumenti è attiva automaticamente, quindi all’avvio della sessione vengono caricati solo i nomi degli strumenti e le istruzioni del server, mentre le definizioni complete arrivano quando Claude le cerca. Una skill inattiva occupa una sola riga di testo.

I due componenti si completano a vicenda 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 come deve essere un risultato corretto. Se gestisci un’infrastruttura autonoma, l’esecuzione di server MCP su un VPS descrive questo aspetto.

Una skill di un agente non è un prompt di sistema né un file AGENTS.md

Entrambi contengono istruzioni in formato Markdown, quindi la confusione è comprensibile. La differenza riguarda il momento in cui vengono caricati. 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 più vicino alla condizione di sempre attivi, perché selezionarne uno modifica direttamente il prompt di sistema, quindi influenzano ogni risposta della sessione, comprese quelle che nessuna skill coinvolge.

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

Anche questi file hanno convenzioni proprie che è importante applicare correttamente. Consulta cosa appartiene ad AGENTS.md e cosa appartiene al file per gli esseri umani e un file 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 di progetto si trovano in .claude/skills/<name>/SKILL.md e vengono salvate nel repository Git, quindi sono disponibili per tutte le persone e tutti gli agenti che lavorano in quel repository. GitHub Copilot e VS Code leggono le skill di progetto da .github/skills/ e .agents/skills/, oltre che da .claude/skills/. Il file contenuto è 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 ciò che è installato ed è il modo più rapido per verificare che il file sia stato acquisito. Se non compare nel menu, controlla prima i nomi: il file deve chiamarsi SKILL.md e la specifica Agent Skills richiede che il nome contenga solo lettere minuscole, cifre e singoli trattini, in modo coerente con la directory. La stessa procedura, descritta in modo che l'agente possa eseguirla nuovamente, è un complemento naturale ai 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. Questa è l'unica riga che l'agent può confrontare con la richiesta. "Assiste nelle 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 realmente, quindi la skill si attiva.

Il problema opposto riguarda la skill che si attiva continuamente. Una descrizione come "Usare per qualsiasi modifica al codice in questo repository" corrisponde a tutto, quindi il contenuto viene caricato per ogni attività e rimane nel contesto per il resto della sessione. Restringi la descrizione al caso previsto. In Claude Code puoi anche impostare disable-model-invocation: true nel frontmatter: in questo modo impedisci 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 essere 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 nuova sessione: una volta con la skill disponibile e una volta con la skill disattivata, quindi confronta le risposte. La nuova sessione è importante, perché quella in cui hai scritto la skill contiene già tutto ciò che la skill indica, nascondendo le lacune della versione scritta. Il plugin skill-creator di Anthropic automatizza questo confronto in Claude Code, inclusa la generazione di prompt che dovrebbero e non dovrebbero attivare la skill e la misurazione della frequenza di attivazione. Se la skill viene caricata e l'agent continua a non eseguire ciò che indica, il problema non è la descrizione: consulta i motivi per cui un agent ignora istruzioni che ha già letto.

È 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. A ottobre 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 per fasi. Include anche un validatore di riferimento, quindi skills-ref validate ./my-skill verifica una cartella rispetto alla specifica prima della condivisione.

Il vero indicatore è l'elenco dei client. La stessa cartella viene letta da Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands e opencode, tra gli altri. Microsoft pubblica le proprie skill in questo formato all'indirizzo github.com/microsoft/skills e distribuisce uno strumento desktop chiamato Skill Recorder, che osserva l'esecuzione di un'attività, la ricostruisce come intento più una sequenza ordinata di passaggi e scrive il risultato come skill. Il fatto che un fornitore sviluppi un recorder il cui formato di output appartiene alla specifica di un altro soggetto è un buon segnale: il formato non è più una funzionalità esclusiva 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 competenza 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 complete degli strumenti occupano contesto per l’intera sessione, a meno che il client ne rimandi il caricamento, come fa ora Claude Code per impostazione predefinita. Una competenza dell’agente è una directory che contiene un file SKILL.md. Non usa processi né protocolli e costa circa 100 token finché l’agente non decide di leggerla. Usate un server MCP per dare a un agente accesso a un sistema. Usate una competenza per indicare all’agente la procedura corretta per usare quell’accesso. Molte configurazioni usano entrambi.

Le competenze degli agenti funzionano solo con Claude Code?

No. Anthropic ha sviluppato il formato e lo ha poi pubblicato 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. Cambiano la posizione in cui ogni client cerca le competenze e i campi aggiuntivi di frontmatter che comprende. Claude Code legge ~/.claude/skills/ e .claude/skills/, mentre GitHub Copilot e VS Code leggono .github/skills/, .claude/skills/ o .agents/skills/ nel repository. Il file SKILL.md rimane invariato quando viene trasferito tra questi client.

Quante competenze posso installare prima che il sistema rallenti?

Il vincolo riguarda il budget di avvio, non il numero di competenze. Ogni competenza installata aggiunge il proprio nome e la propria descrizione, circa 100 token secondo le indicazioni pubblicate nella specifica. Trenta competenze costano quindi circa 3,000 token prima che una di esse venga utilizzata. Il primo aspetto a degradarsi è la selezione, non la velocità: molte competenze con descrizioni sovrapposte rendono più difficile per il modello scegliere quella corretta. Scrivete descrizioni non sovrapposte ed eliminate le competenze che non usate più.

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

Chiedetevi se si applica a ogni attività del repository. I comandi di build, lo stile adottato dal team e le regole di denominazione si applicano a tutte le attività. Devono quindi essere inseriti nel file sempre attivo, il cui caricamento a ogni esecuzione è intenzionale. Una procedura eseguita occasionalmente, come una checklist di release o un’esercitazione di ripristino, dovrebbe essere una competenza. In questo modo, nelle attività che non ne hanno bisogno, incide soltanto con la sua descrizione di una riga. Una sezione di AGENTS.md che si è trasformata in una serie di passaggi numerati è in genere una competenza che attende di essere spostata.