# Codex Plugins pour débutants : ce qui remplace les Skills classiques > Guide complet de l'écosystème des plugins dans Codex : différences entre Skills et Plugins, connexion aux Marketplaces, installation via GUI et CLI, intégration des serveurs MCP et développement de votre propre plugin. ## 1. Évolution de l'écosystème : des Skills basiques aux Plugins modulaires Aux premiers stades du travail avec les environnements de développement autonomes, l'outil principal pour configurer le comportement de l'agent IA était les **Skills** — des dossiers isolés contenant des instructions au format Markdown (`SKILL.md`), expliquant au modèle comment exécuter des tâches spécifiques : effectuer des revues de code selon les standards de l'équipe, optimiser une base de données ou générer de la documentation. Les Skills restent l'unité fondamentale de connaissance, mais leur copie manuelle entre les dépôts, l'absence de gestion standardisée des dépendances et l'impossibilité de fournir des outils exécutables avec les instructions ont conduit à l'apparition d'un écosystème modulaire complet — les **Codex Plugins** et les catalogues **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 ``` ### Comparaison architecturale : Skill vs Plugin | Caractéristique | Skill Basique | Plugin Modulaire | | :--- | :--- | :--- | | **Objectif principal** | Description des règles et du processus étape par étape pour une tâche spécifique | Paquet d'extension complet de l'environnement agent | | **Composition du paquet** | Fichier texte `SKILL.md` + fichiers de référence supplémentaires | Ensemble de Skills, serveurs MCP, hooks de cycle de vie, configuration | | **Intégrations externes** | Ne prend pas en charge la connexion aux API de services tiers | Intègre des services externes via le protocole MCP (Model Context Protocol) | | **Distribution** | Copie manuelle des fichiers dans le répertoire de travail du projet | Installation en une seule commande ou un clic via les Marketplaces | | **Mise à jour** | Remplacement manuel des fichiers par l'utilisateur | Mise à jour automatique via CLI ou catalogue d'extensions | > [!NOTE] > L'analogie la plus précise : **les Skills sont des fonctions de bibliothèque individuelles**, tandis que **les Plugins sont des paquets prêts à l'emploi (modules npm)**. Si vous avez besoin uniquement d'une courte instruction pour votre propre projet, un Skill simple suffit. Si vous souhaitez donner au modèle des outils pour interagir avec GitHub, Slack ou Figma ainsi que des scénarios d'utilisation prêts à l'emploi — choisissez un Plugin. --- ## 2. Anatomie d'un plugin : Skills, serveurs MCP, configurations et hooks Un plugin dans Codex n'est pas simplement un grand prompt système. C'est un répertoire structuré ou une archive contenant un manifeste déclaratif et tous les artefacts exécutables nécessaires. ```text my-awesome-plugin/ ├── .codex-plugin/ │ └── plugin.json # Manifeste obligatoire du plugin ├── skills/ │ ├── code-review/ │ │ └── SKILL.md # Première compétence intégrée │ └── perf-audit/ │ └── SKILL.md # Seconde compétence intégrée ├── mcp/ │ └── server-config.json # Configuration de la connexion au serveur MCP └── README.md # Documentation pour les développeurs ``` ### Composantes d'un plugin moderne 1. **Le Manifeste (`.codex-plugin/plugin.json`) :** Le fichier de configuration principal qui définit l'identifiant unique du plugin, sa version, son auteur, ses dépendances et ses points d'entrée. 2. **L'Ensemble de skills (`skills/`) :** Un ou plusieurs répertoires contenant des fichiers `SKILL.md`, qui enseignent à Codex des approches spécialisées pour la base de code. 3. **Serveurs MCP (Model Context Protocol) :** Des serveurs exécutables ou adaptateurs qui fournissent à l'agent de nouveaux outils — par exemple, la capacité de lire des pull requests sur GitHub, de créer des tickets dans Linear ou de télécharger des maquettes depuis Figma. 4. **Hooks de cycle de vie (Lifecycle Hooks) :** Scripts ou commandes qui s'exécutent automatiquement lors de certains événements dans la session (par exemple, une vérification par linter avant la création d'un commit). ```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] > Contrairement aux prompts classiques, les plugins sont capables d'étendre directement les capacités techniques de l'agent (tooling capability). Sans un plugin avec serveur MCP, l'agent ne fait que raisonner sur le travail avec GitHub ; avec un plugin connecté, il reçoit des commandes natives pour appeler l'API GitHub. --- ## 3. Qu'est-ce que les Marketplaces : catalogues d'extensions et sources de distribution Pour la recherche centralisée, la vérification et la distribution des plugins, Codex utilise le concept de **Marketplaces** (catalogues d'extensions). Une Marketplace est un registre ou un dépôt contenant la liste des plugins disponibles, leurs métadonnées et les adresses sources pour le téléchargement. Au lieu de télécharger soi-même des archives depuis des sites non fiables, le développeur connecte une marketplace vérifiée et installe les paquets requis via leur identifiant court. ```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 ``` ### Types de marketplaces supportées - **Catalogue public officiel :** Registre intégré, accessible par défaut à tous les utilisateurs de Codex. Contient des plugins vérifiés pour les services populaires (Figma, Notion, Google Workspace, GitHub). - **Dépôts Git communautaires :** N'importe quel dépôt public ou privé sur GitHub ou GitLab, conforme à la spécification de la marketplace. - **Registres internes d'entreprise :** Catalogues de l'entreprise où sont stockés des plugins fermés pour travailler avec des microservices internes, des VPN et des systèmes de conformité. - **Catalogues locaux de développement :** Répertoires locaux ordinaires sur votre ordinateur, utilisés pour développer et tester de nouveaux plugins avant leur publication. --- ## 4. Travail via l'interface graphique : commande /plugins et gestion Pour la plupart des scénarios d'interaction quotidiens, le développeur n'a pas nécessairement besoin d'utiliser de longues commandes terminales — Codex propose un navigateur de plugins graphique intégré pratique. ### Appel du catalogue graphique Pour ouvrir l'interface de gestion des plugins, tapez la commande slash dans la barre de dialogue de la session active de Codex : ```bash /plugins ``` Après avoir entré la commande, un gestionnaire visuel apparaît à l'écran, dans lequel vous pouvez : - **Consulter les plugins installés :** Voir la liste de toutes les extensions actives dans le système et leur statut actuel. - **Rechercher de nouvelles extensions :** Utiliser la barre de recherche pour trouver des plugins par nom, tags ou catégories (Development, DevOps, Analytics, Design). - **Basculer entre les marketplaces :** Filtrer les plugins disponibles selon les catalogues connectés spécifiques. - **Gérer l'activité :** Activer (Enable) ou désactiver temporairement (Disable) les plugins en un seul clic sans les supprimer complètement. > [!WARNING] > **Règle de la nouvelle session :** Après l'installation d'un nouveau plugin ou l'activation d'une extension désactivée, ses outils et skills deviennent accessibles **uniquement dans les nouvelles sessions de travail créées**. La session actuelle conserve son état d'exécution initial, donc ouvrez impérativement un nouveau dialogue après toute modification de la configuration des plugins. --- ## 5. Gestion des plugins via CLI : liste, installation et suppression Pour les utilisateurs préférant le terminal, ainsi que pour automatiser la configuration de l'environnement dans CI/CD ou des conteneurs Docker, Codex offre un ensemble complet de commandes CLI sous le sous-groupe `codex plugin`. ### Opérations de base avec les plugins :::tabs @tab Consulter les installés ```bash # Вивести перелік усіх встановлених на поточній машині плагінів codex plugin list ``` @tab Consulter les disponibles ```bash # Переглянути список усіх плагінів, доступних у підключених маркетплейсах codex plugin list --available # Отримати детальний список у машиночитаному форматі JSON codex plugin list --available --json ``` @tab Installer un plugin ```bash # Встановити плагін за унікальним ім'ям codex plugin add github-toolkit # Встановити плагін із конкретного підключеного маркетплейсу codex plugin add dev-suite@company-internal ``` @tab Supprimer un plugin ```bash # Повністю видалити встановлений плагін із системи codex plugin remove github-toolkit # Видалити плагін з прив'язкою до конкретного джерела codex plugin remove dev-suite@company-internal ``` ::: La commande `codex plugin list` affiche le statut de chaque plugin : nom, version, source d'installation, ainsi que l'état activé/désactivé. --- ## 6. Gestion des Marketplaces : ajout de dépôts, mise à jour et suppression Pour étendre la liste des plugins disponibles, le développeur peut connecter des sources externes à l'aide des sous-commandes `codex plugin marketplace`. ### Consulter les catalogues connectés ```bash codex plugin marketplace list ``` La commande affiche le nom de chaque catalogue, le type de source (git ou local) et l'URI actuel. ### Ajouter de nouvelles sources Codex prend en charge plusieurs formats de lien vers une marketplace selon l'environnement et le protocole d'accès : :::tabs @tab Raccourci GitHub ```bash # Скорочений запис для публічних або доступних репозиторіїв GitHub (owner/repo) codex plugin marketplace add orlov-ai/community-plugins ``` @tab URL Git HTTPS ```bash # Стандартне підключення через HTTPS (підходить для публічних GitLab/Bitbucket) codex plugin marketplace add https://github.com/company/internal-codex-plugins.git ``` @tab URL Git SSH ```bash # Підключення через приватні SSH-ключі для закритих корпоративних репозиторіїв codex plugin marketplace add git@github.com:enterprise/secure-plugins.git ``` @tab Répertoire local ```bash # Підключення локальної папки для тестування власного маркетплейсу codex plugin marketplace add ./my-local-marketplace ``` ::: ### Mise à jour et suppression des marketplaces ```bash # Оновити метадані конкретного маркетплейсу (завантажити свіжі версії плагінів) codex plugin marketplace upgrade community-plugins # Оновити всі підключені Git-маркетплейси одночасно codex plugin marketplace upgrade # Видалити маркетплейс зі списку джерел codex plugin marketplace remove community-plugins ``` > [!TIP] > Si un plugin ne trouve pas de mises à jour ou si un paquet publié récemment par des collègues n'apparaît pas dans votre liste, lancez `codex plugin marketplace upgrade` pour mettre à jour l'index local des catalogues. --- ## 7. Plugins avec serveurs MCP : autorisation, droits d'accès et sécurité Lorsqu'un plugin installé contient un **serveur MCP**, il acquiert la capacité d'interagir avec des systèmes externes (bases de données, stockage cloud, endpoints API). Cela transforme Codex d'un générateur de code passif en un exécuteur actif de tâches. ```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 успішно створено!" ``` ### Particularités de l'autorisation des services externes 1. **Authentification OAuth :** La plupart des services cloud (Google Drive, Slack, GitHub) ouvriront une fenêtre de navigateur lors du premier appel demandant de confirmer l'accès à votre compte. 2. **Tokens API dans l'environnement :** Pour les bases de données ou les serveurs internes (PostgreSQL, Supabase), les tokens d'accès sont lus depuis les variables d'environnement (`.env`) ou la configuration globale de Codex. 3. **Permissions granulaires :** Codex demande toujours la confirmation de l'utilisateur avant d'exécuter des actions potentiellement destructives (suppression d'enregistrements en base, envoi de messages, fermeture de pull request). > [!WARNING] > **Sécurité des serveurs MCP :** N'installez jamais de plugins provenant de marketplaces douteuses s'ils contiennent des serveurs MCP. Un serveur MCP malveillant pourrait accéder à vos fichiers locaux ou envoyer des clés API confidentielles vers des serveurs tiers. Analysez toujours le code source avant l'installation. --- ## 8. Cycle de vie : désactivation, suppression du plugin ou déconnexion du catalogue Les débutants confondent souvent trois niveaux distincts de désactivation des extensions : la désactivation temporaire, la suppression complète du plugin et la déconnexion de la marketplace. | Action | Commande | Ce qui arrive aux fichiers | Conséquences pour les sessions | | :--- | :--- | :--- | :--- | | **Désactivation du plugin (Disable)** | Via l'interrupteur `/plugins` | Le plugin reste sur le disque, la configuration est conservée | Les skills et outils MCP deviennent inactifs dans les nouvelles sessions | | **Suppression du plugin (Uninstall)** | `codex plugin remove ` | Tous les fichiers du plugin sont supprimés de l'environnement local | Nettoyage complet ; une nouvelle téléchargement est nécessaire pour réutiliser | | **Suppression de la marketplace** | `codex plugin marketplace remove ` | Seule la source est supprimée ; les plugins déjà installés restent | Impossible de mettre à jour ou d'installer de nouveaux plugins depuis ce catalogue | ### Recommandations pour choisir l'action - Si un plugin cause des conflits ou si vous n'avez pas temporairement besoin de ses lourds outils MCP — **désactivez-le (Disable)** via `/plugins`. - Si vous avez terminé un projet et ne prévoyez plus de travailler avec cette technologie — **supprimez complètement le plugin (Remove)** via CLI. - Si le dépôt d'un développeur tiers est devenu inactif ou obsolète — **supprimez la marketplace (Marketplace Remove)**. --- ## 9. Développement de votre propre Plugin : manifeste, packaging des Skills et test local Créer votre propre plugin est la meilleure façon de standardiser les workflows dans votre équipe et d'assurer un niveau uniforme de génération de code pour tous les ingénieurs. ### Workflow étape par étape pour créer un plugin #### Étape 1. Préparation de l'espace de travail Créez un répertoire vierge pour votre futur plugin : ```bash mkdir -p my-team-plugin/.codex-plugin mkdir -p my-team-plugin/skills/architecture-review ``` #### Étape 2. Création du manifeste `plugin.json` Dans le répertoire `.codex-plugin/`, créez le fichier `plugin.json` : ```json { "name": "team-architecture-plugin", "version": "1.0.0", "description": "Фірмові правила проєктування сервісів та аудит чистої архітектури", "author": "Architecture Guild", "skills": [ "./skills/architecture-review" ] } ``` #### Étape 3. Ajout des instructions dans `SKILL.md` Créez le fichier `my-team-plugin/skills/architecture-review/SKILL.md` : ```markdown --- name: architecture-review description: Vérification de la conformité des modules aux principes du Domain-Driven Design (DDD) --- Lors de l'analyse de nouveaux modules architecturaux, vérifiez les règles suivantes : 1. La logique métier ne doit pas importer directement un ORM ou une base de données. 2. Toutes les interfaces externes sont définies comme des ports (interfaces) dans la couche interne. 3. Chaque mutation de données doit être accompagnée d'un appel aux événements de domaine (domain events). ``` #### Étape 4. Création d'une marketplace de test et installation Pour vérifier le fonctionnement localement sans publier sur GitHub, créez un dossier de marketplace locale `local-market/` et ajoutez-y votre plugin. Ensuite, exécutez : ```bash # Підключаємо локальну папку як джерело маркетплейсу codex plugin marketplace add ./local-market # Встановлюємо наш щойно створений плагін codex plugin add team-architecture-plugin # Перевіряємо статус встановлення codex plugin list ``` Démarrez maintenant une nouvelle session dans Codex et testez le fonctionnement du plugin connecté sur une tâche réelle d'architecture de code. --- ## 10. Aide-mémoire final des commandes et checklist de sécurité avant installation Conservez ce guide consolidé pour une navigation rapide dans le terminal et lors du travail quotidien. ### Aide-mémoire rapide des commandes 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 de sécurité avant l'installation d'un plugin tiers - [ ] **Réputation de la source :** Le dépôt de la marketplace appartient à un éditeur officiel ou à une communauté open-source reconnue. - [ ] **Audit du manifeste :** Aucun commande exécutable suspecte ni dépendance binaire incompréhensible n'est présente dans `plugin.json`. - [ ] **Vérification des adresses réseau MCP :** Si le plugin contient un serveur MCP, ses requêtes réseau sont dirigées exclusivement vers les adresses officielles du service cible. - [ ] **Minimisation des conflits :** Les skills du plugin ne dupliquent ni ne chevauchent les règles déjà installées de l'environnement de travail. - [ ] **Test dans une nouvelle session :** Le fonctionnement du plugin a été vérifié sur une tâche isolée de test avant utilisation dans un dépôt de production.