# Codex Plugins для початківців: що прийшло на зміну звичайним Skills > Вичерпний посібник з екосистеми плагінів у Codex: відмінності між Skills та Plugins, підключення Marketplaces, встановлення через GUI та CLI, інтеграція MCP-серверів та розробка власного плагіна. ## 1. Еволюція екосистеми: від базових Skills до модульних Plugins На ранніх етапах роботи з автономними середовищами розробки основним інструментом налаштування поведінки ШІ-агента були **Skills** — ізольовані папки з інструкціями у форматі Markdown (`SKILL.md`), які пояснювали моделі, як виконувати специфічні таски: проводити код-рев'ю за стандартами команди, оптимізувати базу даних чи формувати документацію. Skills залишаються фундаментальною одиницею знань, проте їхнє ручне копіювання між репозиторіями, відсутність стандартизованого керування залежностями та неможливість поставляти разом з інструкціями виконувані інструменти призвели до появи повноцінної модульної екосистеми — **Codex Plugins** та каталогів **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 ``` ### Порівняння архітектури: Skill проти Plugin | Характеристика | Базовий Skill | Модульний Plugin | | :--- | :--- | :--- | | **Основне призначення** | Опис правил та покрокового процесу для конкретного завдання | Повноцінний пакет розширення середовища агента | | **Склад пакету** | Текстовий файл `SKILL.md` + додаткові довідкові файли | Набір Skills, MCP-сервери, хуки життєвого циклу, конфігурація | | **Зовнішні інтеграції** | Не підтримує підключення до API сторонніх сервісів | Інтегрує зовнішні сервіси через протокол MCP (Model Context Protocol) | | **Дистрибуція** | Ручне копіювання файлів у робочу директорію проєкту | Встановлення однією командою або кліком через Marketplaces | | **Оновлення** | Ручна заміна файлів користувачем | Автоматичне оновлення через CLI або каталог розширень | > [!NOTE] > Найточніша аналогія: **Skills — це окремі бібліотечні функції**, а **Plugins — це готові пакети (npm-модулі)**. Якщо вам потрібна лише коротка інструкція для власного проєкту, звичайного Skill достатньо. Якщо ж ви хочете надати моделі інструменти взаємодії з GitHub, Slack чи Figma разом із готовими сценаріями їх використання — обирайте Plugin. --- ## 2. Анатомія плагіна: Skills, MCP-сервери, конфігурації та хуки Плагін у Codex — це не просто великий системний промпт. Це структурований каталог або архів, що містить декларативний маніфест та всі необхідні виконувані артефакти. ```text my-awesome-plugin/ ├── .codex-plugin/ │ └── plugin.json # Обов'язковий маніфест плагіна ├── skills/ │ ├── code-review/ │ │ └── SKILL.md # Перший вбудований скіл │ └── perf-audit/ │ └── SKILL.md # Другий вбудований скіл ├── mcp/ │ └── server-config.json # Конфігурація підключення MCP-сервера └── README.md # Документація для розробника ``` ### Складові частини сучасного плагіна 1. **Маніфест (`.codex-plugin/plugin.json`):** Головний конфігураційний файл, який визначає унікальний ідентифікатор плагіна, його версію, автора, залежності та точки входу. 2. **Набір скілів (`skills/`):** Один або кілька каталогів із файлами `SKILL.md`, які навчають Codex спеціалізованим підходам до кодової бази. 3. **MCP-сервери (Model Context Protocol):** Виконувані сервери або адаптери, що надають агенту нові інструменти — наприклад, можливість читати pull requests у GitHub, створювати задачі в Linear чи завантажувати дизайн-макети з Figma. 4. **Хуки життєвого циклу (Lifecycle Hooks):** Скрипти або команди, які запускаються автоматично при настанні певних подій у сесії (наприклад, перевірка лінтером перед створенням коміту). ```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] > На відміну від звичайних промптів, плагіни здатні розширювати безпосередні технічні можливості агента (tooling capability). Без плагіна з MCP-сервером агент лише міркує про роботу з GitHub; з підключеним плагіном він отримує нативні команди для виклику GitHub API. --- ## 3. Що таке Marketplaces: каталоги розширень та джерела поширення Для централізованого пошуку, перевірки та поширення плагінів Codex використовує концепцію **Marketplaces** (каталогів розширень). Marketplace — це реєстр або репозиторій, що містить список доступних плагінів, їхні метадані та адреси джерел для завантаження. Замість того щоб самостійно завантажувати архіви з ненадійних сайтів, розробник підключає перевірений маркетплейс і встановлює потрібні пакети за їхнім коротким ідентифікатором. ```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 ``` ### Типи підтримуваних маркетплейсів - **Офіційний публічний каталог:** Вбудований реєстр, доступний за замовчуванням усім користувачам Codex. Містить верифіковані плагіни для популярних сервісів (Figma, Notion, Google Workspace, GitHub). - **Git-репозиторії спільноти:** Будь-який публічний або приватний репозиторій на GitHub чи GitLab, оформлений за специфікацією маркетплейсу. - **Внутрішні корпоративні реєстри:** Каталоги компанії, де зберігаються закриті плагіни для роботи з внутрішніми мікросервісами, VPN та комплаєнс-системами. - **Локальні каталоги розробки:** Звичайні локальні директорії на вашому комп'ютері, які використовуються для розробки та тестування нових плагінів перед їхньою публікацією. --- ## 4. Робота через графічний інтерфейс: команда /plugins та управління Для більшості щоденних сценаріїв взаємодії розробнику не обов'язково використовувати довгі термінальні команди — у Codex передбачено зручний вбудований графічний браузер плагінів. ### Виклик графічного каталогу Щоб відкрити інтерфейс керування плагінами, введіть у діалоговому рядку активної сесії Codex слеш-команду: ```bash /plugins ``` Після введення команди на екрані з'явиться візуальний менеджер, у якому ви можете: - **Переглядати встановлені плагіни:** Бачити список усіх активних у системі розширень та їхній поточний статус. - **Шукати нові розширення:** Використовувати рядок пошуку для знаходження плагінів за назвою, тегами чи категоріями (Development, DevOps, Analytics, Design). - **Перемикатися між маркетплейсами:** Фільтрувати доступні плагіни за конкретними підключеними каталогами. - **Керувати активністю:** В один клік вмикати (Enable) або тимчасово вимикати (Disable) плагіни без їх повного видалення. > [!WARNING] > **Правило нової сесії:** Після встановлення нового плагіна або ввімкнення вимкненого розширення його інструменти та скіли стають доступними **лише у новостворених робочих сесіях**. Поточна сесія зберігає свій початковий стан виконання, тому обов'язково відкрийте новий діалог після зміни конфігурації плагінів. --- ## 5. Керування плагінами через CLI: список, встановлення та видалення Для користувачів, які віддають перевагу терміналу, а також для автоматизації налаштування середовища в CI/CD чи Docker-контейнерах, Codex пропонує повний набір CLI-команд підгрупи `codex plugin`. ### Базові операції з плагінами :::tabs @tab Перегляд встановлених ```bash # Вивести перелік усіх встановлених на поточній машині плагінів codex plugin list ``` @tab Перегляд доступних ```bash # Переглянути список усіх плагінів, доступних у підключених маркетплейсах codex plugin list --available # Отримати детальний список у машиночитаному форматі JSON codex plugin list --available --json ``` @tab Встановлення плагіна ```bash # Встановити плагін за унікальним ім'ям codex plugin add github-toolkit # Встановити плагін із конкретного підключеного маркетплейсу codex plugin add dev-suite@company-internal ``` @tab Видалення плагіна ```bash # Повністю видалити встановлений плагін із системи codex plugin remove github-toolkit # Видалити плагін з прив'язкою до конкретного джерела codex plugin remove dev-suite@company-internal ``` ::: Команда `codex plugin list` виводить статус кожного плагіна: назву, версію, джерело встановлення, а також стан увімкнення/вимкнення. --- ## 6. Керування Marketplaces: додавання репозиторіїв, оновлення та видалення Щоб розширити список доступних плагінів, розробник може підключати зовнішні джерела за допомогою підкоманд `codex plugin marketplace`. ### Перегляд підключених каталогів ```bash codex plugin marketplace list ``` Команда відображає назву кожного каталогу, тип джерела (git або local) та поточний URI. ### Додавання нових джерел Codex підтримує кілька форматів посилання на маркетплейс залежно від середовища та протоколу доступу: :::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 Локальний каталог ```bash # Підключення локальної папки для тестування власного маркетплейсу codex plugin marketplace add ./my-local-marketplace ``` ::: ### Оновлення та видалення маркетплейсів ```bash # Оновити метадані конкретного маркетплейсу (завантажити свіжі версії плагінів) codex plugin marketplace upgrade community-plugins # Оновити всі підключені Git-маркетплейси одночасно codex plugin marketplace upgrade # Видалити маркетплейс зі списку джерел codex plugin marketplace remove community-plugins ``` > [!TIP] > Якщо плагін не знаходить оновлень або щойно опублікований колегами пакет не відображається у вашому списку, запустіть `codex plugin marketplace upgrade`, щоб оновити локальний індекс каталогів. --- ## 7. Плагіни з MCP-серверами: авторизація, права доступу та безпека Коли встановлений плагін містить у собі **MCP-сервер**, він отримує здатність взаємодіяти із зовнішніми системами (базами даних, хмарними сховищами, API-ендпоінтами). Це перетворює Codex із пасивного генератора коду на активного виконавця задач. ```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 успішно створено!" ``` ### Особливості авторизації зовнішніх сервісів 1. **OAuth-автентифікація:** Більшість хмарних сервісів (Google Drive, Slack, GitHub) під час першого звернення відкриють вікно браузера з вимогою підтвердити доступ до вашого облікового запису. 2. **API-токени в оточенні:** Для сервісів баз даних чи внутрішніх серверів (PostgreSQL, Supabase) токени доступу зчитуються зі змінних середовища (`.env`) або глобальної конфігурації Codex. 3. **Гранулярні дозволи (Permissions):** Codex завжди запитує підтвердження користувача перед виконанням потенційно деструктивних дій (видалення записів у базі, відправка повідомлень, закриття pull request). > [!WARNING] > **Безпека MCP-серверів:** Ніколи не встановлюйте плагіни з сумнівних маркетплейсів, якщо вони містять MCP-сервери. Шкідливий MCP-сервер може отримати доступ до ваших локальних файлів або відправити конфіденційні API-ключі на сторонні сервери. Завжди аналізуйте вихідний код перед встановленням. --- ## 8. Життєвий цикл: вимкнення, видалення плагіна чи відключення каталогу Початківці часто плутають три різні рівні деактивації розширень: тимчасове вимкнення, повне видалення плагіна та відключення маркетплейсу. | Дія | Команда | Що відбувається з файлами | Наслідки для сесій | | :--- | :--- | :--- | :--- | | **Вимкнення плагіна (Disable)** | Через `/plugins` перемикач | Плагін залишається на диску, конфігурація зберігається | Скіли та MCP-інструменти стають неактивними в нових сесіях | | **Видалення плагіна (Uninstall)** | `codex plugin remove ` | Усі файли плагіна видаляються з локального середовища | Повне очищення; для повторного використання потрібне нове завантаження | | **Видалення маркетплейсу** | `codex plugin marketplace remove ` | Видаляється лише джерело; вже встановлені плагіни залишаються | Неможливо оновлювати або встановлювати нові плагіни з цього каталогу | ### Рекомендації з вибору дії - Якщо плагін викликає конфлікти або вам тимчасово не потрібні його важкі MCP-інструменти — **вимкніть його (Disable)** через `/plugins`. - Якщо ви завершили проєкт і більше не плануєте працювати з цією технологією — **повністю видаліть плагін (Remove)** через CLI. - Якщо репозиторій стороннього розробника став неактивним або застарів — **видаліть маркетплейс (Marketplace Remove)**. --- ## 9. Розробка власного Plugin: маніфест, пакування Skills та локальне тестування Створення власного плагіна — це найкращий спосіб стандартизувати робочі процеси у вашій команді та забезпечити однаковий рівень генерації коду для всіх інженерів. ### Покроковий воркфлоу створення плагіна #### Крок 1. Підготовка робочого простору Створіть чисту директорію для вашого майбутнього плагіна: ```bash mkdir -p my-team-plugin/.codex-plugin mkdir -p my-team-plugin/skills/architecture-review ``` #### Крок 2. Створення маніфесту `plugin.json` Усередині каталогу `.codex-plugin/` створіть файл `plugin.json`: ```json { "name": "team-architecture-plugin", "version": "1.0.0", "description": "Фірмові правила проєктування сервісів та аудит чистої архітектури", "author": "Architecture Guild", "skills": [ "./skills/architecture-review" ] } ``` #### Крок 3. Додавання інструкцій у `SKILL.md` Створіть файл `my-team-plugin/skills/architecture-review/SKILL.md`: ```markdown --- name: architecture-review description: Перевірка відповідності модулів принципам Domain-Driven Design (DDD) --- При аналізі нових архітектурних модулів перевіряй такі правила: 1. Бізнес-логіка не повинна напряму імпортувати ORM або базу даних. 2. Усі зовнішні інтерфейси визначаються як порти (інтерфейси) у внутрішньому шарі. 3. Кожна мутація даних повинна супроводжуватися викликом domain events. ``` #### Крок 4. Створення тестового маркетплейсу та встановлення Щоб перевірити роботу локально без публікації на GitHub, створіть папку локального маркетплейсу `local-market/` та додайте туди ваш плагін. Після цього виконайте: ```bash # Підключаємо локальну папку як джерело маркетплейсу codex plugin marketplace add ./local-market # Встановлюємо наш щойно створений плагін codex plugin add team-architecture-plugin # Перевіряємо статус встановлення codex plugin list ``` Тепер розпочніть нову сесію у Codex і протестуйте роботу підключеного плагіна на реальній задачі з архітектури коду. --- ## 10. Підсумкова шпаргалка з команд та чек-лист безпеки перед встановленням Збережіть цей зведений довідник для швидкої навігації у терміналі та під час щоденної роботи. ### Швидкий довідник 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 # Відкрити інтерактивний браузер плагінів ``` ### Чек-лист безпеки перед встановленням стороннього плагіна - [ ] **Репутація джерела:** Репозиторій маркетплейсу належить офіційному вендору або авторитетній open-source спільноті. - [ ] **Аудит маніфесту:** У `plugin.json` відсутні підозрілі виконувані команди або незрозумілі бінарні залежності. - [ ] **Перевірка мережевих адрес MCP:** Якщо плагін містить MCP-сервер, його мережеві запити направляються виключно на офіційні адреси цільового сервісу. - [ ] **Мінімізація конфліктів:** Скіли плагіна не дублюють і не перекривають уже встановлені правила робочого середовища. - [ ] **Тестування у новій сесії:** Роботу плагіна перевірено на тестовій ізольованій задачі перед використанням у продакшн-репозиторії.