Plugins Claude Code : packaging, publication & distribution

Pourquoi ce module

M16 vous a appris ce qu'est un plugin et comment l'assembler. Ce module traite la suite : comment passer d'un plugin qui marche sur votre machine à un plugin versionné, testé, distribué — à votre équipe d'abord, au public ensuite. C'est le cycle de vie complet : créer → tester en local → versionner → distribuer → maintenir → sécuriser.

⚠️ À savoir d'emblée (état mai 2026) :

• Les marketplaces officielles d'Anthropic sont gratuites et ne reversent pas de revenus aux créateurs. Pas de revenue-share 50/50. La monétisation éventuelle passe par des marketplaces tiers (cf. dernière section).
• Il n'existe pas de commande … publish. On publie un plugin en le soumettant via un formulaire web Anthropic ; en interne, on distribue via Git + settings.json. Détails plus bas.

Prérequis : avoir suivi M16 (Anatomie d'un plugin) — savoir ce qu'est un plugin.json et les composants (skills, hooks, sub-agents, MCP). Avoir un compte GitHub.

Objectifs pédagogiques

À l'issue de ce module, vous serez capable de :

1. Préparer un plugin pour la distribution : plugin.json complet (version, author, license), README, LICENSE
2. Versionner un plugin : semver explicite vs SHA git, et savoir quand choisir l'un ou l'autre
3. Tester un plugin en local avant publication (--plugin-dir, marketplace locale, hot-reload)
4. Héberger une marketplace : marketplace.json, sources, mode strict
5. Distribuer en équipe via .claude/settings.json (extraKnownMarketplaces, enabledPlugins)
6. Publier publiquement (formulaire de soumission, review communautaire) et sécuriser/maintenir un plugin dans la durée

Plan détaillé

1. Du plugin local au plugin distribué : 4 canaux
2. Préparer un plugin pour la distribution
3. Versionner : semver explicite vs SHA git
4. Tester en local avant de publier
5. Héberger sa marketplace (marketplace.json)
6. Distribution en équipe (settings.json)
7. Publier publiquement (soumission Anthropic)
8. Sécurité, maintenance et fin de vie
9. Monétisation : la réalité 2026
10. Atelier : packager, tester et distribuer

Du plugin local au plugin distribué : 4 canaux

Un même plugin peut être diffusé par plusieurs canaux, du plus simple au plus large :

Préparer un plugin pour la distribution

Un plugin local minimal suffit pour soi. Pour le distribuer, on enrichit le manifeste et on ajoute la documentation attendue.

facture-extractor/
├── .claude-plugin/
│   └── plugin.json          # manifeste enrichi (cf. ci-dessous)
├── skills/
│   └── extraction/SKILL.md
├── agents/
│   └── verificateur.md
├── README.md                # guide utilisateur (clair, non-dev)
├── LICENSE                  # MIT, Apache-2.0… (recommandé)
└── CHANGELOG.md             # historique des versions

plugin.json prêt à distribuer :

{
  "name": "facture-extractor",
  "version": "1.2.0",
  "description": "Extrait un JSON structuré depuis des factures PDF",
  "author": { "name": "Acme", "email": "dev@acme.io" },
  "homepage": "https://github.com/acme/facture-extractor",
  "repository": "https://github.com/acme/facture-extractor",
  "license": "MIT",
  "keywords": ["facture", "pdf", "extraction"],
  "defaultEnabled": true
}

• name est le seul champ requis ; le reste est métadonnée de découverte.
• defaultEnabled (v2.1.154+) : true → le plugin est actif dès l'installation ; false → installé mais désactivé, l'utilisateur l'active avec /plugin enable. Mettez false pour un plugin à effets de bord sensibles.
• Les composants restent découverts par convention (skills/, agents/, hooks/hooks.json, .mcp.json) — pas besoin de les lister (cf. M16).

Pensez « dépendance logicielle » : un README clair (à quoi ça sert, ce que ça exécute, quelles permissions), une LICENSE explicite et un CHANGELOG font la différence entre un plugin adopté et un plugin ignoré.

Versionner : semver explicite vs SHA git

Claude Code résout la version d'un plugin dans cet ordre :

1. version dans plugin.json (épingle explicitement)
2. version dans l'entrée marketplace.json (même effet)
3. SHA du commit git (sources github/url/relative) → chaque commit = une nouvelle version
4. unknown (sources npm ou dossiers non-git)

Convention semver : MAJOR.MINOR.PATCH — patch = corrections, minor = ajouts rétrocompatibles, major = ruptures (documentez la migration dans le CHANGELOG). Côté consommateur, on épingle une version précise dans la marketplace via ref (tag/branche) ou sha (commit exact) du source (voir section suivante).

Tester en local avant de publier

Inutile de publier pour itérer. Trois façons de charger un plugin en cours de développement :

# 1) Charger un dossier de plugin directement (le plus rapide)
claude --plugin-dir ./facture-extractor

# 2) Traiter un dossier local comme une marketplace
#    (en session Claude Code, via slash commands)
/plugin marketplace add ./ma-marketplace-locale
/plugin install facture-extractor@ma-marketplace-locale

# 3) Valider le manifeste et la syntaxe avant tout
claude plugin validate ./facture-extractor

Après modification, rechargez sans redémarrer : la commande /reload-plugins recharge les composants (les SKILL.md se mettent souvent à jour à la volée ; hooks/agents/MCP nécessitent le reload).

Commandes claude plugin utiles (en terminal ; équivalents /plugin … en session) :

Héberger sa marketplace

Une marketplace est un catalogue décrit par un marketplace.json (sur un repo Git, une URL ou un dossier). C'est le canal de distribution d'équipe et la base d'une soumission publique.

{
  "name": "acme-plugins",
  "owner": { "name": "Acme", "email": "dev@acme.io" },
  "description": "Plugins internes Acme",
  "plugins": [
    {
      "name": "facture-extractor",
      "source": {
        "source": "github",
        "repo": "acme/facture-extractor",
        "ref": "v1.2.0"
      },
      "description": "Extraction de factures PDF → JSON",
      "category": "productivity"
    }
  ]
}

• Champs racine requis : name, owner, plugins. Chaque entrée requiert name et source.
• Sources possibles : chemin relatif ("./plugins/x"), github (repo, + ref/sha pour épingler), url (Git), git-subdir, npm.
• Mode strict (défaut true) : plugin.json fait autorité et la marketplace peut compléter. Avec strict: false, c'est l'entrée marketplace qui déclare tout (le plugin.json ne doit alors pas déclarer de composants) — pratique quand l'opérateur de marketplace contrôle des plugins « bruts ».

On ajoute un catalogue ainsi :

/plugin marketplace add acme/plugins-repo     # owner/repo GitHub
/plugin install facture-extractor@acme-plugins

Distribution en équipe

Le vrai levier en entreprise : pré-déclarer la marketplace et auto-activer les plugins pour tout le monde, via le .claude/settings.json versionné dans le repo du projet.

{
  "extraKnownMarketplaces": {
    "acme-plugins": {
      "source": { "source": "github", "repo": "acme/plugins-repo" }
    }
  },
  "enabledPlugins": {
    "facture-extractor@acme-plugins": true,
    "code-formatter@acme-plugins": true
  }
}

• extraKnownMarketplaces : marketplaces connues d'office (chaque membre de l'équipe les a sans manip).
• enabledPlugins : plugins activés automatiquement pour le projet (name@marketplace → true).
• Scopes : .claude/settings.json = projet (partagé via git) · ~/.claude/settings.json = perso · .claude/settings.local.json = local (gitignored).

Résultat : un nouvel arrivant clone le repo et dispose immédiatement des plugins de l'équipe, à la bonne version épinglée.

Publier publiquement

Pour ouvrir votre plugin à tous, deux catalogues Anthropic :

• claude-plugins-official — curé par Anthropic, inclus automatiquement chez tout le monde. Pas de candidature ouverte.
• claude-plugins-community — contributions externes avec review, à ajouter manuellement côté utilisateur.

Procédure réelle de soumission (communauté) :

1. Préparer le repo public (plugin.json valide, README, LICENSE) et valider : claude plugin validate ./mon-plugin.
2. Soumettre via le formulaire web Anthropic — par ex. claude.ai/settings/plugins/submit ou la Console (platform.claude.com/plugins/submit). Il n'y a pas de commande publish.
3. Review : validation automatique (intégrité du manifeste, syntaxe) + screening sécurité.
4. Une fois accepté, le plugin est épinglé à un commit SHA dans le dépôt anthropics/claude-plugins-community et synchronisé dans le marketplace.json public.

Sécurité, maintenance et fin de vie

Un plugin exécute du code (hooks, MCP, bin/) chez ceux qui l'installent. La discipline de distribution est donc aussi une discipline de sécurité.

À la publication :

• Aucun secret dans le repo (clés API, tokens) — scannez avant de pousser.
• Décrivez dans le README ce que le plugin exécute et les permissions qu'il requiert.
• Épinglez vos dépendances ; préférez un source avec ref/sha pour les usages sensibles.

Côté consommateur (à enseigner) :

• N'installez que depuis des sources de confiance ; lisez les hooks/commandes avant d'activer.
• Combinez avec des deny rules dans settings.json (ex. interdire Bash(rm -rf:*)).
• Utilisez defaultEnabled: false pour les plugins à effets de bord, afin de forcer l'opt-in.

Dans la durée :

• Bumpez la version à chaque release, tenez le CHANGELOG, documentez les migrations sur les MAJOR.
• claude plugin update / prune côté utilisateurs ; annoncez les fins de support.

Monétisation : la réalité 2026

Soyons clairs pour vos stagiaires, car beaucoup arrivent avec une idée fausse :

• Le marketplace officiel Anthropic est gratuit et ne paie pas les créateurs. Aucun revenue-share 50/50. C'est un canal de distribution et de visibilité, pas de revenus directs.
• La monétisation existe via des marketplaces tiers (ex. Agensi) qui appliquent leurs propres modèles (souvent ~80/20 en faveur du créateur) et gèrent paiement, ratings, analytics.
• Les chiffres de « marché des extensions IA » (navigateur, IDE) varient fortement (estimations ~1,5–2,5 Md$ pour les extensions navigateur, 9–10 Md$ pour l'ensemble des outils IA en 2026, TCAC ~15–27 % selon les sources) — à recouper avant d'en faire un argument commercial.

Modèles indirects qui marchent sans marketplace payant : open-source + sponsoring (GitHub Sponsors), plugin gratuit en produit d'appel d'une offre de conseil/formation, ou distribution interne (le ROI est l'efficacité de l'équipe, pas une vente).

Atelier : packager, tester et distribuer (45 min)

Livrable : un plugin facture-extractor versionné, testé en local, publié sur une marketplace d'équipe GitHub, et auto-activé via settings.json.

Étapes :

1. Enrichir le manifeste : plugin.json avec version, author, license, description, defaultEnabled. Ajouter README.md, LICENSE, CHANGELOG.md.
2. Valider & tester en local : claude plugin validate ./facture-extractor, puis claude --plugin-dir ./facture-extractor ; vérifier que skill + agent fonctionnent ; itérer avec /reload-plugins.
3. Créer la marketplace : marketplace.json (name, owner, plugins[] avec source github + ref: v1.0.0), poussé sur un repo GitHub.
4. Distribuer en équipe : ajouter extraKnownMarketplaces + enabledPlugins dans .claude/settings.json du projet, committer, vérifier qu'un autre clone récupère le plugin.
5. (Bonus) Préparer une soumission publique : repo public propre, claude plugin validate, repérer le formulaire de soumission (sans soumettre).

Critères de succès :

• ✅ plugin.json valide, version semver
• ✅ Plugin chargé et fonctionnel en local (skill + agent)
• ✅ marketplace.json valide, plugin installable via owner/repo
• ✅ settings.json auto-active le plugin pour le projet
• ✅ Note de sécurité (ce que le plugin exécute, permissions, deny rules conseillées)

Pour aller plus loin

• 📖 Plugins — workflow et soumission
• 📖 Référence plugins (CLI, manifeste, versioning, strict, defaultEnabled)
• 📖 Marketplaces & distribution d'équipe (extraKnownMarketplaces)
• 🎯 Modules complémentaires : M16 Anatomie d'un plugin (les fondations), M7 MCP OAuth (serveurs MCP embarqués), M8 Specs-as-code (tests et qualité)

Récapitulatif

À retenir :

1. Le plugin est l'unité de distribution ; M14 = son cycle de vie (créer → tester → versionner → distribuer → maintenir).
2. Versionner : version semver pour le stable, SHA git pour l'interne ; épingler via ref/sha.
3. Tester sans publier : --plugin-dir, marketplace locale, /reload-plugins, claude plugin validate.
4. Équipe : extraKnownMarketplaces + enabledPlugins dans le settings.json versionné.
5. Public : soumission par formulaire web (pas de CLI publish), review communautaire, épinglage SHA.
6. Marketplace officiel = gratuit, sans revenue-share ; la monétisation passe par des canaux tiers.
7. Sécurité : pas de secrets, README explicite, deny rules, defaultEnabled: false pour le sensible.