# Codex-Plugins für Einsteiger: Was die klassischen Skills ablöst

> Umfassender Leitfaden zur Plugin-Ökosystem in Codex: Unterschiede zwischen Skills und Plugins, Anbindung von Marktplätzen, Installation über GUI und CLI, Integration von MCP-Servern sowie Entwicklung eigener Plugins.

## 1. Evolution des Ökosystems: von grundlegenden Skills zu modularen Plugins

In den frühen Phasen der Arbeit mit autonomen Entwicklungsumgebungen war das primäre Instrument zur Steuerung des Verhaltens von KI-Agenten **Skills** – isolierte Ordner mit Anweisungen im Markdown-Format (`SKILL.md`), die dem Modell erklärten, wie spezifische Aufgaben auszuführen sind: Code-Reviews nach Teamstandards durchführen, Datenbanken optimieren oder Dokumentation erstellen.

Skills bleiben die fundamentale Wissens-Einheit, doch ihr manuelles Kopieren zwischen Repositories, das Fehlen standardisierter Abhängigkeitsverwaltung und die Unmöglichkeit, ausführbare Tools zusammen mit Anweisungen bereitzustellen, führten zur Entstehung eines vollwertigen modularen Ökosystems – **Codex Plugins** und **Marketplace**-Kataloge.

```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
```

### Architekturvergleich: Skill vs. Plugin

| Merkmal | Basis-Skill | Modulares Plugin |
| :--- | :--- | :--- |
| **Hauptzweck** | Beschreibung von Regeln und schrittweisen Prozessen für eine bestimmte Aufgabe | Vollständiges Erweiterungspaket für die Agent-Umgebung |
| **Paketinhalt** | Textdatei `SKILL.md` + zusätzliche Referenzdateien | Satz von Skills, MCP-Server, Lifecycle-Hooks, Konfiguration |
| **Externe Integrationen** | Unterstützt keine Verbindung zu Drittanbieter-APIs | Integriert externe Dienste über das MCP-Protokoll (Model Context Protocol) |
| **Distribution** | Manuelles Kopieren von Dateien in das Arbeitsverzeichnis des Projekts | Installation per Einzelbefehl oder Klick über Marketplaces |
| **Updates** | Manueller Dateiversatz durch den Benutzer | Automatisches Update über CLI oder Erweiterungskatalog |

> [!NOTE]
> Die präziseste Analogie: **Skills sind einzelne Bibliotheksfunktionen**, während **Plugins fertige Pakete (npm-Module)** sind. Wenn Sie nur eine kurze Anleitung für Ihr eigenes Projekt benötigen, reicht ein gewöhnlicher Skill aus. Wenn Sie dem Modell jedoch Tools zur Interaktion mit GitHub, Slack oder Figma zusammen mit vorgefertigten Nutzungsszenarien bereitstellen möchten – wählen Sie ein Plugin.

---

## 2. Anatomie eines Plugins: Skills, MCP-Server, Konfigurationen und Hooks

Ein Plugin in Codex ist nicht einfach ein großer System-Prompt. Es ist eine strukturierte Verzeichnisstruktur oder ein Archiv, das ein deklaratives Manifest sowie alle erforderlichen ausführbaren Artefakte enthält.

```text
my-awesome-plugin/
├── .codex-plugin/
│   └── plugin.json            # Обов'язковий маніфест плагіна
├── skills/
│   ├── code-review/
│   │   └── SKILL.md           # Перший вбудований скіл
│   └── perf-audit/
│       └── SKILL.md           # Другий вбудований скіл
├── mcp/
│   └── server-config.json     # Конфігурація підключення MCP-сервера
└── README.md                  # Документація для розробника
```

### Bestandteile eines modernen Plugins

1. **Manifest (`.codex-plugin/plugin.json`):** Die zentrale Konfigurationsdatei, die den eindeutigen Bezeichner des Plugins, seine Version, den Autor, Abhängigkeiten und Einstiegspunkte definiert.
2. **Skill-Sammlung (`skills/`):** Ein oder mehrere Verzeichnisse mit `SKILL.md`-Dateien, die Codex spezialisierte Ansätze für die Codebasis beibringen.
3. **MCP-Server (Model Context Protocol):** Ausführbare Server oder Adapter, die dem Agent neue Tools bereitstellen – beispielsweise die Möglichkeit, Pull Requests auf GitHub zu lesen, Tickets in Linear zu erstellen oder Design-Mockups aus Figma hochzuladen.
4. **Lifecycle-Hooks:** Skripte oder Befehle, die automatisch bei bestimmten Ereignissen innerhalb einer Session ausgeführt werden (z. B. Linter-Prüfung vor dem 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]
> Im Gegensatz zu gewöhnlichen Prompts können Plugins die unmittelbaren technischen Fähigkeiten des Agents erweitern (Tooling Capability). Ohne ein Plugin mit MCP-Server denkt der Agent nur über die Arbeit mit GitHub nach; mit einem verbundenen Plugin erhält er native Befehle zum Aufruf der GitHub API.

---

## 3. Was sind Marketplaces: Kataloge für Erweiterungen und Distributionsquellen

Für die zentralisierte Suche, Überprüfung und Verteilung von Plugins nutzt Codex das Konzept der **Marketplaces** (Erweiterungskataloge).

Ein Marketplace ist ein Register oder Repository, das eine Liste verfügbarer Plugins, deren Metadaten und Quelladressen zum Download enthält. Anstatt Archive von unsicheren Websites manuell herunterzuladen, verbindet der Entwickler einen geprüften Marketplace und installiert benötigte Pakete anhand ihrer kurzen Bezeichner.

```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
```

### Typen unterstützter Marketplaces

- **Offizieller öffentlicher Katalog:** Das eingebaute Register, das allen Codex-Benutzern standardmäßig zur Verfügung steht. Enthält verifizierte Plugins für populäre Dienste (Figma, Notion, Google Workspace, GitHub).
- **Community-Git-Repositories:** Jedes öffentliche oder private Repository auf GitHub oder GitLab, das gemäß der Marketplace-Spezifikation strukturiert ist.
- **Interne Unternehmensregister:** Firmenkataloge, in denen geschlossene Plugins für die Arbeit mit internen Microservices, VPNs und Compliance-Systemen gespeichert werden.
- **Lokale Entwicklungskataloge:** Gewöhnliche lokale Verzeichnisse auf Ihrem Computer, die für die Entwicklung und das Testen neuer Plugins vor ihrer Veröffentlichung verwendet werden.

---

## 4. Arbeit über die grafische Oberfläche: Der `/plugins`-Befehl und Verwaltung

Für die meisten alltäglichen Interaktionsszenarien muss der Entwickler keine langen Terminalbefehle verwenden – Codex bietet einen komfortablen eingebauten grafischen Plugin-Browser.

### Aufruf des grafischen Katalogs

Um die Plugin-Verwaltungsoberfläche zu öffnen, geben Sie in der Eingabezeile der aktiven Codex-Session den Slash-Befehl ein:

```bash
/plugins
```

Nach der Eingabe des Befehls erscheint ein visueller Manager auf dem Bildschirm, in dem Sie Folgendes tun können:
- **Installierte Plugins anzeigen:** Eine Liste aller im System aktiven Erweiterungen und ihres aktuellen Status sehen.
- **Neue Erweiterungen suchen:** Die Suchleiste nutzen, um Plugins nach Namen, Tags oder Kategorien (Development, DevOps, Analytics, Design) zu finden.
- **Zwischen Marketplaces wechseln:** Verfügbare Plugins nach konkreten verbundenen Katalogen filtern.
- **Aktivität steuern:** Plugins per Klick aktivieren (Enable) oder vorübergehend deaktivieren (Disable), ohne sie vollständig zu entfernen.

> [!WARNING]
> **Regel für neue Sessions:** Nach der Installation eines neuen Plugins oder der Aktivierung einer deaktivierten Erweiterung werden dessen Tools und Skills **nur in neu erstellten Arbeits-Sessions** verfügbar. Die aktuelle Session behält ihren ursprünglichen Ausführungszustand bei, daher müssen Sie nach Änderungen an der Plugin-Konfiguration unbedingt einen neuen Dialog öffnen.

---

## 5. Plugin-Verwaltung über die CLI: Auflisten, Installieren und Entfernen

Für Benutzer, die das Terminal bevorzugen, sowie für die Automatisierung der Umgebungseinrichtung in CI/CD oder Docker-Containern bietet Codex einen vollständigen Satz von CLI-Befehlen unter der Untergruppe `codex plugin`.

### Grundlegende Plugin-Operationen

:::tabs
@tab Installierte anzeigen
```bash
# Вивести перелік усіх встановлених на поточній машині плагінів
codex plugin list
```
@tab Verfügbare anzeigen
```bash
# Переглянути список усіх плагінів, доступних у підключених маркетплейсах
codex plugin list --available

# Отримати детальний список у машиночитаному форматі JSON
codex plugin list --available --json
```
@tab Plugin installieren
```bash
# Встановити плагін за унікальним ім'ям
codex plugin add github-toolkit

# Встановити плагін із конкретного підключеного маркетплейсу
codex plugin add dev-suite@company-internal
```
@tab Plugin entfernen
```bash
# Повністю видалити встановлений плагін із системи
codex plugin remove github-toolkit

# Видалити плагін з прив'язкою до конкретного джерела
codex plugin remove dev-suite@company-internal
```
:::

Der Befehl `codex plugin list` gibt den Status jedes Plugins aus: Name, Version, Installationsquelle sowie den Aktivierungs-/Deaktivierungszustand.

---

## 6. Verwaltung von Marketplaces: Hinzufügen von Repositories, Aktualisieren und Entfernen

Um die Liste der verfügbaren Plugins zu erweitern, kann der Entwickler externe Quellen über die Unterbefehle `codex plugin marketplace` verbinden.

### Verbundene Kataloge anzeigen

```bash
codex plugin marketplace list
```

Der Befehl zeigt den Namen jedes Katalogs, den Quelltyp (git oder local) und die aktuelle URI an.

### Neue Quellen hinzufügen

Codex unterstützt mehrere Formate für die Verlinkung auf einen Marketplace, abhängig von der Umgebung und dem Zugriffsprotokoll:

:::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 Lokales Verzeichnis
```bash
# Підключення локальної папки для тестування власного маркетплейсу
codex plugin marketplace add ./my-local-marketplace
```
:::

### Aktualisieren und Entfernen von Marketplaces

```bash
# Оновити метадані конкретного маркетплейсу (завантажити свіжі версії плагінів)
codex plugin marketplace upgrade community-plugins

# Оновити всі підключені Git-маркетплейси одночасно
codex plugin marketplace upgrade

# Видалити маркетплейс зі списку джерел
codex plugin marketplace remove community-plugins
```

> [!TIP]
> Wenn ein Plugin keine Updates findet oder ein gerade von Kollegen veröffentlichtes Paket nicht in Ihrer Liste angezeigt wird, führen Sie `codex plugin marketplace upgrade` aus, um den lokalen Index der Kataloge zu aktualisieren.

---

## 7. Plugins mit MCP-Servern: Authentifizierung, Zugriffsrechte und Sicherheit

Wenn ein installiertes Plugin einen **MCP-Server** enthält, erhält es die Fähigkeit, mit externen Systemen zu interagieren (Datenbanken, Cloud-Speicher, API-Endpunkte). Dies verwandelt Codex von einem passiven Code-Generator in einen aktiven Task-Ausführer.

```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 успішно створено!"
```

### Besonderheiten der Authentifizierung externer Dienste

1. **OAuth-Authentifizierung:** Die meisten Cloud-Dienste (Google Drive, Slack, GitHub) öffnen beim ersten Zugriff ein Browserfenster mit der Aufforderung, den Zugriff auf Ihr Konto zu bestätigen.
2. **API-Tokens in der Umgebung:** Für Datenbankdienste oder interne Server (PostgreSQL, Supabase) werden Zugriffstoken aus Umgebungsvariablen (`.env`) oder der globalen Codex-Konfiguration gelesen.
3. **Granulare Berechtigungen (Permissions):** Codex fragt immer die Bestätigung des Benutzers ab, bevor potenziell destruktive Aktionen ausgeführt werden (Löschen von Datensätzen in der DB, Senden von Nachrichten, Schließen von Pull Requests).

> [!WARNING]
> **Sicherheit von MCP-Servern:** Installieren Sie niemals Plugins von fragwürdigen Marketplaces, wenn diese MCP-Server enthalten. Ein schädlicher MCP-Server könnte auf Ihre lokalen Dateien zugreifen oder vertrauliche API-Keys an fremde Server senden. Analysieren Sie stets den Quellcode vor der Installation.

---

## 8. Lebenszyklus: Deaktivieren, Entfernen eines Plugins oder Trennen eines Katalogs

Anfänger verwechseln oft drei verschiedene Ebenen der Deaktivierung von Erweiterungen: temporäres Deaktivieren, vollständiges Entfernen eines Plugins und Trennen eines Marketplaces.

| Aktion | Befehl | Was passiert mit den Dateien | Auswirkungen auf Sessions |
| :--- | :--- | :--- | :--- |
| **Plugin deaktivieren (Disable)** | Über `/plugins` Schalter | Plugin bleibt auf der Festplatte, Konfiguration bleibt erhalten | Skills und MCP-Tools werden in neuen Sessions inaktiv |
| **Plugin entfernen (Uninstall)** | `codex plugin remove <name>` | Alle Plugin-Dateien werden aus der lokalen Umgebung gelöscht | Vollständige Bereinigung; für erneute Nutzung ist ein neuer Download erforderlich |
| **Marketplace entfernen** | `codex plugin marketplace remove <name>` | Nur die Quelle wird entfernt; bereits installierte Plugins bleiben bestehen | Keine Updates oder Installation neuer Plugins aus diesem Katalog möglich |

### Empfehlungen zur Auswahl der Aktion

- Wenn ein Plugin Konflikte verursacht oder Sie die schweren MCP-Tools vorübergehend nicht benötigen – **deaktivieren Sie es (Disable)** über `/plugins`.
- Wenn Sie ein Projekt abgeschlossen haben und nicht mehr planen, mit dieser Technologie zu arbeiten – **entfernen Sie das Plugin vollständig (Remove)** über die CLI.
- Wenn das Repository eines Drittanbieters inaktiv oder veraltet ist – **entfernen Sie den Marketplace (Marketplace Remove)**.

---

## 9. Entwicklung eines eigenen Plugins: Manifest, Packen von Skills und lokales Testen

Die Erstellung eines eigenen Plugins ist der beste Weg, um Workflows in Ihrem Team zu standardisieren und ein einheitliches Niveau der Codegenerierung für alle Ingenieure sicherzustellen.

### Schrittweiser Workflow zur Plugin-Erstellung

#### Schritt 1. Vorbereitung des Arbeitsbereichs
Erstellen Sie ein sauberes Verzeichnis für Ihr zukünftiges Plugin:

```bash
mkdir -p my-team-plugin/.codex-plugin
mkdir -p my-team-plugin/skills/architecture-review
```

#### Schritt 2. Erstellen des Manifests `plugin.json`
Innerhalb des Verzeichnisses `.codex-plugin/` erstellen Sie die Datei `plugin.json`:

```json
{
  "name": "team-architecture-plugin",
  "version": "1.0.0",
  "description": "Фірмові правила проєктування сервісів та аудит чистої архітектури",
  "author": "Architecture Guild",
  "skills": [
    "./skills/architecture-review"
  ]
}
```

#### Schritt 3. Hinzufügen von Anweisungen in `SKILL.md`
Erstellen Sie die Datei `my-team-plugin/skills/architecture-review/SKILL.md`:

```markdown
---
name: architecture-review
description: Перевірка відповідності модулів принципам Domain-Driven Design (DDD)
---

При аналізі нових архітектурних модулів перевіряй такі правила:
1. Бізнес-логіка не повинна напряму імпортувати ORM або базу даних.
2. Усі зовнішні інтерфейси визначаються як порти (інтерфейси) у внутрішньому шарі.
3. Кожна мутація даних повинна супроводжуватися викликом domain events.
```

#### Schritt 4. Erstellen eines Test-Marketplaces und Installation
Um die Funktion lokal zu prüfen, ohne auf GitHub zu veröffentlichen, erstellen Sie den Ordner für den lokalen Marketplace `local-market/` und fügen Sie dort Ihr Plugin hinzu. Führen Sie anschließend aus:

```bash
# Підключаємо локальну папку як джерело маркетплейсу
codex plugin marketplace add ./local-market

# Встановлюємо наш щойно створений плагін
codex plugin add team-architecture-plugin

# Перевіряємо статус встановлення
codex plugin list
```

Starten Sie nun eine neue Session in Codex und testen Sie die Funktionalität des verbundenen Plugins an einer realen Aufgabe aus der Code-Architektur.

---

## 10. Zusammenfassende Cheatsheet für Befehle und Sicherheits-Checkliste vor der Installation

Speichern Sie dieses kompakte Handbuch für die schnelle Navigation im Terminal und für die tägliche Arbeit.

### Schnelles CLI-Befehls-Handbuch

```bash
# ─── Робота з плагінами ───────────────────────────────────────────
codex plugin list                         # Список встановлених плагінів
codex plugin list --available             # Список доступних плагінів у каталогах
codex plugin add <plugin-name>            # Встановити плагін
codex plugin add <plugin@marketplace>     # Встановити з конкретного джерела
codex plugin remove <plugin-name>         # Видалити плагін

# ─── Робота з Marketplaces ────────────────────────────────────────
codex plugin marketplace list             # Список підключених каталогів
codex plugin marketplace add <source>     # Додати маркетплейс (GitHub / URL / локальний)
codex plugin marketplace upgrade <name>   # Оновити конкретний каталог
codex plugin marketplace upgrade          # Оновити всі підключені каталоги
codex plugin marketplace remove <name>    # Видалити каталог зі списку

# ─── Графічний інтерфейс ─────────────────────────────────────────
/plugins                                  # Відкрити інтерактивний браузер плагінів
```

### Sicherheits-Checkliste vor der Installation eines Drittanbieter-Plugins

- [ ] **Reputation der Quelle**
- [ ] **Analyse des Quellcodes**
- [ ] **Überprüfung der Berechtigungen**
- [ ] **Test in isolierter Umgebung**