better-plugin-gen

Better Plugin Generator (better-plugin-gen)

Ce skill aide à créer un plugin : un dossier regroupant plusieurs composants (skill, agent, hook, serveur MCP) à installer dans un agent de codage en une seule commande. Il prend en charge trois hôtes (outils d'agent chargeant des plugins) : Claude Code, Codex, Antigravity. Chaque hôte possède son propre manifeste ; le skill utilise un dossier commun skills/ et génère le manifeste pour chaque hôte sélectionné.

Tous les chemins (template.md, references/, examples/, scripts/) ci-dessous sont relatifs au dossier contenant ce fichier SKILL.md.

---

1. Principes fondamentaux

1. Demander d'abord, générer ensuite. Toute option est demandée à l'utilisateur via un outil de question structurée si la session le permet ; sinon, les options sont listées avec des numéros, la recommandation est indiquée, et le skill attend une réponse. Avant chaque question, un court résumé explique ce que le plugin fera, ce qui est demandé et pourquoi. Le skill ne complète jamais un point ambigu avant de générer un fichier.
2. Ne pas deviner les spécificités de l'hôte. L'emplacement des fichiers, le format des manifestes et des MCP sont définis dans references/hosts.md. Les points marqués « non vérifié » doivent être signalés à l'utilisateur.
3. La logique principale est dans le skill. Le skill est le seul composant exécutable sur les trois hôtes. Les agents, commandes, hooks et LSP ne sont ajoutés que si l'utilisateur en a besoin et que l'hôte les prend en charge.
4. Cadre minimal fonctionnel. Chaque composant généré doit être immédiatement exécutable mais concis. Si le projet contient les skills better-skill-gen ou better-agent-gen, proposez à l'utilisateur de les utiliser pour écrire un skill ou un agent plus détaillé après que le plugin soit fonctionnel.
5. Auto-validation. Le plugin n'est livré que lorsque scripts/validate.sh retourne le code de sortie 0.
6. Aucun effet de bord externe. Le skill écrit uniquement dans le dossier du plugin cible (et dans le fichier marketplace à la racine du dépôt si l'utilisateur choisit cette option). Il n'exécute pas git commit, git push, n'installe pas le plugin, ne modifie pas la configuration de l'hôte de l'utilisateur ; il affiche uniquement les commandes que l'utilisateur doit exécuter lui-même.

---

2. Entrées

• Obligatoire : une description de l'utilité du plugin (une phrase suffit), ou le chemin d'un plugin existant pour ajouter un composant. Cette information est extraite de la demande de l'utilisateur.
• Demander si manquant : l'hôte cible, l'emplacement du dossier, la liste des composants, la présence d'un marketplace, le nom du plugin, l'auteur, la licence.
• Information manquante : demander selon l'étape 2 de la section 3 ; en l'absence de réponse, attendre.

---

3. Procédure

Étape 1 : Déterminer le mode et lire l'état actuel

• Création : l'utilisateur décrit le plugin, pas de dossier existant.
• Ajout de composant / ajout d'hôte : l'utilisateur fournit un chemin contenant .claude-plugin/plugin.json, .codex-plugin/plugin.json ou plugin.json. Lire tous les manifestes, lister les composants existants, exécuter la commande shell bash scripts/validate.sh <dir> pour connaître les erreurs existantes avant de les corriger.
• Création d'un marketplace : l'utilisateur a déjà un plugin, souhaite le publier. Lire le plugin comme ci-dessus, puis passer à l'étape 6.
• Lire references/hosts.md. Si la « Date de vérification » date de plus de 30 jours, ou si le plugin nécessite une fonctionnalité non encore présente dans le fichier : consulter les sources mentionnées à la section 6 de ce fichier sur le web, mettre à jour le fichier et la date de vérification, puis informer l'utilisateur des modifications apportées.

Étape 2 : Interroger l'utilisateur

Résumer ce qui a été compris (à quoi sert le plugin, qui l'utilise, quand il s'exécute), puis poser la première série de questions, en omettant toute question dont la réponse est déjà claire :

Question	Type	Choix (recommandation en premier)
Sur quel hôte le plugin s'exécute-t-il ?	Choix multiple	Claude Code ; Codex ; Antigravity. Recommandation : les trois si le plugin ne contient que des skills et des MCP ; seulement Claude Code si des hooks, LSP ou userConfig sont nécessaires
Où placer le plugin ?	Choix unique	Dépôt dédié, plugin à la racine (./<nom>/) ; dans un dépôt marketplace (plugins/<nom>/) ; dans le projet en cours pour test
Quels composants le plugin contient-il ?	Choix multiple	Skill ; Agent ; Hook ; Serveur MCP ; Commande ; LSP ; userConfig
Créer un marketplace pour publier ?	Choix unique	Oui, pour les hôtes sélectionnés ; Non, test local uniquement

Deuxième série (si nécessaire) : nom du plugin (proposer un nom en kebab-case dérivé de la description), auteur et propriétaire du dépôt GitHub, licence, détails de chaque composant (à quoi sert le skill, quels outils l'agent utilise-t-il, à quel événement le hook s'exécute-t-il, quel serveur MCP et a-t-il besoin d'un jeton).

Règles lors des questions :

• L'utilisateur choisit un hook avec un hôte autre que Claude Code : signaler le conflit dans references/hosts.md section 4, demander s'il faut conserver le hook.
• Le plugin nécessite un jeton ou un mot de passe : demander comment le fournir (Claude Code : userConfig avec sensitive: true ; autre hôte : variable d'environnement documentée dans le README). Ne jamais écrire de valeur sensible dans un fichier.
• Le nom est interdit par Claude Code (references/hosts.md section 2.1) : proposer un autre nom.
• Le dossier cible contient déjà des fichiers : lister les fichiers qui seront écrasés et demander confirmation avant d'écrire.

Étape 3 : Finaliser la conception

Écrire un résumé dans le chat : nom, hôte, emplacement, arborescence du dossier à créer (en indiquant l'hôte de chaque fichier), quels composants s'exécutent sur quel hôte, les valeurs que l'agent définira automatiquement, les points non vérifiés. Si la réponse soulève de nouvelles ambiguïtés, demander à nouveau, ne pas générer de fichier.

Étape 4 : Générer les fichiers

1. Lire template.md (structure de chaque fichier) et references/components.md (format de chaque composant). Lire examples/sample.md pour connaître le niveau de détail attendu.
2. Écrire le manifeste pour chaque hôte sélectionné. name, version, description sont identiques dans tous les manifestes.
3. Écrire les composants à la racine du plugin, pas dans .claude-plugin/ ou .codex-plugin/ :
   • Skill : skills/<nom>/SKILL.md, frontmatter avec name et description uniquement, lisible par tous les hôtes.
   • MCP : .mcp.json pour Claude Code et Codex ; mcp_config.json pour Antigravity (serveur distant avec serverUrl). Les deux fichiers contiennent la même liste de serveurs.
   • Hook : hooks/hooks.json enveloppé dans la clé "hooks", toujours avec un matcher, appelant le script via "${CLAUDE_PLUGIN_ROOT}" (variable de Claude Code). Le script est placé dans scripts/, avec shebang.
   • Agent, commande, LSP, userConfig : selon references/components.md.
4. Écrire README.md à partir du modèle Fichier 8, au moins 40 mots, comprenant un tableau des composants par hôte et les commandes d'installation pour chaque hôte (references/publishing.md section 5).
5. Mode ajout de composant : ajouter uniquement les nouveaux fichiers et modifier les clés nécessaires dans le manifeste ; augmenter version (patch) dans tous les manifestes si le plugin a déjà été publié.

Étape 5 : Auto-validation

1. Exécuter la commande shell HOSTS="<hôtes sélectionnés>" bash scripts/validate.sh <dossier-du-plugin-ou-du-dépôt>. Exemple : HOSTS="claude codex antigravity".
2. Le script exécute check_plugin.py (vérification du manifeste, nom, chemins, MCP, hook, skill, agent, marketplace, placeholders, chaînes ressemblant à des secrets), puis claude plugin validate et agy plugin validate si ces commandes sont disponibles sur la machine.
3. En cas de [FAIL] ou d'erreur signalée par la CLI : corriger le fichier, relancer jusqu'à obtenir le code de sortie 0.
4. Lire chaque [WARN] : corriger si possible ; si on le conserve (par exemple avertissement concernant un hook multi-hôte déjà signalé à l'utilisateur), consigner la raison dans le rapport de livraison.
5. Si des fichiers temporaires sont nécessaires, les écrire dans le répertoire temporaire spécifié par l'utilisateur, ou à défaut dans le répertoire temporaire du système d'exploitation ; les supprimer immédiatement après la vérification.

Étape 6 : Marketplace (si sélectionné)

• Claude Code : .claude-plugin/marketplace.json à la racine du dépôt (modèle Fichier 9).
• Codex : .agents/plugins/marketplace.json à la racine du dépôt (modèle Fichier 10).
• Antigravity : pas de fichier nécessaire ; le README indique la commande agy plugin install avec l'URL du dépôt GitHub, par exemple https://github.com/phucbui/pr-review-kit.
• Relancer l'étape 5 avec le dossier racine du dépôt pour valider également le marketplace.

Étape 7 : Livraison

Afficher un rapport selon le modèle « Rapport de livraison » à la fin de template.md : dossier, hôte, résultat de la validation, tableau des fichiers, points non vérifiés, commandes de test local, commandes de publication à exécuter par l'utilisateur (references/publishing.md sections 3 à 6). Si le projet contient better-skill-gen ou better-agent-gen, suggérer en une ligne comment les utiliser pour écrire un composant plus détaillé.

---

4. Contraintes

• Obligatoires :
  • Demander l'hôte, l'emplacement, les composants, le marketplace avant de créer des fichiers ; ne jamais décider un point ambigu.
  • Écrire uniquement dans le dossier du plugin cible et dans le fichier marketplace à la racine du dépôt ; pas de fichiers modèles ailleurs. Les exemples se trouvent uniquement dans examples/ de ce skill.
  • Ne pas exécuter git commit, git push, claude plugin install, agy plugin install, codex plugin marketplace add ; afficher uniquement les commandes.
  • Ne jamais écrire de jeton, mot de passe ou clé API dans un fichier.
  • Livrer uniquement lorsque scripts/validate.sh retourne 0.
• Recommandé :
  • Utiliser des noms en kebab-case pour le plugin, le skill et l'agent ; version initiale 0.1.0.
  • Garder le plugin centré sur un seul objectif ; scinder le plugin si l'utilisateur regroupe des fonctionnalités non liées.
  • Indiquer clairement dans le README quel composant s'exécute sur quel hôte.
• À éviter :
  • Ne pas copier le contenu de SKILL.md avec les champs spécifiques à Claude Code dans un plugin destiné à Codex ou Antigravity.
  • Ne pas utiliser de chemins absolus ni de .. dans les manifestes, hooks, MCP.
  • Ne pas placer de CLAUDE.md à la racine du plugin ; si une configuration est nécessaire, l'intégrer dans le skill.