Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Impacchetta il plugin

Lezione 10 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Perché impacchettare
  2. Struttura di un pacchetto portatile
  3. Dichiarazione del server MCP
  4. Metadati specifici di OpenAI
  5. La via rapida: @plugin-creator
  6. Marketplace locali
  7. Hook: solo desktop
  8. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base della pagina Package your plugin della documentazione dei Plugin OpenAI. La lezione precedente descriveva la creazione di un “pacchetto” per un inesistente “ChatGPT Store” utilizzando un manifest mancante. Un plugin viene impacchettato con un manifest plugin.json che segue lo schema Agent Plugins. Fonte: Package your plugin.

Perché impacchettare

Una volta scritte le tue skill e, se necessario, costruito il server MCP, il passo finale consiste nell’assemblarle in un’unità installabile. L’impacchettamento conferisce al tuo plugin un’identità stabile e indica a ChatGPT e Codex quali skill, connessioni al server MCP e risorse appartengono allo stesso insieme. La logica dell’interfaccia utente e dell’autenticazione rimane all’interno del server MCP; il manifest si limita a collegare tale integrazione al resto del bundle.

Struttura di un pacchetto portatile

Un plugin portatile ha un manifest plugin.json alla sua radice, che dichiara lo schema Agent Plugins. La cartella può contenere anche una directory skills/, un file mcp.json per i server MCP distribuiti con il plugin e risorse visive in assets/.

mon-plugin/
├── plugin.json
├── mcp.json
├── skills/
│   └── compte-rendu/
│       └── SKILL.md
└── assets/
    ├── icon.png
    └── logo.png

Il manifest minimo occupa solo poche righe. Il nome, stabile e in kebab-case, funge sia da identificatore che da namespace per i componenti; le skill vengono scoperte automaticamente in skills/ senza bisogno di una dichiarazione esplicita.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "notes-equipe",
  "version": "0.1.0",
  "description": "Team notes and meeting minutes"
}

Ogni skill risiede in skills/<name>/SKILL.md, con un’intestazione che ne fornisce nome e descrizione, seguita dalle istruzioni:

---
name: compte-rendu
description: Drafts meeting minutes from team notes.
---

Retrieve meeting notes using list_notes, group them by topic,
then draft a summary: decisions, action items with owners, and open points.

Dichiarazione del server MCP

I server MCP distribuiti con il plugin vengono dichiarati in mcp.json alla radice, utilizzando lo schema corrispondente e specificando un tipo di trasporto per ogni server:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "notes": {
      "type": "streamable-http",
      "url": "https://notes.example.com/mcp"
    }
  }
}

L’autenticazione del server viene dichiarata in questo stesso file, sotto extensions["com.openai"].auth per ogni server: appartiene al server, non al manifest. Per l’invio pubblico, invii l’endpoint HTTPS remoto; i server locali seguono un percorso separato riservato ai plugin desktop.

Metadati specifici di OpenAI

La presentazione della directory, le mappature verso server MCP già registrati e gli hook vengono dichiarati nell’oggetto extensions.com.openai del file plugin.json radice, mentre l’identità portatile (name, version, description) rimane alla radice:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "notes-equipe",
  "version": "0.1.0",
  "description": "Team notes and meeting minutes",
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "Team Notes",
        "shortDescription": "Notes and meeting minutes",
        "developerName": "Your Team",
        "category": "Productivity",
        "capabilities": ["Read", "Write"],
        "websiteURL": "https://example.com",
        "privacyPolicyURL": "https://example.com/privacy",
        "termsOfServiceURL": "https://example.com/terms",
        "defaultPrompt": ["Use Team Notes to draft Monday's meeting minutes."],
        "composerIcon": "./assets/icon.png",
        "logo": "./assets/logo.png"
      }
    }
  }
}

I percorsi in questo oggetto sono relativi alla radice del plugin e iniziano con ./. Le risorse visive (composerIcon, logo, screenshots) dovrebbero preferibilmente andare in ./assets/. Il campo apps viene utilizzato solo per puntare a un file .app.json contenente le mappature verso server MCP già registrati in ChatGPT.

Puoi anche dichiarare una skill di onboarding tramite extensions.com.openai.onboardingSkill (ad esempio, ./skills/setup/SKILL.md): essa guida l’utente dopo l’installazione nella scelta di un workspace o nell’impostazione delle preferenze. Testala in una nuova conversazione e durante un’installazione in corso.

Un formato più vecchio, con un manifest in .codex-plugin/plugin.json, è ancora accettato per compatibilità: viene utilizzato solo se l’oggetto extensions.com.openai è assente, poiché i due non vengono uniti. I nuovi pacchetti dovrebbero usare il plugin.json radice.

La via rapida: @plugin-creator

ChatGPT e Codex includono una skill, @plugin-creator, che genera la struttura per te, attualmente nel formato di compatibilità .codex-plugin/. Per collegarvi un server MCP, connetti prima quel server in ChatGPT (Add custom MCP server, quindi Create as a plugin), prendi nota dell’ID di connessione tecnico dall’URL del browser (inizia con plugin_asdk_app) e forniscilo a @plugin-creator in modalità Work (o a $plugin-creator in Codex). La skill può anche creare una voce nel marketplace personale, permettendoti di installare e testare il plugin dalla tua directory locale di origine.

Marketplace locali

Un marketplace è un catalogo JSON di plugin. Serve per scrivere, testare e distribuire in team parallelamente alla directory pubblica: in modalità Work o in Codex, ogni marketplace appare come una sorgente selezionabile nella directory dei plugin. È così che testerai il plugin completo prima di inviarlo (Lezione 9).

Hook: solo desktop

Gli hook del ciclo di vita sono supportati solo per i plugin installati manualmente nell’app desktop Codex; un plugin che li contiene non è idoneo per la directory pubblica. Se il tuo plugin è destinato alla pubblicazione, omettili.

Punti chiave

  • Un pacchetto portatile: plugin.json (schema Agent Plugins), skills/, mcp.json, assets/
  • Il server MCP viene dichiarato in mcp.json con il suo tipo di trasporto; anche l’autenticazione va lì
  • Presentazione, mappature e la skill di onboarding vanno in extensions.com.openai
  • @plugin-creator genera la struttura; un marketplace locale serve per i test
  • Un plugin con hook non è idoneo per la directory pubblica