L’aggiornamento era una pista, non la prova

L’aggiornamento Radar del 17 agosto 2026 ha acceso la pista editoriale: un formato comune per distribuire estensioni agli agenti. Per scrivere la guida, però, non l’ho trattato come fonte tecnica. Ho verificato definizioni, struttura e limiti nella specifica Agent Plugins, negli schemi collegati e nella documentazione dei client.

Al 19 agosto la specifica dichiara versione 1.0.0 e stato Working Draft. Sono due informazioni diverse: 1.0.0 identifica il contratto e gli schemi pubblicati; Working Draft dice che il progetto non lo presenta ancora come testo definitivo. Chiamarlo “standard 1.0 concluso” sarebbe quindi più forte di ciò che afferma la fonte.

Il risultato utile non è un altro nome da aggiungere al glossario. È una separazione operativa: comportamento, capacità e distribuzione appartengono a livelli diversi e vanno revisionati con controlli diversi.

La distinzione che evita quasi tutta la confusione

Pensa a un piccolo workflow editoriale che deve leggere una board, fermarsi se la fonte corretta non è disponibile e produrre una scheda di review. La skill descrive quella procedura. Il server MCP rende disponibili le operazioni per interrogare la board. Il plugin raccoglie la skill e l’eventuale configurazione MCP in un’unità distribuibile.

Le tre parti possono esistere anche separatamente. Una skill può usare soltanto file e strumenti già presenti. Codex può collegarsi direttamente a un server MCP senza installare un plugin. Un plugin può contenere solo skill, solo configurazione MCP o entrambe. Per questo “ho installato l’MCP” e “ho scritto un plugin” non descrivono la stessa operazione.

Skill → comportamento
Istruzioni riutilizzabili, con eventuali script, riferimenti e asset. Definisce quando attivare un workflow, quali passaggi seguire, cosa verificare e quando fermarsi.
MCP → strumenti e dati
Protocollo con cui un client si collega a server che espongono tool, risorse e contesto. Il server gestisce capacità, schemi, autenticazione e autorizzazione del sistema esterno.
Plugin → pacchetto distribuibile
Directory identificata da un manifest che raggruppa componenti installabili. Nel nucleo portabile di Agent Plugins v1 i componenti standard sono skill e server MCP.

Un esempio concreto: leggere GitHub Projects senza fallback invisibili

Nel caso GitHub Projects, la skill può imporre di usare projects_list e projects_get, vietare di ricavare Status dal testo dell’issue e fermarsi quando gli strumenti mancano. Queste istruzioni migliorano il comportamento, ma non creano una connessione a GitHub.

Il server MCP remoto espone invece i tool e restituisce i dati correnti del Project secondo i permessi della credenziale. Un plugin potrebbe distribuire la skill insieme alla dichiarazione della dipendenza MCP, così un team installa un’esperienza riconoscibile invece di ricostruire a mano cartelle e configurazioni.

Resta una distinzione decisiva: il plugin può descrivere quali componenti appartengono al pacchetto, ma la task autorizza l’operazione concreta e il client applica approvazioni, sandbox e policy. Se vuoi soltanto provare il server in sola lettura, non serve trasformare subito la prova in un plugin pubblico.

Che cosa rende portabile Agent Plugins 1.0

La specifica sceglie un nucleo piccolo. Alla radice richiede plugin.json con lo schema Agent Plugins e un nome. Le skill vengono scoperte nelle sottocartelle immediate di skills/ quando contengono SKILL.md. I server MCP, se presenti, sono dichiarati in mcp.json con un trasporto esplicito.

Agent Plugins v1 standardizza esattamente due tipi di componente: Agent Skills e server MCP. Tutto ciò che appartiene a un client specifico vive in un namespace reverse-domain e può essere ignorato dagli altri client. Il manifest usa uno schema chiuso: i campi non standard non acquistano significato portabile soltanto perché sono stati aggiunti al JSON.

La specifica impone anche che i percorsi risolti rimangano dentro la radice del plugin. È un vincolo utile contro riferimenti che evadono dal pacchetto, non una valutazione del comportamento degli script o dei server inclusi.

  • plugin.json identifica il pacchetto e la versione della specifica.
  • skills/ contiene i workflow nel formato Agent Skills.
  • mcp.json dichiara server stdio, Streamable HTTP o legacy HTTP+SSE.
  • Le estensioni specifiche di un client restano fuori dal nucleo condiviso.
Struttura portabile minima con skill e MCP 
board-review/
├── plugin.json
├── skills/
│   └── board-review/
│       ├── SKILL.md
│       └── references/
│           └── states.md
└── mcp.json

plugin.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "board-review",
  "version": "1.0.0",
  "description": "Review board items using verified project fields"
}

Portabile non significa identico su ogni client

Il sito ufficiale parla di interoperability floor: una base comune, non un’interfaccia identica. Un client conforme può adottare i componenti in modo incrementale e supportare anche soltanto skill oppure MCP. Se un tipo non è supportato, viene ignorato; se un singolo server fallisce, gli altri componenti validi possono continuare a caricarsi.

L’elenco ufficiale dei client compatibili indica, al momento della verifica, supporto ChatGPT e Codex per Agent Skills e per MCP stdio e Streamable HTTP. La release Codex CLI 0.147.0 dichiara inoltre l’arrivo dei portable Agent Plugins. Questo prova il supporto documentato, non che ogni superficie, piano o policy esponga nello stesso modo cataloghi, installazione e approvazioni.

C’è poi un secondo formato da non confondere con il nucleo portabile. La documentazione OpenAI per pubblicare nel proprio ecosistema usa .codex-plugin/plugin.json e può collegare .mcp.json, .app.json, hook e asset. Sono superfici di distribuzione e compatibilità OpenAI. Il plugin.json alla radice e mcp.json senza punto appartengono invece alla specifica Agent Plugins 1.0. Copiare o rinominare i file alla cieca non rende automaticamente equivalenti i due pacchetti.

Il manifest non è un certificato di fiducia

Un plugin valido può contenere una skill con script eseguibili, un server MCP stdio avviato come processo locale o un collegamento remoto che riceve dati e credenziali. La validazione dello schema dice che il pacchetto ha una forma interpretabile. Non dimostra che il publisher sia chi dichiara di essere, che il codice sia innocuo o che l’endpoint remoto mantenga lo stesso comportamento nel tempo.

Il manifest portabile v1 non include un campo standard per firma o attestazione. La specifica vieta inoltre di usare env e header letterali come meccanismo per incorporare segreti; per i server remoti lascia discovery dell’autorizzazione, interazione con l’utente e storage delle credenziali al client. È una separazione sensata, ma significa che il controllo prima dell’installazione non può fermarsi a plugin.json.

Il confine di fiducia attraversa almeno quattro livelli: origine del pacchetto, file locali, processi o endpoint MCP e dati restituiti dai tool. Anche un server autentico può riportare commenti o issue non fidati. Il trasporto verificato non rende affidabile ogni campo del contenuto.

  • Una skill può influenzare il comportamento e può includere script da eseguire.
  • Un server stdio può avviare codice locale con l’ambiente concesso dal client.
  • Un server remoto può leggere dati o compiere azioni secondo credenziali e scope.
  • Le estensioni specifiche del client possono aggiungere capacità non coperte dal nucleo v1.
  • Un aggiornamento può cambiare file, dipendenze o comportamento anche se il nome resta uguale.

Checklist prima di installare un Agent Plugin

Fai il controllo sul pacchetto esatto che installerai, non soltanto sulla pagina di presentazione. Se la sorgente è Git, annota repository, revisione e versione. Se arriva da un catalogo, verifica quali informazioni di provenienza e aggiornamento il client mostra davvero.

Per una prima prova usa un workspace non critico, nessun segreto di produzione e capacità di sola lettura quando disponibili. Installa, osserva componenti caricati e tool esposti, poi confrontali con l’inventario atteso. Un tool inatteso o un endpoint non documentato è un motivo per fermarsi, non per proseguire “e vedere cosa succede”.

Controllo copiabile 
[ ] Origine, publisher dichiarato, repository e revisione annotati
[ ] Stato Working Draft e versione dello schema compresi
[ ] plugin.json letto; campi e namespace inattesi spiegati
[ ] Ogni SKILL.md letto, inclusi trigger e comportamento di arresto
[ ] scripts/, references/ e assets/ inventariati
[ ] mcp.json letto: type, command, args, cwd, env, URL e header
[ ] Nessun token o segreto incorporato nei file del pacchetto
[ ] Processi locali, rete, cartelle e dati accessibili ridotti al necessario
[ ] Scope e approvazioni delle scritture verificati nel client
[ ] Prima prova in ambiente non critico e, se possibile, read-only
[ ] Tool caricati e attività osservata confrontati con quanto dichiarato
[ ] Strategia per aggiornamento, disabilitazione e rimozione definita

Governance aperta, con un limite da dichiarare

Il Technical Charter descrive Agent Plugins come progetto comunitario e vendor-neutral. La governance è affidata a un Technical Steering Committee; i ruoli appartengono a persone, non ad aziende, e nessun vendor può controllare la maggioranza dei Core Maintainer. Il sito elenca nel comitato iniziale maintainer provenienti da Amazon, Cursor, Microsoft, OpenAI e Vercel.

Queste sono dichiarazioni e regole pubbliche del progetto, non una garanzia che ogni implementazione converga subito o che ogni plugin sia sicuro. Il valore della governance aperta è poter leggere specifica, schemi, discussioni e decisioni. La verifica resta necessaria sia per il formato sia per il singolo pacchetto.

Il limite più importante resta lo stato Working Draft. La versione 1.0.0 offre un bersaglio concreto per test e interoperabilità; chi distribuisce oggi dovrebbe fissare la versione dello schema, validare i client target e prepararsi a revisionare il pacchetto quando la specifica evolve.

Quando scegliere una skill, MCP o un plugin

Parti dal livello più piccolo che risolve il problema. Se ripeti istruzioni e criteri ma possiedi già tutti gli strumenti, crea una skill. Se servono dati vivi o azioni su un sistema esterno, valuta un server MCP con tool e autorizzazioni circoscritti. Se vuoi distribuire una capacità stabile a più persone o client, allora il pacchetto plugin diventa utile.

Aggiungere un plugin troppo presto rende più difficile capire quale parte non funziona. Prima prova il comportamento, poi la connessione, infine la distribuzione. È lo stesso ordine che rende diagnosticabile un workflow: skill verificabile, MCP osservabile, pacchetto installabile.

  1. Scrivi il risultato atteso e prova il workflow come istruzione circoscritta.
  2. Trasformalo in skill quando trigger, passaggi e verifiche sono stabili.
  3. Aggiungi MCP soltanto per dati o azioni che gli strumenti esistenti non coprono.
  4. Riduci tool, scope e scritture prima di collegare la skill al server.
  5. Crea il plugin quando esiste una reale esigenza di installazione e portabilità.
  6. Testa ogni client target e documenta ciò che resta specifico della piattaforma.

Fonti primarie e stato della verifica

Definizioni, struttura, stato Working Draft, regole di caricamento e limiti di portabilità provengono dalla specifica Agent Plugins 1.0.0 e dal suo Technical Charter. La distinzione tra skill e MCP è coerente anche con le specifiche Agent Skills e Model Context Protocol. Supporto e packaging OpenAI sono stati controllati nella documentazione Plugins e nella release ufficiale di Codex CLI.

La fotografia è aggiornata al 19 agosto 2026. Client compatibili, formati di distribuzione e stato della bozza possono cambiare: prima di pubblicare o installare, ricontrolla la versione dello schema e la documentazione del client che userai.

CONTINUA A LEGGERE

Altre guide collegate

01 Il mio agente diceva di leggere la board. In realtà leggeva un’issue Leggi → 02 Codex Security: come scansionare un repository senza fidarsi alla cieca Leggi → 03 OpenAI Academy: 3 corsi gratuiti per imparare l’AI, anche se non sei tecnico Leggi →
PROSSIMO PASSO

Prova su un caso reale, ma piccolo

Parti da una email, un riassunto o un confronto semplice. Controlla sempre dati personali, date, numeri e decisioni importanti.

Torna a AI pratica