Plugins Claude Code : packager et partager ses skills

Une skill projet vit dans .claude/skills/ et se partage par git avec le dépôt. Pratique pour une équipe sur un même projet, mais limité dès que vous voulez réutiliser une skill sur plusieurs projets, la versionner ou la distribuer à d'autres. La réponse de Claude Code est le plugin : un dossier autonome qui empaquette skills, agents, hooks et serveurs MCP, installable et mis à jour comme une dépendance. Ce guide montre comment packager une skill en plugin, le publier et le sécuriser, avec un lab vérifié.

Ce que vous allez apprendre

Distinguer une skill projet d'un plugin distribuable
Packager une skill dans un plugin avec son manifeste
Publier le plugin via un marketplace git et l'installer
Versionner un plugin et auditer un plugin tiers avant installation

Prérequis

Savoir créer une skill et structurer une skill avancée
Un dépôt git pour héberger le marketplace
Claude Code à jour (lab vérifié en v2.1.152)

Pourquoi un plugin plutôt qu'une skill projet

Une skill projet est faite pour un dépôt. Un plugin est fait pour le partage. Trois différences comptent.

Le namespacing : une skill de plugin s'invoque nom-du-plugin:nom-de-la-skill, ce qui évite les collisions entre skills de provenances différentes. Le versioning : un plugin porte une version, et les utilisateurs ne reçoivent une mise à jour que lorsque vous la publiez. La distribution : un plugin s'installe d'une commande depuis un marketplace, sans copier-coller de dossiers.

En clair : tant que la skill sert votre projet, gardez-la dans .claude/skills/. Dès qu'elle doit voyager entre projets ou personnes, faites-en un plugin.

Anatomie d'un plugin

Un plugin est un dossier avec un manifeste .claude-plugin/plugin.json à sa racine, et les composants à côté (pas dans .claude-plugin/). Voici le plugin du lab, qui empaquette une skill notes-release :

Répertoireboite-a-outils/
- Répertoire.claude-plugin/
  - plugin.json
- Répertoireskills/
  - Répertoirenotes-release/
    SKILL.md

Le manifeste minimal ne requiert qu'un name ; les autres champs sont des métadonnées utiles :

{
  "name": "boite-a-outils",
  "description": "Skills utilitaires : génération de notes de version à partir des commits.",
  "version": "0.1.0",
  "author": { "name": "Stéphane Robert" },
  "license": "MIT",
  "keywords": ["release", "changelog", "git"]
}

Un plugin peut contenir bien plus que des skills : des agents (agents/), des hooks (hooks/), des serveurs MCP (.mcp.json), des binaires (bin/). C'est ce qui en fait un format de distribution complet, pas seulement un sac de skills.

Lab : packager une skill et valider le plugin

La skill notes-release créée précédemment se range telle quelle dans skills/notes-release/SKILL.md. Claude Code fournit un validateur natif pour vérifier la structure avant publication :

claude plugin validate ./plugins/boite-a-outils

Validating plugin manifest: .../plugins/boite-a-outils/.claude-plugin/plugin.json

✔ Validation passed

Le validateur contrôle le manifeste et le frontmatter des skills, agents et hooks embarqués. Lancez-le systématiquement avant de publier : il attrape les fautes de chemin et de frontmatter que vous ne verriez qu'à l'installation.

Publier via un marketplace

Pour distribuer le plugin, vous le déclarez dans un marketplace : un dépôt git contenant un fichier .claude-plugin/marketplace.json qui liste vos plugins.

{
  "name": "demo-marketplace",
  "owner": { "name": "Stéphane Robert" },
  "plugins": [
    {
      "name": "boite-a-outils",
      "source": "./plugins/boite-a-outils",
      "description": "Skills utilitaires : génération de notes de version.",
      "category": "development"
    }
  ]
}

Le source en chemin relatif suppose que les plugins vivent dans le même dépôt que le marketplace. Il accepte aussi un dépôt github, une url git, ou un sous-dossier de monorepo. Le marketplace se valide comme le plugin :

claude plugin validate .

Validating marketplace manifest: .../.claude-plugin/marketplace.json

✔ Validation passed

Une fois le dépôt poussé, n'importe qui l'ajoute et installe le plugin :

/plugin marketplace add votre-org/votre-depot
/plugin install boite-a-outils@demo-marketplace

L'interface /plugin regroupe la découverte, les plugins installés et les marketplaces. Le marketplace officiel claude-plugins-official est disponible d'emblée ; on y trouve par exemple le plugin skill-creator, qui aide à créer et tester des skills, installable par /plugin install skill-creator@claude-plugins-official.

Versionner un plugin

Deux modes coexistent. Si le manifeste porte un champ version, le plugin est épinglé à cette chaîne : vos utilisateurs ne reçoivent une mise à jour que lorsque vous incrémentez la version. Si vous omettez version, Claude Code utilise le SHA du commit git : chaque commit devient de fait une nouvelle version.

Pour un plugin partagé en équipe, préférez une version explicite (0.1.0, 0.2.0) : elle rend les mises à jour intentionnelles et lisibles, là où le suivi par commit propage le moindre changement.

Sécurité : un plugin exécute du code

C'est le point à ne jamais négliger. Un plugin peut embarquer des hooks, des serveurs MCP et des binaires ajoutés au PATH : il exécute donc du code arbitraire avec vos privilèges. La documentation officielle est explicite : n'installez de plugins et n'ajoutez de marketplaces que depuis des sources de confiance, car Anthropic ne contrôle pas leur contenu.

Trois réflexes concrets :

Inspectez avant d'installer. Les versions récentes affichent un écran « Will install » listant précisément les commandes, agents, skills, hooks et serveurs MCP ajoutés. Lisez-le.
Traitez un plugin comme une dépendance, pas comme une config : il mérite la même revue qu'un paquet npm. Cela rejoint la logique de la supply chain logicielle.
Verrouillez côté organisation si besoin : le réglage strictKnownMarketplaces (managed settings) limite les marketplaces autorisés, sans que les utilisateurs puissent l'outrepasser.

Dépannage

Symptôme	Cause probable	Correction
`Validation failed` sur le plugin	Composants dans `.claude-plugin/`	Déplacer `skills/` etc. à la racine du plugin
Plugin introuvable à l'install	Nom du plugin différent entre manifeste et marketplace	Aligner le `name` des deux fichiers
Chemin `source` rejeté	Chemin relatif sans `./` ou avec `../`	Utiliser `./plugins/...` depuis la racine du marketplace
Skill du plugin non invocable	Oubli du namespace	Invoquer `plugin:skill`, pas juste `skill`
Mise à jour non propagée	`version` non incrémentée	Bumper le champ `version` du manifeste

À retenir

Une skill projet sert un dépôt ; un plugin sert le partage, le versioning et la distribution.
Le manifeste .claude-plugin/plugin.json ne requiert qu'un name ; les composants vont à la racine, pas dans .claude-plugin/.
Un marketplace est un dépôt git avec .claude-plugin/marketplace.json qui liste vos plugins.
claude plugin validate vérifie plugin et marketplace avant publication : utilisez-le.
Versionnez explicitement un plugin d'équipe plutôt que de suivre les commits.
Un plugin exécute du code : inspectez l'écran « Will install » et n'installez que des sources de confiance.

Prochaines étapes

Skills avancées (scripts) Structurer les skills que vous allez packager

Agent Skills : le standard Le format portable derrière vos plugins

Serveur MCP Embarquer un serveur MCP dans un plugin

Hooks Claude Code Ajouter des hooks à un plugin pour automatiser des garde-fous