Balenie zásuvného modulu
Na tejto strane
Lekcia prepísaná 3. novembra 2026 na základe stránky Package your plugin v dokumentácii OpenAI Plugins. Predchádzajúca lekcia opisovala vytváranie „balíka“ pre neexistujúci „ChatGPT Store“ s použitím chýbajúceho manifestu. Zásuvný modul sa balí s manifestom
plugin.jsonpodľa schémy Agent Plugins. Zdroj: Package your plugin.
Prečo baliť
Keď už máš napísané svoje zručnosti a v prípade potreby zostavený server MCP, posledným krokom je ich spojenie do inštalovateľnej jednotky. Balenie dáva tvojmu zásuvnému modulu stabilnú identitu a hovorí ChatGPT a Codexu, ktoré zručnosti, pripojenia serverov MCP a zdroje patria k sebe. Logika používateľského rozhrania a overovania zostáva vo vnútri servera MCP; manifest jednoducho prepája túto integráciu so zvyškom balíka.
Štruktúra prenosného balíka
Prenosný zásuvný modul má vo svojom koreňovom adresári manifest plugin.json, ktorý deklaruje schému Agent Plugins. Priečinok môže tiež obsahovať adresár skills/, súbor mcp.json pre servery MCP distribuované so zásuvným modulom a vizuálne zdroje v assets/.
mon-plugin/
├── plugin.json
├── mcp.json
├── skills/
│ └── compte-rendu/
│ └── SKILL.md
└── assets/
├── icon.png
└── logo.png
Minimálny manifest sa zmestí len do niekoľkých riadkov. Názov, ktorý je stabilný a formátovaný v kebab-case, slúži ako identifikátor aj ako menný priestor pre komponenty; zručnosti sa automaticky objavujú v skills/ bez potreby explicitného deklarovania.
{
"$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"
}
Každá zručnosť žije v skills/<názov>/SKILL.md, pričom hlavička poskytuje jej názov a popis, po ktorých nasledujú inštrukcie:
---
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.
Deklarácia servera MCP
Servery MCP distribuované so zásuvným modulom sa deklarujú v súbore mcp.json v koreňovom adresári pomocou zodpovedajúcej schémy a špecifikáciou typu transportu pre každý server:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"notes": {
"type": "streamable-http",
"url": "https://notes.example.com/mcp"
}
}
}
Overovanie servera sa deklaruje v tomto istom súbore pod extensions["com.openai"].auth pre každý server – patrí k serveru, nie k manifestu. Pri verejnom odovzdaní odovzdáš vzdialený koncový bod HTTPS; lokálne servery nasledujú samostatnú cestu vyhradenú pre desktopové zásuvné moduly.
Metadáta špecifické pre OpenAI
Prezentácia adresára, mapovania na už registrované servery MCP a háky (hooks) sa deklarujú v objekte extensions.com.openai koreňového súboru plugin.json, zatiaľ čo prenosná identita (name, version, description) zostáva v koreni:
{
"$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"
}
}
}
}
Cesty v tomto objekte sú relatívne ku koreňu zásuvného modulu a začínajú na ./. Vizuálne zdroje (composerIcon, logo, screenshots) by mali prednostne ísť do ./assets/. Pole apps sa používa len na odkazovanie na súbor .app.json obsahujúci mapovania na servery MCP už registrované v ChatGPT.
Môžeš tiež deklarovať uvádzaciu zručnosť (onboarding skill) prostredníctvom extensions.com.openai.onboardingSkill (napríklad ./skills/setup/SKILL.md): tá vedie používateľa po inštalácii k výberu pracovného priestoru alebo nastaveniu preferencií. Otestuj ju v novej konverzácii a počas prebiehajúcej inštalácie.
Starší formát s manifestom v .codex-plugin/plugin.json je stále akceptovaný pre kompatibilitu: používa sa len vtedy, ak chýba objekt extensions.com.openai, keďže sa tieto dva nespaľujú. Nové balíky by mali používať koreňový plugin.json.
Rýchla cesta: @plugin-creator
ChatGPT a Codex obsahujú zručnosť @plugin-creator, ktorá za teba vygeneruje štruktúru – momentálne vo formáte kompatibilnom .codex-plugin/. Ak k nej chceš pripojiť server MCP, najprv tento server pripoj v ChatGPT (Add custom MCP server, potom Create as a plugin), zaznamenaj si technické ID pripojenia z URL adresy prehliadača – začína sa na plugin_asdk_app – a poskytni ho nástroju @plugin-creator v režime Work (alebo $plugin-creator v Codexe). Táto zručnosť môže tiež vytvoriť záznam v osobnom trhovisku, čo ti umožní nainštalovať a otestovať zásuvný modul zo zdrojového lokálneho adresára.
Lokálne trhoviská
Trhovisko je katalóg zásuvných modulov vo formáte JSON. Slúži na písanie, testovanie a distribúciu v rámci tímu popri verejnom adresári: v režime Work alebo v Codexe sa každé trhovisko zobrazuje ako voliteľný zdroj v adresári zásuvných modulov. Takto otestuješ kompletný zásuvný modul pred jeho odovzdaním (Lekcia 9).
Háky (Hooks): len pre desktop
Životné cykly hákov (lifecycle hooks) sú podporované len pre zásuvné moduly manuálne nainštalované v desktopovej aplikácii Codex a zásuvný modul, ktorý ich obsahuje, nie je oprávnený na zaradenie do verejného adresára. Ak cieliš na publikáciu, vynechaj ich.
Kľúčové poznatky
- Prenosný balík:
plugin.json(schéma Agent Plugins),skills/,mcp.json,assets/ - Server MCP sa deklaruje v
mcp.jsons jeho typom transportu; tam patrí aj overovanie - Prezentácia, mapovania a uvádzacia zručnosť idú do
extensions.com.openai @plugin-creatorgeneruje štruktúru; lokálne trhovisko slúži na testovanie- Zásuvný modul s hákmi nie je oprávnený pre verejný adresár