grahama1970/plugin-creator

Plugin Creator

Kurzanleitung

1. Führen Sie das Gerüstskript aus:

# Plugin-Namen werden in Kleinbuchstaben mit Bindestrichen normalisiert und müssen <= 64 Zeichen lang sein.
# Der generierte Ordner- und plugin.json-Name ist immer identisch.
# Vom Skill-Stammverzeichnis aus ausführen (dem Verzeichnis, das diese `SKILL.md` enthält).
# Standardmäßig wird in `~/plugins/<plugin-name>` erstellt.
python3 scripts/create_basic_plugin.py <plugin-name>

2. Bearbeiten Sie <plugin-pfad>/.codex-plugin/plugin.json, wenn die Anfrage spezifische Metadaten liefert. Das Gerüst beginnt mit gültigen Standardwerten und darf keine [TODO: ...]-Platzhalter enthalten.

3. Generieren oder aktualisieren Sie den persönlichen Marktplatzeintrag, wenn das Plugin in der Codex-UI-Reihenfolge erscheinen soll:

# Persönliche Marktplatzeinträge werden standardmäßig in `~/.agents/plugins/marketplace.json` abgelegt.
python3 scripts/create_basic_plugin.py mein-plugin --with-marketplace

Geben Sie --marketplace-name <name> nur an, wenn der Standard-Marktplatzname personal bereits belegt oder installiert ist und Sie eine andere neue Marktplatzdatei anlegen müssen:

python3 scripts/create_basic_plugin.py mein-plugin \
  --with-marketplace \
  --marketplace-name team-lokal

Verwenden Sie einen Repo/Team-Marktplatz nur, wenn der Benutzer ausdrücklich nach diesem Ziel fragt:

python3 scripts/create_basic_plugin.py mein-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

Wenn der Benutzer einen Marktplatzpfad angibt, stellen Sie sicher, dass dieser Marktplatz tatsächlich installiert ist, bevor Sie dem Benutzer sagen, er solle von dort neu installieren. Die Standard-Marktplatzdatei unter ~/.agents/plugins/marketplace.json wird implizit erkannt, andere Marktplatzpfade jedoch nicht. Unter Windows verwenden Sie den entsprechenden Pfad im Benutzerprofil.

4. Generieren/Anpassen optionaler Begleiterordner nach Bedarf:

python3 scripts/create_basic_plugin.py mein-plugin \
  --path <übergeordnetes-plugin-verzeichnis> \
  --marketplace-path <marktplatz-json-pfad> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<übergeordnetes-plugin-verzeichnis> ist das Verzeichnis, in dem der Plugin-Ordner <plugin-name> erstellt wird (z. B. ~/plugins).

5. Führen Sie vor der Rückgabe eines generierten Plugins Folgendes aus:

python3 scripts/validate_plugin.py <plugin-pfad>

Für Aktualisierungen eines bestehenden lokalen Plugins während der Entwicklung behalten Sie den Gerüstablauf bei und verwenden Sie die Referenz anstatt Marktplatzdateien von Hand zu bearbeiten:

python3 scripts/update_plugin_cachebuster.py <plugin-pfad>

Bevorzugen Sie den standardmäßigen Cachebuster des Hilfsprogramms, es sei denn, der Benutzer fragt ausdrücklich nach einer bestimmten Überschreibung. Siehe references/installing-and-updating.md für den erwarteten Cachebuster- und Neuinstallationsablauf beim Iterieren über ein bestehendes lokales Plugin.

Was dieser Skill erstellt

• Standardmäßige marktplatzgestützte Gerüste verwenden die persönliche Marktplatzdatei unter ~/.agents/plugins/marketplace.json, wobei Plugins normalerweise in ~/plugins/<plugin-name>/ gespeichert werden.
• Erstellt Plugin-Stammverzeichnis unter /<übergeordnetes-plugin-verzeichnis>/<plugin-name>/.
• Erstellt immer /<übergeordnetes-plugin-verzeichnis>/<plugin-name>/.codex-plugin/plugin.json.
• Befüllt das Manifest mit der validierten Schemaform, die der Aufnahmepfad akzeptiert.
• Erstellt oder aktualisiert ~/.agents/plugins/marketplace.json, wenn --with-marketplace gesetzt ist.
  • Wenn die Marktplatzdatei noch nicht existiert, initialisieren Sie ein persönliches Marktplatzstammverzeichnis, bevor Sie den ersten Plugin-Eintrag hinzufügen.
• <plugin-name> wird mit den Namenskonventionen von skill-creator normalisiert:
  • Mein Plugin → mein-plugin
  • Mein--Plugin → mein-plugin
  • Unterstriche, Leerzeichen und Satzzeichen werden in - umgewandelt
  • Ergebnis ist in Kleinbuchstaben, durch Bindestriche getrennt, mit zusammengezogenen aufeinanderfolgenden Bindestrichen
• Unterstützt optionale Erstellung von:
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

Marktplatzablauf

• Die Erstellung persönlicher Marktplätze erfolgt standardmäßig unter ~/.agents/plugins/marketplace.json. Hier bedeutet "persönlicher Marktplatz" den Marktplatz, dessen Datei sich an diesem Pfad befindet.
• Die Erstellung von Repo/Team-Marktplätzen erfolgt nur über beide --path und --marketplace-path opt-in, wenn der Benutzer dies ausdrücklich wünscht.
• --marketplace-name ist ein Ausnahmepfad. Verwenden Sie es nur, wenn der Standard-Marktplatzname personal bereits belegt ist und Sie eine andere neue Marktplatzdatei initialisieren müssen.
• Verwenden Sie --marketplace-name nicht, um eine bestehende Marktplatzdatei umzubenennen. Wenn die Datei bereits existiert, muss ihr oberster name bereits übereinstimmen.
• Wenn der Benutzer einen anderen Marktplatzpfad angibt, behandeln Sie diesen Marktplatz so, dass er eine explizite Installation via codex plugin marketplace add benötigt.
• Bevorzugen Sie scripts/read_marketplace_name.py, wenn Sie den Marktplatznamen aus einer beliebigen marketplace.json-Datei benötigen. Ohne Argument liest es den Standard-Personalmarktplatz; mit einem expliziten Pfad funktioniert es auch für Repo/Team-Marktplätze.
• In beiden Pfaden bleibt der generierte Quellpfad ./plugins/<plugin-name>.
• Die Metadaten des Marktplatzstammverzeichnisses unterstützen den obersten name plus optional interface.displayName.
• Behandeln Sie die Plugin-Reihenfolge in plugins[] als Render-Reihenfolge in Codex. Fügen Sie neue Einträge an, es sei denn, ein Benutzer bittet ausdrücklich um eine Neuordnung der Liste.
• displayName gehört innerhalb des Marktplatz-interface-Objekts, nicht in einzelne plugins[]-Einträge.
• Jeder generierte Marktplatzeintrag muss alle der folgenden Felder enthalten:
  • policy.installation
  • policy.authentication
  • category
• Standardmäßige neue Einträge:
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• Überschreiben Sie die Standardwerte nur, wenn der Benutzer ausdrücklich einen anderen zulässigen Wert angibt.
• Zulässige Werte für policy.installation:
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• Zulässige Werte für policy.authentication:
  • ON_INSTALL
  • ON_USE
• Behandeln Sie policy.products als eine Überschreibung. Lassen Sie es weg, es sei denn, der Benutzer fordert ausdrücklich eine Produktsteuerung an.
• Die Form des generierten Plugin-Eintrags ist:

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

• Verwenden Sie --force nur, wenn Sie absichtlich einen vorhandenen Marktplatzeintrag für denselben Plugin-Namen ersetzen.

• Wenn die Zielmarktplatzdatei noch nicht existiert, erstellen Sie sie mit einem obersten "name", einem "interface"-Objekt, das "displayName" enthält, und einem plugins-Array, und fügen Sie dann den neuen Eintrag hinzu.

• Für eine brandneue Marktplatzdatei sollte das Stammobjekt wie folgt aussehen:

{
  "name": "personal",
  "interface": {
    "displayName": "Persönlich"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Erforderliches Verhalten

• Der äußere Ordnernamen und der "name" in plugin.json sind immer der gleiche normalisierte Plugin-Name.
• Entfernen Sie nicht die erforderliche Struktur; behalten Sie .codex-plugin/plugin.json bei.
• Hinterlassen Sie keine [TODO: ...]-Platzhalter in Plugin-Manifesten.
• Lassen Sie apps und mcpServers aus plugin.json heraus, es sei denn, ihre Begleitdateien werden tatsächlich erstellt.
• Lassen Sie nicht unterstützte Plugin-Manifestfelder weg, die die Validierung ablehnt, einschließlich hooks.
• Wenn Sie Dateien innerhalb eines bestehenden Plugin-Pfads erstellen, verwenden Sie --force nur, wenn das Überschreiben beabsichtigt ist.
• Bewahren Sie jegliches vorhandenes interface.displayName des Marktplatzes.
• Schreiben Sie beim Generieren von Marktplatzeinträgen immer policy.installation, policy.authentication und category, auch wenn ihre Werte Standardwerte sind.
• Fügen Sie policy.products nur hinzu, wenn der Benutzer ausdrücklich nach dieser Überschreibung fragt.
• Halten Sie den source.path des Marktplatzes relativ zum ausgewählten Marktplatzstammverzeichnis als ./plugins/<plugin-name>.
• Verwenden Sie --marketplace-name nur, wenn Sie eine neue Marktplatzdatei erstellen, deren Name nicht personal sein soll, weil dieser Name bereits belegt oder anderweitig installiert ist.
• Wenn Codex eine Genehmigung zum Schreiben der Marktplatzdatei benötigt, holen Sie diese Genehmigung ein, bevor Sie fortfahren. Wenn der Benutzer es vorzieht, das Schreiben selbst auszuführen, geben Sie den genauen Gerüstbefehl an und fahren Sie dann mit der Validierung oder nachfolgenden Plugin-Bearbeitungen fort, anstatt den Arbeitsablauf vage zu halten.
• Bearbeiten Sie für Aktualisierungen eines bestehenden lokalen Plugins während der Entwicklung nicht von Hand die Marktplatzkonfiguration oder marketplace.json. Verwenden Sie den in references/installing-and-updating.md und scripts/update_plugin_cachebuster.py dokumentierten Aktualisierungsablauf.
• Weisen Sie den Benutzer nicht an, codex plugin marketplace add für den standardmäßigen persönlichen Marktplatzablauf auszuführen. Dieser Befehl ist für explizite, nicht standardmäßige Marktplatzkonfigurationen gedacht, nicht für den standardmäßigen Pfad ~/.agents/plugins/marketplace.json.
• Wenn der Benutzer einen nicht standardmäßigen --marketplace-path angegeben hat, stellen Sie sicher, dass dieser Marktplatz installiert ist, bevor Sie Neuinstallationsanweisungen geben. Verwenden Sie codex plugin marketplace add <pfad-zum-marktplatz-stammverzeichnis>, wenn dieser explizite Marktplatz noch nicht konfiguriert wurde.
• Wenn der Arbeitsablauf ein marktplatzgestütztes Plugin erstellt oder aktualisiert hat, beenden Sie die abschließende benutzerseitige Antwort mit einer kurzen Codex-App-Übergabe. Sagen Sie Um dies in der Codex-App anzuzeigen: und schreiben Sie View <normalisierter Plugin-Name> und Share <normalisierter Plugin-Name> als Markdown-Links, nicht als rohe URLs oder Code-Spans.
• Der View-Deeplink verwendet codex://plugins/<normalisierter Plugin-Name>?marketplacePath=<absoluter marketplace.json-pfad>. Der Share-Deeplink verwendet dieselbe URL mit &mode=share.
• Ersetzen Sie die Platzhalter durch den tatsächlichen normalisierten Plugin-Namen und den absoluten marketplace.json-Pfad aus dem Gerüst des Plugins. URL-kodieren Sie das Pfadsegment und den Abfragewert bei Bedarf.
• Fügen Sie diesen Deeplinks keine Abfrageparameter pluginName oder hostId hinzu. Codex leitet beide ab, nachdem der Benutzer auf den Link geklickt hat.
• Geben Sie die Links View <normalisierter Plugin-Name> oder Share <normalisierter Plugin-Name> nicht aus, wenn kein Marktplatzeintrag erstellt oder aktualisiert wurde.

Referenz zum genauen Spezifikationsbeispiel

Für das genaue kanonische Beispiel-JSON sowohl für Plugin-Manifeste als auch für Marktplatzeinträge verwenden Sie:

• references/plugin-json-spec.md
• references/installing-and-updating.md für Hinweise zur Aktualisierung/Neuinstallation beim Iterieren über ein bestehendes lokales Plugin, plus das Aufnahmeverhalten für neue Threads nach der Neuinstallation

Validierung

Nach der Bearbeitung von SKILL.md führen Sie Folgendes aus:

python3 ../skill-creator/scripts/quick_validate.py .

Vor der Rückgabe eines generierten Plugins führen Sie Folgendes aus:

python3 scripts/validate_plugin.py <plugin-pfad>