Pakietowanie wtyczki
Na tej stronie
Lekcja przepisana 3 listopada 2026 na podstawie strony Package your plugin z dokumentacji wtyczek OpenAI. Poprzednia lekcja opisywała budowanie „pakietu“ dla nieistniejącego „Sklepu ChatGPT“ przy użyciu brakującego manifestu. Wtyczka jest pakowana z manifestem
plugin.jsonzgodnym ze schematem Agent Plugins. Źródło: Package your plugin.
Dlaczego pakować
Gdy już napiszesz swoje umiejętności i w razie potrzeby zbudujesz serwer MCP, ostatnim krokiem jest złożenie ich w jednostkę instalacyjną. Pakietowanie nadaje Twojej wtyczce stabilną tożsamość i informuje ChatGPT oraz Codex, które umiejętności, połączenia z serwerami MCP i zasoby należą do siebie. Logika interfejsu użytkownika i uwierzytelniania pozostaje wewnątrz serwera MCP; manifest jedynie łączy tę integrację z resztą pakietu.
Struktura przenośnego pakietu
Przenośna wtyczka posiada manifest plugin.json w swoim katalogu głównym, deklarujący schemat Agent Plugins. Folder może również zawierać katalog skills/, plik mcp.json dla serwerów MCP dystrybuowanych razem z wtyczką oraz zasoby graficzne w katalogu assets/.
mon-plugin/
├── plugin.json
├── mcp.json
├── skills/
│ └── compte-rendu/
│ └── SKILL.md
└── assets/
├── icon.png
└── logo.png
Minimalny manifest mieści się w zaledwie kilku liniach. Nazwa, stabilna i zapisana w formacie kebab-case, służy zarówno jako identyfikator, jak i przestrzeń nazw dla komponentów; umiejętności są wykrywane automatycznie w katalogu skills/ bez konieczności ich jawnego deklarowania.
{
"$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żda umiejętność znajduje się w skills/<nazwa>/SKILL.md, z nagłówkiem zawierającym jej nazwę i opis, po którym następują instrukcje:
---
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.
Deklarowanie serwera MCP
Serwery MCP dystrybuowane razem z wtyczką są deklarowane w pliku mcp.json w katalogu głównym, przy użyciu odpowiedniego schematu i określeniu typu transportu dla każdego serwera:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"notes": {
"type": "streamable-http",
"url": "https://notes.example.com/mcp"
}
}
}
Uwierzytelnianie serwera deklaruje się w tym samym pliku, pod kluczem extensions["com.openai"].auth dla każdego serwera – należy ono do serwera, a nie do manifestu. W przypadku zgłoszenia publicznego przesyłasz zdalny punkt końcowy HTTPS; serwery lokalne podlegają osobnej ścieżce zarezerwowanej dla wtyczek desktopowych.
Metadane specyficzne dla OpenAI
Prezentacja w katalogu, mapowania do już zarejestrowanych serwerów MCP oraz hooki są deklarowane w obiekcie extensions.com.openai w głównym pliku plugin.json, podczas gdy przenośna tożsamość (name, version, description) pozostaje w katalogu głównym:
{
"$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"
}
}
}
}
Ścieżki w tym obiekcie są względne wobec katalogu głównego wtyczki i zaczynają się od ./. Zasoby graficzne (composerIcon, logo, screenshots) powinny najlepiej trafić do ./assets/. Pole apps służy wyłącznie do wskazania pliku .app.json zawierającego mapowania do serwerów MCP już zarejestrowanych w ChatGPT.
Możesz również zadeklarować umiejętność wdrożeniową (onboarding skill) poprzez extensions.com.openai.onboardingSkill (na przykład ./skills/setup/SKILL.md): prowadzi ona użytkownika po instalacji, pomagając wybrać przestrzeń roboczą lub ustawić preferencje. Przetestuj ją w nowej rozmowie oraz podczas trwającej instalacji.
Starszy format, z manifestem w .codex-plugin/plugin.json, jest nadal akceptowany ze względów kompatybilności: jest używany tylko wtedy, gdy obiekt extensions.com.openai nie występuje, ponieważ te dwa formaty nie łączą się ze sobą. Nowe pakiety powinny używać głównego pliku plugin.json.
Szybka ścieżka: @plugin-creator
ChatGPT i Codex zawierają umiejętność @plugin-creator, która generuje dla Ciebie strukturę – obecnie w formacie kompatybilnościowym .codex-plugin/. Aby dołączyć do niej serwer MCP, najpierw połącz ten serwer w ChatGPT (Add custom MCP server, a następnie Create as a plugin), zanotuj techniczny identyfikator połączenia z adresu URL przeglądarki – zaczyna się on od plugin_asdk_app – i przekaż go do @plugin-creator w trybie Work (lub do $plugin-creator w Codex). Umiejętność ta może również utworzyć wpis w osobistym marketplace, co pozwala zainstalować i przetestować wtyczkę ze źródła w Twoim katalogu lokalnym.
Lokalne marketplace
Marketplace to katalog JSON wtyczek. Służy do pisania, testowania i dystrybucji zespołowej obok publicznego katalogu: w trybie Work lub w Codex każdy marketplace pojawia się jako wybieralne źródło w katalogu wtyczek. W ten sposób przetestujesz kompletną wtyczkę przed jej zgłoszeniem (Lekcja 9).
Hooki: tylko wersja desktopowa
Hooki cyklu życia są obsługiwane wyłącznie dla wtyczek instalowanych ręcznie w aplikacji desktopowej Codex, a wtyczka je zawierająca nie kwalifikuje się do publicznego katalogu. Jeśli Twoja wtyczka ma trafić do publikacji, pomiń je.
Kluczowe wnioski
- Przenośny pakiet:
plugin.json(schemat Agent Plugins),skills/,mcp.json,assets/ - Serwer MCP jest deklarowany w
mcp.jsonwraz z typem transportu; tam też znajduje się uwierzytelnianie - Prezentacja, mapowania i umiejętność wdrożeniowa trafiają do
extensions.com.openai @plugin-creatorgeneruje strukturę; lokalny marketplace służy do testów- Wtyczka z hookami nie kwalifikuje się do publicznego katalogu