grahama1970/créateur-de-plugin

Créateur de Plugin

Démarrage rapide

1. Exécutez le script d'échafaudage :

# Les noms de plugins sont normalisés en minuscules avec tirets et doivent faire <= 64 caractères.
# Le dossier généré et le nom dans plugin.json sont toujours identiques.
# Exécutez depuis la racine de la compétence (le répertoire contenant ce `SKILL.md`).
# Par défaut, crée dans `~/plugins/<nom-du-plugin>`.
python3 scripts/create_basic_plugin.py <nom-du-plugin>

2. Modifiez <chemin-du-plugin>/.codex-plugin/plugin.json lorsque la demande fournit des métadonnées spécifiques. L'échafaudage commence avec des valeurs par défaut valides et ne doit pas contenir d'espaces réservés [TODO: ...].

3. Générez ou mettez à jour l'entrée de marché personnel lorsque le plugin doit apparaître dans l'interface de classement de Codex :

# Les entrées de marché personnel se trouvent par défaut dans `~/.agents/plugins/marketplace.json`.
python3 scripts/create_basic_plugin.py mon-plugin --with-marketplace

Ne spécifiez --marketplace-name <nom> que lorsque le nom de marché par défaut personal est déjà pris ou installé et que vous devez initialiser un nouveau fichier de marché différent :

python3 scripts/create_basic_plugin.py mon-plugin \
  --with-marketplace \
  --marketplace-name equipe-locale

N'utilisez un marché de dépôt/équipe que lorsque l'utilisateur demande explicitement cette destination :

python3 scripts/create_basic_plugin.py mon-plugin \
  --path <racine-du-depot>/plugins \
  --marketplace-path <racine-du-depot>/.agents/plugins/marketplace.json \
  --with-marketplace

Lorsque l'utilisateur spécifie un chemin de marché, assurez-vous que ce marché est réellement installé avant de dire à l'utilisateur de le réinstaller. Le fichier de marché personnel par défaut à ~/.agents/plugins/marketplace.json est découvert implicitement, mais les autres chemins de marché ne le sont pas. Sous Windows, utilisez le chemin équivalent sous le profil utilisateur.

4. Générez/ajustez les dossiers compagnons optionnels selon les besoins :

python3 scripts/create_basic_plugin.py mon-plugin \
  --path <répertoire-parent-du-plugin> \
  --marketplace-path <chemin-du-fichier-marketplace-json> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<répertoire-parent-du-plugin> est le répertoire où le dossier du plugin <nom-du-plugin> sera créé (par exemple ~/plugins).

5. Avant de remettre un plugin généré, exécutez :

python3 scripts/validate_plugin.py <chemin-du-plugin>

Pour les mises à jour d'un plugin local existant pendant le développement, conservez le flux d'échafaudage tel quel et utilisez la référence au lieu de modifier manuellement les fichiers de marché :

python3 scripts/update_plugin_cachebuster.py <chemin-du-plugin>

Préférez l'invalidation de cache par défaut du helper, sauf si l'utilisateur demande explicitement une valeur spécifique. Consultez references/installing-and-updating.md pour le flux attendu d'invalidation de cache et de réinstallation lors de l'itération sur un plugin local existant.

Ce que crée cette compétence

• Les échafaudages par défaut avec marché utilisent le fichier de marché personnel à ~/.agents/plugins/marketplace.json, les plugins étant généralement stockés dans ~/plugins/<nom-du-plugin>/.
• Crée la racine du plugin à /<répertoire-parent-du-plugin>/<nom-du-plugin>/.
• Crée toujours /<répertoire-parent-du-plugin>/<nom-du-plugin>/.codex-plugin/plugin.json.
• Remplit le manifeste avec la forme de schéma validée que le pipeline d'ingestion accepte.
• Crée ou met à jour ~/.agents/plugins/marketplace.json lorsque --with-marketplace est défini.
  • Si le fichier de marché n'existe pas encore, initialise une racine de marché personnel avant d'ajouter la première entrée de plugin.
• <nom-du-plugin> est normalisé selon les règles de dénomination du créateur de compétence :
  • Mon Plugin → mon-plugin
  • Mon--Plugin → mon-plugin
  • les underscores, espaces et ponctuation sont convertis en -
  • le résultat est en minuscules avec des tirets, les tirets consécutifs étant réduits
• Prend en charge la création optionnelle de :
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

Flux de travail du marché

• La création de marché personnel par défaut se fait dans ~/.agents/plugins/marketplace.json. Ici, "marché personnel" signifie le marché dont le fichier se trouve à ce chemin.
• La création de marché de dépôt/équipe est optionnelle via --path et --marketplace-path, uniquement lorsque l'utilisateur le demande spécifiquement.
• --marketplace-name est un chemin d'exception. Utilisez-le uniquement lorsque le nom de marché personal par défaut est déjà pris et que vous devez initialiser un nouveau fichier de marché différent.
• N'utilisez pas --marketplace-name pour renommer un fichier de marché existant sur place. Si le fichier existe déjà, son name de premier niveau doit déjà correspondre.
• Si l'utilisateur spécifie un chemin de marché différent, traitez ce marché comme nécessitant une installation explicite via codex plugin marketplace add.
• Préférez scripts/read_marketplace_name.py lorsque vous avez besoin du nom du marché à partir de n'importe quel fichier marketplace.json. Sans argument, il lit le marché personnel par défaut ; avec un chemin explicite, il fonctionne également pour les marchés de dépôt/équipe.
• Dans les deux emplacements, le chemin source généré reste ./plugins/<nom-du-plugin>.
• Les métadonnées racines du marché prennent en charge le name de premier niveau plus un interface.displayName optionnel.
• Traitez l'ordre des plugins dans plugins[] comme l'ordre d'affichage dans Codex. Ajoutez les nouvelles entrées à la fin, sauf si un utilisateur demande explicitement de réorganiser la liste.
• displayName appartient à l'objet interface du marché, pas aux entrées individuelles plugins[].
• Chaque entrée de marché générée doit inclure tous les éléments suivants :
  • policy.installation
  • policy.authentication
  • category
• Définissez par défaut les nouvelles entrées à :
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• Remplacez les valeurs par défaut uniquement lorsque l'utilisateur spécifie explicitement une autre valeur autorisée.
• Valeurs autorisées pour policy.installation :
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• Valeurs autorisées pour policy.authentication :
  • ON_INSTALL
  • ON_USE
• Traitez policy.products comme un remplacement. Omettez-le sauf si l'utilisateur demande explicitement un contrôle par produit.
• La forme de l'entrée de plugin générée est :

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

• Utilisez --force uniquement lorsque vous remplacez intentionnellement une entrée de marché existante pour le même nom de plugin.

• Si le fichier de marché cible n'existe pas encore, créez-le avec le "name" de premier niveau, un objet "interface" contenant "displayName", et un tableau plugins, puis ajoutez la nouvelle entrée.

• Pour un tout nouveau fichier de marché, l'objet racine doit ressembler à :

{
  "name": "personal",
  "interface": {
    "displayName": "Personnel"
  },
  "plugins": [
    {
      "name": "nom-du-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/nom-du-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivité"
    }
  ]
}

Comportement requis

• Le nom du dossier externe et "name" dans plugin.json sont toujours le même nom de plugin normalisé.
• Ne supprimez pas la structure obligatoire ; conservez .codex-plugin/plugin.json présent.
• Ne laissez pas d'espaces réservés [TODO: ...] dans les manifestes de plugin.
• Gardez apps et mcpServers hors de plugin.json sauf si leurs fichiers compagnons sont réellement créés.
• Omettez les champs de manifeste de plugin non pris en charge que la validation rejette, y compris hooks.
• Si vous créez des fichiers dans un chemin de plugin existant, utilisez --force uniquement lorsque l'écrasement est intentionnel.
• Préservez tout interface.displayName existant du marché.
• Lors de la génération d'entrées de marché, écrivez toujours policy.installation, policy.authentication et category même si leurs valeurs sont les valeurs par défaut.
• Ajoutez policy.products uniquement lorsque l'utilisateur demande explicitement ce remplacement.
• Gardez source.path du marché relatif à la racine du marché sélectionné comme ./plugins/<nom-du-plugin>.
• Utilisez --marketplace-name uniquement lors de la création d'un nouveau fichier de marché dont le nom ne doit pas être personal car ce nom est déjà pris ou installé ailleurs.
• Si Codex a besoin d'approbation pour écrire le fichier de marché, demandez cette approbation avant de procéder. Si l'utilisateur préfère exécuter l'écriture lui-même, fournissez la commande d'échafaudage exacte et continuez ensuite à partir de la validation ou des modifications ultérieures du plugin au lieu de laisser le flux de travail vague.
• Pour les mises à jour d'un plugin local existant pendant le développement, ne modifiez pas manuellement la configuration du marché ou marketplace.json. Utilisez le flux de mise à jour documenté dans references/installing-and-updating.md et scripts/update_plugin_cachebuster.py.
• Ne dites pas à l'utilisateur d'exécuter codex plugin marketplace add pour le flux de marché personnel par défaut. Cette commande est destinée à la configuration explicite de marché non par défaut, pas au chemin standard ~/.agents/plugins/marketplace.json.
• Si l'utilisateur a fourni un --marketplace-path non par défaut, assurez-vous que ce marché est installé avant de donner des instructions de réinstallation. Utilisez codex plugin marketplace add <chemin-vers-la-racine-du-marche> lorsque ce marché explicite n'a pas encore été configuré.
• Lorsque le flux de travail a créé ou mis à jour un plugin adossé à un marché, terminez la réponse finale destinée à l'utilisateur par un bref renvoi vers l'application Codex. Dites Pour voir ceci dans l'application Codex : et écrivez Voir <nom normalisé du plugin> et Partager <nom normalisé du plugin> sous forme de liens Markdown, pas d'URL brutes ou de spans de code.
• Le lien profond Voir utilise codex://plugins/<nom normalisé du plugin>?marketplacePath=<chemin absolu du marketplace.json>. Le lien profond Partager utilise la même URL avec &mode=share.
• Remplacez les espaces réservés par le vrai nom de plugin normalisé et le chemin absolu du marketplace.json du plugin échafaudé. Encodez l'URL du segment de chemin et la valeur de la requête si nécessaire.
• N'ajoutez pas les paramètres de requête pluginName ou hostId à ces liens profonds. Codex les dérive après que l'utilisateur a cliqué sur le lien.
• N'émettez pas les liens Voir <nom normalisé du plugin> ou Partager <nom normalisé du plugin> lorsqu'aucune entrée de marché n'a été créée ou mise à jour.

Référence à l'échantillon de spécification exact

Pour l'échantillon JSON canonique exact pour les manifestes de plugin et les entrées de marché, utilisez :

• references/plugin-json-spec.md
• references/installing-and-updating.md pour les conseils de mise à jour/réinstallation lors de l'itération sur un plugin local existant, ainsi que le comportement de reprise après réinstallation

Validation

Après avoir modifié SKILL.md, exécutez :

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

Avant de remettre un plugin généré, exécutez :

python3 scripts/validate_plugin.py <chemin-du-plugin>