# Wtyczki Codex dla początkujących: co zastąpiło zwykłe Skills > Kompleksowy przewodnik po ekosystemie wtyczek w Codex: różnice między Skills a Plugins, podłączanie Marketplaces, instalacja przez GUI i CLI, integracja serwerów MCP oraz tworzenie własnych wtyczek. ## 1. Ewolucja ekosystemu: od podstawowych Skills do modułowych Plugins Na wczesnych etapach pracy z autonomicznymi środowiskami programistycznymi głównym narzędziem konfiguracji zachowania agenta AI były **Skills** – izolowane foldery z instrukcjami w formacie Markdown (`SKILL.md`), które wyjaśniały modelowi, jak wykonywać specyficzne zadania: przeprowadzać code review zgodnie ze standardami zespołu, optymalizować bazę danych czy generować dokumentację. Skills pozostają fundamentalną jednostką wiedzy, jednak ich ręczne kopiowanie między repozytoriami, brak standaryzowanego zarządzania zależnościami oraz niemożność dostarczania wraz z instrukcjami wykonywalnych narzędzi doprowadziły do powstania pełnoprawnego, modułowego ekosystemu – **Codex Plugins** oraz katalogów **Marketplaces**. ```mermaid flowchart TD subgraph Distribution ["Рівень дистрибуції"] M["Marketplace (Git-репо або локальний каталог)"] end subgraph Packaging ["Рівень пакетування: Plugin"] P["Codex Plugin"] P --> S["Skills (Інструкції та експертиза)"] P --> T["MCP Tools (Зовнішні API: GitHub, Slack, Figma)"] P --> H["Hooks (Автоматичні тригери подій)"] P --> C["Config (Маніфест plugin.json)"] end subgraph Execution ["Рівень виконання"] Session["Нова робоча сесія Codex"] end M -->|codex plugin add| P P -->|Ініціалізація розширень| Session ``` ### Porównanie architektury: Skill vs Plugin | Cecha | Podstawowy Skill | Modułowy Plugin | | :--- | :--- | :--- | | **Główne przeznaczenie** | Opis reguł i procesów krok po kroku dla konkretnego zadania | Pełnoprawny pakiet rozszerzeń środowiska agenta | | **Skład pakietu** | Plik tekstowy `SKILL.md` + dodatkowe pliki referencyjne | Zbiór Skills, serwery MCP, hooki cyklu życia, konfiguracja | | **Integracje zewnętrzne** | Nie obsługuje połączeń z API usług zewnętrznych | Integruje usługi zewnętrzne przez protokół MCP (Model Context Protocol) | | **Dystrybucja** | Ręczne kopiowanie plików do katalogu roboczego projektu | Instalacja jedną komendą lub kliknięciem przez Marketplaces | | **Aktualizacje** | Ręczna wymiana plików przez użytkownika | Automatyczne aktualizacje przez CLI lub katalog rozszerzeń | > [!NOTE] > Najdokładniejsza analogia: **Skills to pojedyncze funkcje biblioteczne**, a **Plugins to gotowe pakiety (moduły npm)**. Jeśli potrzebujesz jedynie krótkiej instrukcji dla własnego projektu, zwykłego Skill wystarczy. Jeśli natomiast chcesz dać modelowi narzędzia do interakcji z GitHub, Slack czy Figma wraz z gotowymi scenariuszami ich użycia – wybierz Plugin. --- ## 2. Anatomia pluginu: Skills, serwery MCP, konfiguracje i hooki Plugin w Codex to nie tylko duży prompt systemowy. To strukturalny katalog lub archiwum zawierające deklaratywny manifest oraz wszystkie niezbędne artefakty wykonywalne. ```text my-awesome-plugin/ ├── .codex-plugin/ │ └── plugin.json # Obowiązkowy manifest wtyczki ├── skills/ │ ├── code-review/ │ │ └── SKILL.md # Pierwsza wbudowana umiejętność (skill) │ └── perf-audit/ │ └── SKILL.md # Druga wbudowana umiejętność (skill) ├── mcp/ │ └── server-config.json # Konfiguracja połączenia z serwerem MCP └── README.md # Dokumentacja dla programistów ``` ### Składowe części współczesnego pluginu 1. **Manifest (`.codex-plugin/plugin.json`):** Główny plik konfiguracyjny definiujący unikalny identyfikator pluginu, jego wersję, autora, zależności oraz punkty wejścia. 2. **Zestaw skills (`skills/`):** Jeden lub więcej katalogów z plikami `SKILL.md`, które uczą Codex specjalistycznych podejść do bazy kodu. 3. **Serwery MCP (Model Context Protocol):** Wykonywalne serwery lub adaptery udostępniające agentowi nowe narzędzia – na przykład możliwość odczytywania pull requestów w GitHub, tworzenia zadań w Linear czy pobierania makiet projektowych z Figma. 4. **Hooki cyklu życia (Lifecycle Hooks):** Skrypty lub komendy uruchamiane automatycznie przy wystąpieniu określonych zdarzeń w sesji (np. sprawdzenie lintem przed utworzeniem commita). ```json { "name": "developer-toolkit", "version": "1.2.0", "description": "Розширений набір інструментів для аудиту коду та автоматизації GitHub", "author": "Engineering Team", "skills": [ "./skills/code-review", "./skills/perf-audit" ], "mcpServers": { "github-connector": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } } ``` > [!IMPORTANT] > W przeciwieństwie do zwykłych promptów, pluginy potrafią bezpośrednio rozszerzać techniczne możliwości agenta (tooling capability). Bez pluginu z serwerem MCP agent jedynie „myśli” o pracy z GitHub; z podłączonym pluginem otrzymuje natywne komendy do wywoływania API GitHub. --- ## 3. Czym są Marketplaces: katalogi rozszerzeń i źródła dystrybucji Do scentralizowanego wyszukiwania, weryfikacji i dystrybucji pluginów Codex wykorzystuje koncepcję **Marketplaces** (katalogów rozszerzeń). Marketplace to rejestr lub repozytorium zawierające listę dostępnych pluginów, ich metadane oraz adresy źródeł do pobrania. Zamiast samodzielnie pobierać archiwa z niepewnych stron, deweloper podłącza zweryfikowany marketplace i instaluje potrzebne pakiety za pomocą ich krótkich identyfikatorów. ```mermaid flowchart LR subgraph Sources ["Джерела каталогів"] Official["Офіційний реєстр OpenAI"] Community["Публічний GitHub-каталог"] Private["Внутрішній GitLab компанії"] Local["Локальна папка розробника"] end subgraph Client ["Клієнтське середовище Codex"] Reg["Менеджер Marketplaces"] Reg --> P1["Plugin: GitHub Sync"] Reg --> P2["Plugin: PostgreSQL Inspector"] Reg --> P3["Plugin: Team Styleguide"] end Official --> Reg Community --> Reg Private --> Reg Local --> Reg ``` ### Typy obsługiwanych marketplace’ów - **Oficjalny publiczny katalog:** Wbudowany rejestr dostępny domyślnie dla wszystkich użytkowników Codex. Zawiera zweryfikowane pluginy dla popularnych usług (Figma, Notion, Google Workspace, GitHub). - **Repozytoria Git społeczności:** Dowolne publiczne lub prywatne repozytorium na GitHub lub GitLab, sformatowane zgodnie ze specyfikacją marketplace. - **Wewnętrzne rejestry korporacyjne:** Katalogi firmowe, w których przechowywane są zamknięte pluginy do pracy z wewnętrznymi mikrousługami, VPN oraz systemami compliance. - **Lokalne katalogi deweloperskie:** Zwykłe katalogi lokalne na Twoim komputerze, używane do rozwoju i testowania nowych pluginów przed ich publikacją. --- ## 4. Praca przez interfejs graficzny: komenda /plugins i zarządzanie Dla większości codziennych scenariuszy współpracy deweloper nie musi korzystać z długich komend terminalowych – w Codex przewidziano wygodny, wbudowany graficzny przeglądarka pluginów. ### Wywołanie graficznego katalogu Aby otworzyć interfejs zarządzania pluginami, wpisz w pasku dialogowym aktywnej sesji Codex komendę slash: ```bash /plugins ``` Po wpisaniu komendy na ekranie pojawi się wizualny menedżer, w którym możesz: - **Przeglądać zainstalowane pluginy:** Widzieć listę wszystkich aktywnych rozszerzeń w systemie oraz ich bieżący status. - **Szukać nowych rozszerzeń:** Korzystać z pola wyszukiwania, aby znaleźć pluginy po nazwie, tagach czy kategoriach (Development, DevOps, Analytics, Design). - **Przełączać się między marketplace’ami:** Filtrować dostępne pluginy według konkretnych podłączonych katalogów. - **Zarządzać aktywnością:** Jednym kliknięciem włączać (Enable) lub tymczasowo wyłączać (Disable) pluginy bez ich całkowitego usuwania. > [!WARNING] > **Reguła nowej sesji:** Po zainstalowaniu nowego pluginu lub włączeniu wyłączonego rozszerzenia jego narzędzia i skills stają się dostępne **tylko w nowo tworzonych sesjach roboczych**. Bieżąca sesja zachowuje swój początkowy stan wykonania, dlatego po zmianie konfiguracji pluginów należy koniecznie otworzyć nowy dialog. --- ## 5. Zarządzanie pluginami przez CLI: lista, instalacja i usuwanie Dla użytkowników preferujących terminal, a także do automatyzacji konfiguracji środowiska w CI/CD czy kontenerach Docker, Codex oferuje pełny zestaw komend CLI podgrupy `codex plugin`. ### Podstawowe operacje na pluginach :::tabs @tab Przegląd zainstalowanych ```bash # Вивести перелік усіх встановлених на поточній машині плагінів codex plugin list ``` @tab Przegląd dostępnych ```bash # Переглянути список усіх плагінів, доступних у підключених маркетплейсах codex plugin list --available # Отримати детальний список у машиночитаному форматі JSON codex plugin list --available --json ``` @tab Instalacja pluginu ```bash # Встановити плагін за унікальним ім'ям codex plugin add github-toolkit # Встановити плагін із конкретного підключеного маркетплейсу codex plugin add dev-suite@company-internal ``` @tab Usunięcie pluginu ```bash # Повністю видалити встановлений плагін із системи codex plugin remove github-toolkit # Видалити плагін з прив'язкою до конкретного джерела codex plugin remove dev-suite@company-internal ``` ::: Komenda `codex plugin list` wyświetla status każdego pluginu: nazwę, wersję, źródło instalacji oraz stan włączenia/wyłączenia. --- ## 6. Zarządzanie Marketplaces: dodawanie repozytoriów, aktualizacje i usuwanie Aby rozszerzyć listę dostępnych pluginów, deweloper może podłączać zewnętrzne źródła za pomocą podpolecenia `codex plugin marketplace`. ### Przegląd podłączonych katalogów ```bash codex plugin marketplace list ``` Komenda wyświetla nazwę każdego katalogu, typ źródła (git lub local) oraz bieżący URI. ### Dodawanie nowych źródeł Codex obsługuje kilka formatów odwołań do marketplace w zależności od środowiska i protokołu dostępu: :::tabs @tab GitHub Shorthand ```bash # Скорочений запис для публічних або доступних репозиторіїв GitHub (owner/repo) codex plugin marketplace add orlov-ai/community-plugins ``` @tab HTTPS Git URL ```bash # Стандартне підключення через HTTPS (підходить для публічних GitLab/Bitbucket) codex plugin marketplace add https://github.com/company/internal-codex-plugins.git ``` @tab SSH Git URL ```bash # Підключення через приватні SSH-ключі для закритих корпоративних репозиторіїв codex plugin marketplace add git@github.com:enterprise/secure-plugins.git ``` @tab Katalog lokalny ```bash # Підключення локальної папки для тестування власного маркетплейсу codex plugin marketplace add ./my-local-marketplace ``` ::: ### Aktualizacja i usuwanie marketplace’ów ```bash # Оновити метадані конкретного маркетплейсу (завантажити свіжі версії плагінів) codex plugin marketplace upgrade community-plugins # Оновити всі підключені Git-маркетплейси одночасно codex plugin marketplace upgrade # Видалити маркетплейс зі списку джерел codex plugin marketplace remove community-plugins ``` > [!TIP] > Jeśli plugin nie znajduje aktualizacji lub niedawno opublikowany przez kolegów pakiet nie pojawia się na Twojej liście, uruchom `codex plugin marketplace upgrade`, aby odświeżyć lokalny indeks katalogów. --- ## 7. Pluginy z serwerami MCP: autoryzacja, uprawnienia i bezpieczeństwo Gdy zainstalowany plugin zawiera w sobie **serwer MCP**, zyskuje zdolność do interakcji z systemami zewnętrznymi (bazami danych, chmurami, endpointami API). To przekształca Codex z pasywnego generatora kodu w aktywnego wykonawcę zadań. ```mermaid sequenceDiagram autonumber actor Dev as Інженер participant Codex as Codex Session participant Plugin as Plugin (MCP Adapter) participant Cloud as Зовнішній сервіс (GitHub API) Dev->>Codex: "Створи issue з результатами аудиту" Codex->>Plugin: Виклик інструменту create_issue() alt Потрібна авторизація Plugin-->>Dev: Запит OAuth-авторизації або токена Dev->>Plugin: Підтвердження облікового запису end Plugin->>Cloud: POST /repos/:owner/:repo/issues Cloud-->>Plugin: HTTP 201 Created (Issue #42) Plugin-->>Codex: Результат виконання з посиланням Codex-->>Dev: "Issue #42 успішно створено!" ``` ### Specyfika autoryzacji usług zewnętrznych 1. **Autentykacja OAuth:** Większość usług chmurowych (Google Drive, Slack, GitHub) podczas pierwszego wywołania otworzy okno przeglądarki z żądaniem potwierdzenia dostępu do Twojego konta. 2. **Tokeny API w środowisku:** Dla usług bazodanowych lub wewnętrznych serwerów (PostgreSQL, Supabase) tokeny dostępu są odczytywane ze zmiennych środowiskowych (`.env`) lub globalnej konfiguracji Codex. 3. **Granularne uprawnienia (Permissions):** Codex zawsze prosi o potwierdzenie użytkownika przed wykonaniem potencjalnie destrukcyjnych akcji (usuwanie rekordów w bazie, wysyłanie wiadomości, zamykanie pull request). > [!WARNING] > **Bezpieczeństwo serwerów MCP:** Nigdy nie instaluj pluginów z podejrzanych marketplace’ów, jeśli zawierają one serwery MCP. Złośliwy serwer MCP może uzyskać dostęp do Twoich lokalnych plików lub wysłać poufne klucze API na zewnętrzne serwery. Zawsze analizuj kod źródłowy przed instalacją. --- ## 8. Cykl życia: wyłączanie, usuwanie pluginu lub odłączanie katalogu Początkujący często mylą trzy różne poziomy dezaktywacji rozszerzeń: tymczasowe wyłączenie, całkowite usunięcie pluginu oraz odłączenie marketplace. | Akcja | Komenda | Co dzieje się z plikami | Konsekwencje dla sesji | | :--- | :--- | :--- | :--- | | **Wyłączenie pluginu (Disable)** | Przełącznik w `/plugins` | Plugin pozostaje na dysku, konfiguracja jest zachowana | Skills i narzędzia MCP stają się nieaktywne w nowych sesjach | | **Usunięcie pluginu (Uninstall)** | `codex plugin remove ` | Wszystkie pliki pluginu są usuwane z lokalnego środowiska | Całkowite czyszczenie; do ponownego użycia wymagane nowe pobranie | | **Usunięcie marketplace** | `codex plugin marketplace remove ` | Usuwane jest tylko źródło; już zainstalowane pluginy pozostają | Niemożliwe jest aktualizowanie lub instalowanie nowych pluginów z tego katalogu | ### Rekomendacje dotyczące wyboru akcji - Jeśli plugin powoduje konflikty lub tymczasowo nie potrzebujesz jego ciężkich narzędzi MCP – **wyłącz go (Disable)** przez `/plugins`. - Jeśli zakończyłeś projekt i nie planujesz dalszej pracy z tą technologią – **całkowicie usuń plugin (Remove)** przez CLI. - Jeśli repozytorium zewnętrznego dewelopera stało się nieaktywne lub przestarzałe – **usuń marketplace (Marketplace Remove)**. --- ## 9. Rozwój własnego Plugin: manifest, pakowanie Skills i testowanie lokalne Tworzenie własnego pluginu to najlepszy sposób na standaryzację workflow w Twoim zespole oraz zapewnienie jednolitego poziomu generowania kodu dla wszystkich inżynierów. ### Workflow krok po kroku tworzenia pluginu #### Krok 1. Przygotowanie workspace Utwórz czysty katalog dla przyszłego pluginu: ```bash mkdir -p my-team-plugin/.codex-plugin mkdir -p my-team-plugin/skills/architecture-review ``` #### Krok 2. Tworzenie manifestu `plugin.json` Wewnątrz katalogu `.codex-plugin/` utwórz plik `plugin.json`: ```json { "name": "team-architecture-plugin", "version": "1.0.0", "description": "Фірмові правила проєктування сервісів та аудит чистої архітектури", "author": "Architecture Guild", "skills": [ "./skills/architecture-review" ] } ``` #### Krok 3. Dodawanie instrukcji w `SKILL.md` Utwórz plik `my-team-plugin/skills/architecture-review/SKILL.md`: ```markdown --- name: architecture-review description: Weryfikacja zgodności modułów z zasadami Domain-Driven Design (DDD) --- Podczas analizy nowych modułów architektonicznych sprawdzaj następujące zasady: 1. Logika biznesowa nie powinna bezpośrednio importować ORM ani bazy danych. 2. Wszystkie interfejsy zewnętrzne są definiowane jako porty (interfejsy) w warstwie wewnętrznej. 3. Każda mutacja danych powinna być związana z wywołaniem zdarzeń domenowych (domain events). ``` #### Krok 4. Tworzenie testowego marketplace i instalacja Aby sprawdzić działanie lokalnie bez publikacji na GitHub, utwórz folder lokalnego marketplace `local-market/` i dodaj tam swój plugin. Następnie wykonaj: ```bash # Підключаємо локальну папку як джерело маркетплейсу codex plugin marketplace add ./local-market # Встановлюємо наш щойно створений плагін codex plugin add team-architecture-plugin # Перевіряємо статус встановлення codex plugin list ``` Teraz rozpocznij nową sesję w Codex i przetestuj działanie podłączonego pluginu na realnym zadaniu z zakresu architektury kodu. --- ## 10. Podsumowująca ściągawka z komend i checklist bezpieczeństwa przed instalacją Zapisz ten zbiorczy przewodnik dla szybkiej nawigacji w terminalu oraz podczas codziennej pracy. ### Szybki przewodnik po komendach CLI ```bash # ─── Робота з плагінами ─────────────────────────────────────────── codex plugin list # Список встановлених плагінів codex plugin list --available # Список доступних плагінів у каталогах codex plugin add # Встановити плагін codex plugin add # Встановити з конкретного джерела codex plugin remove # Видалити плагін # ─── Робота з Marketplaces ──────────────────────────────────────── codex plugin marketplace list # Список підключених каталогів codex plugin marketplace add # Додати маркетплейс (GitHub / URL / локальний) codex plugin marketplace upgrade # Оновити конкретний каталог codex plugin marketplace upgrade # Оновити всі підключені каталоги codex plugin marketplace remove # Видалити каталог зі списку # ─── Графічний інтерфейс ───────────────────────────────────────── /plugins # Відкрити інтерактивний браузер плагінів ``` ### Checklist bezpieczeństwa przed instalacją zewnętrznego pluginu - [ ] **Reputacja źródła:** Repozytorium marketplace należy do oficjalnego vendor lub autorytatywnej społeczności open-source. - [ ] **Audyt manifestu:** W `plugin.json` brak podejrzanych komend wykonywalnych lub niezrozumiałych zależności binarnych. - [ ] **Weryfikacja adresów sieciowych MCP:** Jeśli plugin zawiera serwer MCP, jego zapytania sieciowe kierowane są wyłącznie na oficjalne adresy docelowego serwisu. - [ ] **Minimalizacja konfliktów:** Skills pluginu nie dublują ani nie nadpisują już zainstalowanych reguł środowiska pracy. - [ ] **Testowanie w nowej sesji:** Działanie pluginu zostało sprawdzone na izolowanym zadaniu testowym przed użyciem w repozytorium produkcyjnym.