NuGet può distribuire le istruzioni agli agenti. Ma chi verifica ciò che leggono?

Un agente che lavora su una libreria appena aggiornata ha un problema molto concreto: il codice cambia più velocemente della conoscenza incorporata nel modello. Può cercare documentazione, leggere i sorgenti, ispezionare assembly e ricostruire il comportamento delle API. Oppure può ricevere istruzioni operative insieme alla versione della dipendenza che sta usando. Microsoft sta sperimentando questa seconda strada nei pacchetti NuGet, distribuendo file SKILL.md accanto alle librerie .NET.

La parte interessante non è che un pacchetto possa contenere Markdown. È sempre stato possibile. La novità è trattare quel Markdown come materiale che un agente può utilizzare per decidere come lavorare. E questo sposta il problema dalla sola documentazione alla gestione delle istruzioni, della loro provenienza e della loro qualità.

Una dipendenza aggiornata, un modello fermo a ieri

Nel resoconto pubblicato dal team .NET il 3 novembre 2026, Richard Lander descrive un esperimento: includere skill in pacchetti NuGet e renderle individuabili con strumenti dedicati. L’esempio è Markout, che distribuisce più file SKILL.md per spiegare forme di output, composizione e casi d’uso della libreria. Ogni versione può accompagnare le proprie API con istruzioni coerenti con quella versione.

È una differenza importante rispetto alla domanda generica posta a un modello: “Come si usa questa libreria?”. Una risposta può mescolare versioni diverse o suggerire metodi inesistenti. Una skill residente nel pacchetto può invece descrivere convenzioni e limiti relativi alla release effettivamente installata. Non garantisce che l’agente risponda correttamente, ma riduce una fonte prevedibile di ambiguità.

Il restore scarica i file, non insegna automaticamente all’agente

Qui serve precisione. dotnet restore porta il pacchetto nella cache NuGet e con esso anche gli eventuali file skill. Non significa che qualsiasi agente li scopra, li carichi e li segua automaticamente. La disponibilità sul filesystem e l’integrazione nel contesto operativo sono due passaggi distinti.

Microsoft mostra dotnet-inspect per elencare e leggere le skill contenute in un pacchetto o nelle dipendenze di un progetto. Presenta inoltre dotnet-package-skills, che copia le skill delle dipendenze dirette nella directory .agents/skills del repository. La pagina NuGet dello strumento documenta anche il comportamento durante gli aggiornamenti: le skill possono essere riallineate alle versioni risolte dal progetto.

Questa distinzione evita una conclusione troppo comoda: distribuire le istruzioni non equivale a costruire un sistema affidabile per consumarle. Bisogna decidere quali file esporre, quando aggiornarli, come gestire collisioni di nomi e come verificare che l’agente stia usando proprio la documentazione prevista.

Una skill non è un’autorità

Il formato Agent Skills prevede un file SKILL.md con metadati YAML e istruzioni Markdown, eventualmente affiancato da script, riferimenti e risorse. È un contenitore flessibile. Proprio per questo il suo contenuto va trattato come materiale esterno da valutare, non come un ordine con priorità superiore alle regole del progetto.

Una dipendenza software può già introdurre rischi attraverso il codice. Se aggiungiamo istruzioni che un agente interpreta durante lo sviluppo, introduciamo un ulteriore confine di fiducia. Una skill può essere sbagliata, obsoleta, troppo permissiva o malevola. Può chiedere di ignorare test, eseguire comandi non necessari o inviare informazioni a un servizio esterno. Il fatto che arrivi da un registry non trasforma automaticamente quelle istruzioni in una policy approvata.

La conseguenza operativa è semplice: mantenere versioni risolte e verificabili, controllare le modifiche alle skill come si controllano quelle alle dipendenze e limitare i permessi degli strumenti che l’agente può invocare. Le istruzioni di un pacchetto devono aiutare a usare la libreria, non decidere da sole quali accessi o privilegi concedere.

Anche il costo delle istruzioni è un requisito

Il team .NET insiste su un punto che spesso sparisce nelle dimostrazioni degli agenti: una skill va misurata. Le istruzioni possono aumentare la correttezza, ma possono anche consumare token senza produrre un vantaggio proporzionato. Nel resoconto Microsoft distingue efficacia ed efficienza e racconta di aver osservato risultati differenti a seconda della capacità del modello.

Per un progetto reale non basta verificare che una skill venga caricata. Bisogna confrontare lo stesso compito con e senza skill, osservare errori, tempo di esecuzione, chiamate agli strumenti e costo complessivo. Se un file di istruzioni rende più costoso il lavoro senza migliorarlo, il problema non si risolve aggiungendo altro testo: si corregge o si elimina quella skill.

La documentazione diventa parte della release

L’idea più solida dell’esperimento è legare la conoscenza operativa alla versione della libreria. Per chi mantiene un SDK significa poter spiegare agli agenti non soltanto quali API esistono, ma quali errori evitare e quali percorsi sono supportati. Per chi sviluppa significa avere un riferimento vicino al codice effettivamente installato.

Ma la qualità non nasce dal packaging. Nasce dalla manutenzione, dalla revisione e dalla verifica sul lavoro concreto. NuGet può consegnare una skill insieme a una DLL; non può garantire che l’agente la interpreti correttamente o che sia sicuro obbedirle. Il passo avanti, quindi, non è avere più prompt distribuiti. È poter trattare le istruzioni per gli agenti come un artefatto versionato, testabile e soggetto agli stessi controlli seri che chiediamo al software.