plugin-forge

Présentation de la skill plugin-forge

plugin-forge est une skill de création et de maintenance pensée pour les auteurs de plugins Claude Code qui veulent une structure de dossiers correcte, les bons fichiers de manifeste et un enregistrement marketplace propre, sans réinventer tout le workflow. Le vrai besoin n’est pas simplement de « rédiger un peu de JSON », mais de publier un plugin correctement initialisé, versionné de façon cohérente et installable dans un flux de travail basé sur une marketplace.

À qui s’adresse le mieux plugin-forge

Utilisez la skill plugin-forge si vous :

• créez un nouveau plugin Claude Code à partir de zéro
• ajoutez des composants de plugin comme commands/, agents/, skills/ ou hooks/
• mettez à jour .claude-plugin/plugin.json et les métadonnées marketplace en même temps
• testez des plugins en local avant publication
• maintenez un dépôt de plugins au format marketplace avec plusieurs plugins

Elle est particulièrement utile pour les développeurs qui veulent une structure reproductible, pas seulement une sortie ponctuelle générée par prompt.

Ce qui distingue plugin-forge d’un prompt générique

Un prompt générique peut produire l’ébauche d’un plugin, mais plugin-forge ajoute des garde-fous concrets :

• une organisation de répertoires de plugin définie
• des emplacements de manifeste explicites et des attentes claires sur les champs
• une référence du schéma marketplace
• un workflow d’installation et de test en local
• des scripts d’automatisation pour le scaffolding et l’incrémentation de version

Cette combinaison compte, car la cause la plus fréquente d’échec d’un plugin n’est pas la qualité du code, mais une structure incohérente ou des métadonnées qui ne correspondent pas.

Ce que la skill plugin-forge couvre réellement

Les éléments présents dans le dépôt montrent que plugin-forge se concentre sur :

• scripts/create_plugin.py pour générer l’ossature d’un nouveau plugin
• scripts/bump_version.py pour synchroniser les mises à jour de version
• references/plugin-structure.md pour la structure des dossiers et l’organisation des manifestes
• references/marketplace-schema.md pour les règles d’une entrée marketplace
• references/workflows.md pour le flux de création, test et publication

On est donc davantage face à un guide d’implémentation avec outillage d’appoint qu’à un document théorique généraliste.

Quand plugin-forge est un bon choix pour la génération de code

plugin-forge pour Code Generation est surtout utile quand vous voulez que le modèle génère des fichiers qui doivent respecter exactement la forme attendue d’un plugin, par exemple :

• un nouveau squelette de plugin avec des métadonnées valides
• une nouvelle commande ou une nouvelle skill insérée dans un plugin existant
• des mises à jour de plugin.json accompagnées des changements correspondants dans l’entrée marketplace
• la préparation d’une release avec incrémentation sémantique de version

Si votre besoin principal concerne uniquement la logique métier dans un plugin déjà opérationnel, plugin-forge sera moins utile qu’une skill de code spécialisée dans votre domaine.

Comment utiliser la skill plugin-forge

Contexte d’installation pour plugin-forge

Le fichier SKILL.md upstream ne publie pas sa propre commande d’installation ; l’installation dépend donc de la façon dont vous chargez les skills dans votre environnement. Si vous utilisez le bundle de skills du dépôt, un schéma courant est :

npx skills add softaworks/agent-toolkit --skill plugin-forge

Ensuite, faites appel à plugin-forge lorsque votre tâche concerne la création de plugin, les manifestes, l’enregistrement marketplace, les tests en local ou la gestion de version.

Les fichiers plugin-forge à lire en premier

Pour une prise en main rapide, commencez dans cet ordre :

1. skills/plugin-forge/SKILL.md
2. skills/plugin-forge/references/plugin-structure.md
3. skills/plugin-forge/references/marketplace-schema.md
4. skills/plugin-forge/references/workflows.md
5. skills/plugin-forge/scripts/create_plugin.py
6. skills/plugin-forge/scripts/bump_version.py

Ce parcours vous donne d’abord le « quoi », puis la structure de fichiers attendue, ensuite le contrat marketplace, puis les helpers directement exploitables.

Quelles informations plugin-forge attend de votre part

plugin-forge fonctionne nettement mieux si vous fournissez un contexte concret sur le dépôt et la publication, plutôt qu’un simple « crée-moi un plugin ». Au minimum, précisez :

• le nom du plugin en kebab-case
• le chemin racine de la marketplace
• l’objectif du plugin
• le nom et l’e-mail de l’auteur
• les mots-clés initiaux
• la catégorie
• si vous avez besoin de commands, agents, skills, hooks ou d’une configuration MCP
• s’il s’agit d’un nouveau plugin ou d’une mise à jour d’un plugin existant

Sans ces informations, le modèle peut toujours produire des fichiers, mais le résultat demandera en général un nettoyage manuel.

Transformer un objectif flou en prompt plugin-forge solide

Prompt faible :

Create a Claude Code plugin for my project.

Prompt plus solide :

Use plugin-forge to scaffold a new Claude Code plugin named schema-audit inside /repos/internal-marketplace. Author is Jane Doe <jane@example.com>. Description: “Validate JSON and OpenAPI schemas in CI.” Keywords: schema,openapi,json,validation. Category: developer-tools. Include commands/ and skills/, but no hooks yet. Generate the expected folder layout, plugins/schema-audit/.claude-plugin/plugin.json, the matching .claude-plugin/marketplace.json entry, and a short README. Follow the marketplace and plugin structure references.

Le deuxième prompt donne à plugin-forge assez d’informations pour produire des fichiers beaucoup plus proches d’un résultat réellement exploitable.

Utiliser le script de scaffolding quand vous voulez aller vite

Si vous connaissez déjà vos métadonnées, utilisez le script helper plutôt que de construire l’arborescence initiale à la main :

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

C’est la voie la plus rapide si votre priorité est une configuration correcte plutôt qu’un scaffolding entièrement façonné à la main.

Utiliser le script de version pour éviter la dérive des manifestes

L’un des aspects les plus utiles de plugin-forge en pratique est la synchronisation des versions. La skill inclut scripts/bump_version.py pour mettre à jour à la fois :

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

Exemple :

python scripts/bump_version.py plugin-name patch \
  --marketplace-root /path/to/marketplace

C’est important, car un décalage de version entre ces fichiers fait partie des erreurs de maintenance les plus courantes.

Suivre le vrai workflow plugin-forge

Un guide plugin-forge pragmatique ressemble à ceci :

1. générer l’ossature du plugin
2. inspecter le plugin.json généré
3. vérifier l’entrée marketplace dans .claude-plugin/marketplace.json
4. ajouter les composants comme les commandes ou les skills
5. tester en local via le flux d’installation marketplace
6. itérer
7. incrémenter la version avant la release

Ce workflow est plus fiable que de demander au modèle de tout faire d’un seul coup dans un prompt énorme.

Prévoir tôt le flux de test local

Les références incluent un chemin concret pour les tests en local :

/plugin marketplace add /path/to/marketplace-root
/plugin install plugin-name@marketplace-name

Autrement dit, vous devez formuler vos prompts de sorte que plugin-forge produise des chemins et des métadonnées réellement installables, pas seulement des fichiers descriptifs. Si le chemin source ou le nom du plugin est incohérent, les tests cassent immédiatement.

Les fichiers clés que plugin-forge modifie souvent

En usage réel, attendez-vous à ce que plugin-forge crée ou modifie :

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/<plugin-name>/README.md
• plugins/<plugin-name>/commands/
• plugins/<plugin-name>/agents/
• plugins/<plugin-name>/skills/
• plugins/<plugin-name>/hooks/hooks.json
• plugins/<plugin-name>/.mcp.json

Cette portée est utile pour planifier la relecture, car plugin-forge génère souvent des changements répartis sur plusieurs fichiers.

Conseils pratiques pour améliorer la qualité des sorties plugin-forge

Demandez à plugin-forge de :

• préserver exactement les noms et chemins de plugin existants
• garder tous les identifiants en kebab-case
• afficher ensemble le manifeste du plugin et l’entrée marketplace
• expliquer les champs obligatoires qu’il n’a pas pu déduire
• séparer les « generated files » du « manual follow-up »
• vérifier que les versions et les noms correspondent dans tous les manifestes

Ces demandes réduisent le risque d’obtenir une sortie séduisante, mais impossible à installer.

FAQ sur la skill plugin-forge

plugin-forge vaut-il le coup si je sais déjà bien prompter ?

Oui, si votre principal risque concerne la justesse structurelle. La skill plugin-forge est plus utile qu’un prompt classique lorsque vous avez besoin de manifestes cohérents, d’entrées marketplace correctes et d’une arborescence de répertoires fiable. Si vous cherchez seulement de l’aide pour écrire un unique fichier de commande dans un plugin existant, l’avantage est plus limité.

plugin-forge est-il adapté aux débutants ?

Dans l’ensemble, oui. plugin-forge donne aux débutants un parcours concret pour créer et tester un plugin. Le point d’attention, c’est qu’un débutant doit malgré tout comprendre où se trouve la racine de sa marketplace, quelles conventions de nommage il utilise et quels composants il veut réellement. La skill aide surtout sur la structure, moins sur la conception produit.

Quand ne faut-il pas utiliser plugin-forge ?

Évitez plugin-forge si :

• vous ne construisez pas un plugin Claude Code
• vous n’utilisez pas une distribution de type marketplace
• vous cherchez seulement de la génération de code Python ou JavaScript générique
• votre dépôt suit une structure de plugin personnalisée qui diffère volontairement de la structure documentée

Dans ces cas-là, plugin-forge risque de vous pousser vers une mauvaise forme de projet.

plugin-forge gère-t-il automatiquement la publication ?

Pas entièrement. La skill couvre bien tout le travail préparatoire : scaffolding, manifestes, enregistrement marketplace, indications de test local et mises à jour de version. En revanche, ce n’est pas une plateforme de release de bout en bout. Vous devez toujours relire les fichiers, tester en local et exécuter votre propre processus de publication ou de distribution.

Quel est le principal frein à l’adoption ?

Le plus souvent, c’est l’absence de contexte sur le dépôt. plugin-forge suppose que vous savez où se trouve la racine de la marketplace et comment votre plugin doit être catégorisé. Si vous ne pouvez pas répondre à ces questions, le résultat restera au stade de brouillon plutôt que d’être prêt pour la production.

Comment plugin-forge se compare-t-il à une édition manuelle des manifestes ?

Les modifications manuelles conviennent pour des changements ponctuels, mais plugin-forge est meilleur si vous cherchez de la répétabilité ou si vous voulez éviter les divergences entre plugin.json et marketplace.json. Les scripts inclus constituent son avantage pratique le plus clair.

Comment améliorer la skill plugin-forge

Donner à plugin-forge des entrées ancrées dans le dépôt

La meilleure amélioration consiste à fournir les chemins exacts et les fichiers actuels. Au lieu de demander « un bump de version », dites plutôt :

Use plugin-forge to bump schema-audit in /repos/internal-marketplace from its current version using a minor change. Check both plugins/schema-audit/.claude-plugin/plugin.json and .claude-plugin/marketplace.json, then show the diff.

Cela pousse la skill vers des changements vérifiables, plutôt que vers des conseils génériques.

Demander une sortie fichier par fichier, pas seulement un résumé

plugin-forge donne de meilleurs résultats quand vous demandez des livrables concrets :

• le plugin.json complet
• l’entrée marketplace exacte
• l’arborescence de répertoires proposée
• un README de départ
• les commandes de suivi pour tester en local

C’est particulièrement important pour plugin-forge pour Code Generation, où la valeur vient de fichiers directement applicables.

Prévenir les modes d’échec les plus fréquents

Surveillez ces problèmes dans les sorties de plugin-forge :

• le nom du plugin diffère selon les fichiers
• le chemin source de la marketplace ne correspond pas à la structure réelle des dossiers
• la version est mise à jour dans un manifeste, mais pas dans l’autre
• des composants optionnels sont mentionnés dans les métadonnées sans avoir été créés
• la structure générée omet .claude-plugin/plugin.json

Une vérification rapide par rapport à references/plugin-structure.md et references/marketplace-schema.md permet d’en repérer la plupart.

Utiliser un workflow en deux passes pour de meilleurs résultats

En pratique, un bon guide plugin-forge ressemble à ceci :

1. première passe : générer la structure et les manifestes
2. deuxième passe : générer les composants du plugin et améliorer le README

Essayer de traiter en un seul prompt le scaffolding, la logique métier, la documentation, la configuration de test et les notes de publication fait souvent baisser la qualité. plugin-forge est le plus fort quand la structure passe d’abord.

Itérer après la première sortie avec des corrections ciblées

Ne dites pas simplement « corrige ça ». Donnez des consignes de correction précises, par exemple :

• « Regenerate marketplace.json entry so source points to ./plugins/schema-audit. »
• « Add skills/ to the tree and keep manifest fields unchanged. »
• « Update only version fields; do not rewrite descriptions or keywords. »
• « Align the plugin name to kebab-case everywhere. »

Ce type d’itération contrainte rend plugin-forge beaucoup plus fiable.

Associer plugin-forge aux documents de référence, pas les remplacer

La meilleure façon d’améliorer la sortie de plugin-forge est de lui demander explicitement de citer ou suivre les références du dépôt. Dans vos prompts, mentionnez :

• references/plugin-structure.md pour les attentes sur l’arborescence
• references/marketplace-schema.md pour les champs marketplace
• references/workflows.md pour le flux d’installation et de test

De cette façon, la skill reste alignée sur les conventions réelles du dépôt, au lieu de retomber sur des hypothèses génériques sur les plugins.