La descrizione di uno strumento MCP è una frase attaccata a una singola funzione
richiamabile: che cosa fa, che cosa prende, se modifica qualcosa. Viaggia con
ogni richiesta che il client invia al modello, insieme alla descrizione di ogni
altro strumento. Una skill è una cartella con dentro un file SKILL.md, che
contiene una procedura — fare questo, poi verificare quello, chiedere conferma
prima di quest'altra cosa — e il suo corpo viene caricato solo quando il modello
decide che la richiesta corrisponde.
È tutta qui la distinzione, ed è una distinzione su quando il testo è in contesto, non su che cosa dice il testo. Le descrizioni sono il prezzo del biglietto: si pagano tutte, a ogni turno, per sempre. Le istruzioni di una skill sono gratuite finché non diventano rilevanti. Ecco perché un paragrafo indifendibile nella descrizione di uno strumento — trecento parole su come smaltire un arretrato di registrazioni di riunioni — è perfettamente ragionevole in una skill.
Questo articolo parla di come decidere dove va ciascuna istruzione. Se il protocollo in sé è una novità, che cos'è un server MCP copre prima il vocabolario, e MCP, plugin e integrazioni copre dove si colloca MCP rispetto ai modi più vecchi di collegare le cose.
Nella specifica MCP la definizione di uno strumento ha una forma piccola e
fissa. Porta con sé un name, un title facoltativo leggibile dalle persone,
una description, un inputSchema che descrive gli argomenti, un
outputSchema facoltativo e le annotations — proprietà facoltative che
descrivono il comportamento dello strumento, per esempio se si limita a
leggere. Il client recupera l'intero elenco con una chiamata tools/list e lo
mette davanti al modello: è questo che rende gli strumenti MCP controllati dal
modello, che ne sceglie uno in base alla conversazione.
Questa forma è brava esattamente in una cosa: dire a un modello che cosa fa una singola chiamata, perché scelga quella giusta. È strutturalmente inadatta ad altre tre.
Non può descrivere l'ordine. Niente in una definizione di strumento può dire
«chiama list_channels prima di share_to_channel, perché il canale deve
esistere e deve essere l'utente a sceglierlo». Ogni descrizione è un'isola.
Non può contenere molto. Ogni descrizione è in contesto per ogni richiesta di ogni conversazione, comprese tutte quelle che non toccheranno mai quello strumento. Un server con quindici strumenti e un paragrafo per ciascuno ha già speso una parte significativa della finestra di contesto prima che l'utente abbia scritto qualcosa.
Non può codificare il giudizio di chi lo usa. «Quando non è chiaro chi debba vederla, etichetta la registrazione invece di condividerla» è una politica, non la descrizione di una funzione. Due team diversi vorrebbero due politiche diverse dallo stesso strumento.
C'è una valvola di sfogo nel protocollo: alla connessione il server può
restituire una stringa instructions, che il client può aggiungere al prompt di
sistema, prima dell'elenco degli strumenti. È il posto giusto per un breve
orientamento: che cos'è questo server, a che cosa è collegato, a che cosa fare
attenzione. Due avvertenze. Resta comunque testo per sessione, quindi va tenuto
breve. E la specifica dice che i client possono usarla, non che devono, quindi
il supporto per mostrarla davvero al modello varia da client a client.
Una skill è una directory che contiene un file SKILL.md: frontmatter YAML con
un name e una description, poi istruzioni in markdown. Accanto può
raccogliere altro — scripts/ per il codice eseguibile, references/ per la
documentazione dettagliata, assets/ per i modelli — e l'agente li tira dentro
solo quando le istruzioni lo mandano lì.
Il modello di caricamento si chiama progressive disclosure, divulgazione progressiva, e la specifica lo articola in tre fasi:
name e la description di
ogni skill disponibile — con un budget di circa 100 token per skill.
Abbastanza per sapere quando potrebbe servire, e nulla di più.SKILL.md. La raccomandazione è restare
sotto i 5.000 token circa, e il file principale sotto le 500 righe.Così il costo di avere venti skill installate è venti descrizioni brevi. Il costo di avere venti descrizioni di strumento lunghe è venti descrizioni lunghe, a ogni turno. È questa asimmetria la ragione per cui lo strato esiste.
Il formato non è legato a un singolo client. Agent Skills è stato sviluppato da
Anthropic e rilasciato come standard aperto, pubblicato su agentskills.io; la
vetrina dei client elenca decine di prodotti che leggono la stessa cartella, tra
cui Claude Code, Claude, ChatGPT e Codex, Cursor, VS Code, GitHub Copilot,
Gemini CLI, Goose, Roo Code, Kiro, Junie, Amp, Factory, Tabnine, Snowflake
Cortex Code e Databricks Genie Code. Verificato il 14 agosto 2026.
Il frontmatter obbligatorio è volutamente scarno. name arriva a 64 caratteri,
lettere minuscole, cifre e trattini, e deve coincidere con il nome della
directory che lo contiene. description arriva a 1.024 caratteri e dovrebbe
dire sia che cosa fa la skill sia quando usarla — perché quella stringa è
l'unica base su cui un agente decide se aprire il file. I campi facoltativi sono
license, compatibility, metadata e lo sperimentale allowed-tools.
Quel campo description merita più cura di quanta gliene venga data. «Aiuta con
gli appunti delle riunioni» non corrisponderà mai a niente in modo affidabile;
«rivede e archivia le registrazioni recenti — le etichetta, dà un nome a chi
parla, condivide quelle che appartengono a un canale del team; da usare quando
l'utente chiede di mettere in ordine, smaltire l'arretrato o recuperare il
non letto» sì.
Tra le descrizioni per chiamata e le skill a richiesta sta uno strato che non è né l'una né l'altra cosa: file che l'agente legge all'inizio di una sessione a prescindere da che cosa gli è stato chiesto.
AGENTS.md è la versione più semplice — markdown standard, nessun campo obbligatorio, letto dal file più vicino risalendo l'albero delle directory. Il suo sito dichiara l'uso da parte di oltre 60.000 progetti open source ed elenca il supporto in OpenAI Codex, Google Jules e Gemini CLI, negli agenti Claude, nell'agente di programmazione di GitHub Copilot, in Aider, VS Code, Cursor, Zed, Warp, Factory, goose, Roo Code, Devin e Junie. Verificato il 14 agosto 2026.
Le regole di Cursor sono la stessa idea con un interruttore sopra. Vivono in
.cursor/rules come file .mdc, e tre campi del frontmatter decidono quando
ciascuna viene inclusa: alwaysApply: true la mette in ogni sessione di chat;
una description lascia all'agente il giudizio sulla rilevanza; i globs la
agganciano quando è aperto un file corrispondente; e senza nessuno di questi, la
regola arriva solo quando la si richiama con @. Cursor supporta anche
AGENTS.md e ora supporta direttamente Agent Skills — le skill stanno in
.cursor/skills/ o .agents/skills/ — con uno strumento di migrazione che
converte in skill le regole dinamiche e i comandi slash idonei. Verificato il
14 agosto 2026.
A rileggere quei due paragrafi lo schema è chiaro: i formati sono convergenti,
i modelli di caricamento no. Ormai SKILL.md lo legge chiunque. Ma una regola
alwaysApply e un blocco di AGENTS.md hanno l'ambito della sessione, una
skill ha l'ambito del compito, e nessuna compatibilità di formato cambia questo.
La conseguenza pratica è una regola empirica che vale più dei dettagli di formato:
| Dove va | Che cosa ci sta | Che cosa costa |
|---|---|---|
description dello strumento |
Una frase: che cosa fa questa chiamata, che cosa modifica | Ogni richiesta, per sempre |
instructions del server |
Un breve orientamento sull'intero server | Ogni sessione su questo server |
AGENTS.md, regole sempre attive |
Fatti veri per ogni compito in questo repository | Ogni sessione di questo progetto |
SKILL.md |
Procedure, politiche, esempi svolti, giudizio | Solo quando il compito corrisponde |
Tutto ciò che è lungo, tutto ciò che è condizionale, tutto ciò che è vero solo a
volte: skill. L'errore in cui si cade è mettere centocinquanta righe di
procedura specifica di un prodotto in un AGENTS.md globale, dove restano in
contesto mentre si lavora tutto il pomeriggio su un backend che non c'entra
nulla.
Speak-Y distribuisce un server MCP, ed è un esempio discreto perché i due strati fanno visibilmente lavori diversi.
Le descrizioni degli strumenti coprono le chiamate: cercare fra le
registrazioni, leggere una trascrizione, un riassunto o le azioni da fare,
elencare canali ed etichette — e, con l'app in esecuzione, etichettare una
registrazione, rinominare chi parla, cambiarle titolo, ritrascriverla o
archiviarla in un canale del team. Ciascuna porta un'annotazione che dice se
legge o se modifica: è questo che permette a un client di chiedere conferma
prima di eseguire quelle che modificano, ed è questo che rende --read-only un
singolo interruttore invece di un elenco di nomi di strumenti da ricordare. La
lettura avviene in locale sulla libreria presente sulla propria macchina; i
comandi che modificano passano dall'app in esecuzione e lì vengono registrati,
come racconta più in dettaglio
che cosa rende sicuro l'accesso in scrittura via MCP.
La skill copre il lavoro. Installando l'integrazione da
Impostazioni → Integrazioni, Speak-Y scrive una skill di organizzazione
accanto alla configurazione del server: da dove partire quando si smaltisce una
pila di registrazioni, quando la risposta giusta è un'etichetta e quando è un
canale, quali azioni far confermare prima di eseguirle. Le descrizioni non
potrebbero contenere tutto questo, e la stringa instructions del server non
dovrebbe provarci.
È anche scritta nel modo che il modello di caricamento premia. Un unico file
dettagliato sta in un unico posto, e ogni client riceve un breve rimando nel
formato che quel client legge — un SKILL.md per Claude Code, una regola .mdc
per Cursor, un blocco delimitato dentro AGENTS.md per Codex, un blocco
delimitato in GEMINI.md per Gemini CLI. I client con ambito di sessione
ricevono un rimando proprio perché hanno l'ambito della sessione:
centocinquanta righe sugli appunti delle riunioni non devono restare in memoria
mentre si fa il debug del backend di qualcun altro. I blocchi stanno fra
marcatori, così una reinstallazione sostituisce solo quella sezione e lascia
intatto il resto del file.
Il server MCP in sé è gratuito su ogni piano, incluso Free. L'installazione in un clic e la configurazione manuale per ciascun client sono documentate in Assistenti IA (MCP).
Tre domande, in quest'ordine.
L'istruzione descrive una sola chiamata? Allora è la descrizione di uno strumento, e deve stare in una o due frasi. Se ci si accorge di scriverne una terza, si è trovata una skill.
È vera per ogni sessione, indipendentemente dal compito? Allora può stare in
AGENTS.md o in una regola sempre attiva — ma la parte «indipendentemente dal
compito» va verificata onestamente. «Questo repository usa pnpm» rientra. «Ecco
il nostro processo di smistamento delle riunioni» no.
Descrive una procedura con passaggi, scelte o eccezioni? Skill. Il nome e la
descrizione vanno esaminati con severità, perché sono quelle due stringhe a fare
tutto l'instradamento, e tutto ciò che è lungo va messo in un file dentro
references/ accanto al SKILL.md invece che al suo interno.
Sbagliare nella direzione economica significa un agente con il contesto gonfio e una precisione peggiore su ogni domanda che non c'entra. Sbagliare nella direzione costosa — procedura stipata nelle descrizioni degli strumenti — significa che il modello legge la politica a ogni turno e potrebbe comunque non seguirla, perché una descrizione viene letta come documentazione di una funzione, non come un'istruzione da rispettare.
Per vedere la differenza in concreto, la prova più rapida è scrivere una skill per un lavoro che si ripete davvero e confrontarla con i prompt che si incollavano prima. I prompt da fare all'assistente AI sulle proprie riunioni sono una fonte ragionevole di candidati: quelli che si eseguono più di due volte sono quelli che meritano un file.
La descrizione di uno strumento è una frase attaccata a una singola funzione richiamabile, scritta da chi realizza il server e inviata al modello con ogni richiesta come parte dell'elenco degli strumenti. Una skill è una cartella con un file SKILL.md che contiene una procedura — più passaggi, più strumenti, valutazioni da fare — e finché il modello non decide che il compito corrisponde, in contesto ci sono solo il suo nome e la sua descrizione. Le descrizioni rispondono a «che cosa fa questa chiamata»; le skill rispondono a «come si porta a termine questo lavoro».
Non per i compiti che si esauriscono in una chiamata. Serve quando un lavoro richiede più strumenti in un ordine preciso, quando la scelta giusta fra due strumenti dipende da un contesto che le descrizioni non possono trasportare, oppure quando si vuole che la stessa procedura si ripeta identica in ogni sessione. Buone descrizioni rendono corretta ciascuna chiamata; una skill rende coerente una sequenza di chiamate.
No. Agent Skills è stato sviluppato da Anthropic e rilasciato come standard aperto, pubblicato su agentskills.io, e la vetrina dei client elenca decine di prodotti che lo adottano — tra cui Claude Code, ChatGPT e Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Goose, Roo Code, Kiro, Junie e Factory. Verificato il 14 agosto 2026.
AGENTS.md è semplice markdown senza campi obbligatori, che l'agente legge dalla directory più vicina risalendo l'albero, e viene caricato per l'intera sessione a prescindere da che cosa è stato chiesto. Il corpo di una skill viene caricato solo dopo che l'agente ha fatto corrispondere la richiesta alla sua descrizione. Entrambi sono utili, ma tutto ciò che è lungo appartiene a una skill, perché il contenuto di AGENTS.md occupa contesto in ogni sessione, comprese quelle che non c'entrano nulla.
La specifica di Agent Skills raccomanda di tenere il file SKILL.md principale sotto le 500 righe e sotto i 5.000 token circa, spostando il materiale di riferimento dettagliato in file separati che l'agente carica solo quando gli servono. Per nome e descrizione il budget è di circa 100 token, perché sono quelli che ogni sessione paga.