Skip to main content
Un plugin est un répertoire de skills, d’agents, de hooks et de serveurs MCP, plus un fichier plugin.json, appelé le manifeste, qui nomme le plugin. Claude Code charge le répertoire comme une unité, ce qui vous permet de le partager avec vos coéquipiers, de l’installer dans plusieurs projets ou de le publier sur une marketplace. Cette page s’adresse aux personnes qui écrivent leurs propres plugins.
Ces cas sont couverts sur d’autres pages :
Commencez par la section qui correspond à ce que vous avez déjà :

Décider quand utiliser un plugin

Les skills, agents, hooks et serveurs MCP fonctionnent tous de manière autonome dans votre projet ou répertoire personnel. Conservez cette configuration autonome tant qu’elle ne concerne qu’un seul projet ou que vous seul. Créez un plugin quand vous voulez partager la configuration avec vos coéquipiers, l’installer dans plusieurs projets ou publier des versions. Quand vous déplacez les skills, agents, hooks et configuration MCP autonomes dans un plugin, leur emplacement et leurs noms changent :
  • Où vont les fichiers : sous le répertoire propre du plugin, appelé la racine du plugin, comme skills/, agents/, hooks/hooks.json et .mcp.json.
  • Comment ils sont nommés : les skills et agents du plugin reçoivent le nom du plugin comme préfixe, par exemple /my-plugin:hello, de sorte que deux plugins peuvent chacun fournir un skill hello sans collision.
Pour déplacer une configuration existante dans un plugin, voir Convertir une configuration .claude/ existante.

Créer votre premier plugin

Dans cette procédure pas à pas, vous créez un plugin dont le seul composant est un skill, un salut, et vous l’exécutez avec --plugin-dir, qui charge un plugin pour une session sans l’installer. Un plugin peut contenir n’importe quel mélange de composants, tels que des skills, des agents, des hooks et des serveurs MCP, et aucun n’est requis ; un skill est le plus petit exemple qui montre la disposition. Vous avez besoin de Claude Code installé et connecté. Ouvrez un terminal dans le répertoire où vous voulez conserver le plugin, par exemple ~/projects, et exécutez les commandes de ces étapes à partir de là. Vous pouvez conserver un plugin n’importe où, car vous passez son chemin à Claude Code quand vous démarrez une session.
1

Créer le répertoire du plugin

Créez le répertoire du plugin, avec un dossier .claude-plugin/ à l’intérieur pour contenir le manifeste :
2

Écrire le manifeste

Le manifeste est un fichier JSON nommé plugin.json qui indique à Claude Code le nom du plugin et le décrit. Enregistrez celui-ci comme my-first-plugin/.claude-plugin/plugin.json :
my-first-plugin/.claude-plugin/plugin.json
Les quatre champs font ceci :
  • name : requis. Il identifie le plugin et devient le préfixe sur chaque skill et agent que le plugin fournit. Ne mettez pas d’espaces dedans.
  • description : le texte que les utilisateurs voient pour le plugin dans /plugin.
  • version : optionnel. Le définir maintient les utilisateurs sur cette version jusqu’à ce que vous la changiez ; Publier une nouvelle version indique quand le définir ou l’omettre.
  • author : qui créditer. name est requis à l’intérieur ; email et url sont optionnels.
Tous les autres champs sont sur la référence du manifeste.Seul plugin.json va à l’intérieur de .claude-plugin/. Le skill que vous ajoutez ensuite va directement sous my-first-plugin/, à côté de ce dossier.
3

Ajouter un skill

Le seul composant de ce plugin est un skill. Chaque skill est un répertoire sous skills/ qui contient un fichier SKILL.md. Créez le répertoire du skill :
Ensuite, créez my-first-plugin/skills/hello/SKILL.md avec ce contenu :
my-first-plugin/skills/hello/SKILL.md
La ligne disable-model-invocation: true signifie que Claude n’exécute pas le skill de lui-même, donc seul vous le déclenchez. Supprimez cette ligne d’un skill que vous voulez que Claude exécute de lui-même. La commande du skill combine le nom du plugin et le nom du skill, donc vous exécutez celui-ci comme /my-first-plugin:hello. Pour les autres champs du frontmatter, voir la référence du frontmatter du skill.
4

Valider le plugin

Vérifiez le manifeste et le frontmatter du skill avant d’exécuter quoi que ce soit :
La commande imprime le chemin du manifeste qu’elle a vérifié et ✔ Validation passed. Si elle imprime ✘ Validation failed à la place, chaque ligne au-dessus de cette ligne de résultat nomme le champ à corriger. Recherchez chaque message sous claude plugin validate rapporte des erreurs.
5

Exécuter Claude Code avec le plugin

Démarrez une session avec le plugin chargé :
Une fois Claude Code démarré, exécutez le skill :
Claude répond avec un salut.
Le plugin ne se charge que dans les sessions que vous démarrez avec --plugin-dir. Pour continuer à travailler dessus sans le drapeau, ou pour tester une version .zip, voir Développer sans marketplace.

Partager votre plugin

Un plugin que vous avez créé avec Créer votre premier plugin n’existe que sur votre machine. Quand il est prêt pour d’autres personnes, il y a trois façons de le leur faire parvenir :
  • L’envoyer à quelques personnes directement : donnez-leur le répertoire du plugin ou un .zip de celui-ci, et rien n’a besoin d’être publié. Voir Partager un plugin sans marketplace.
  • Le lister dans votre propre marketplace : les coéquipiers ajoutent votre marketplace une fois et installent le plugin par nom, et ils reçoivent vos mises à jour. Voir Publier via votre propre marketplace.
  • Le soumettre à la marketplace communautaire d’Anthropic : une fois qu’il est listé, quiconque ajoute cette marketplace peut l’installer. Voir Soumettre à la marketplace communautaire.

Disposition du plugin

Chaque type de composant, tel que les skills, agents, hooks et serveurs MCP, va dans un répertoire fixe sous la racine du plugin, qui est le répertoire que vous passez à --plugin-dir. Ajoutez uniquement les répertoires que vous utilisez. Pour cliquer dans un répertoire de plugin complet et lire ce que chaque fichier fait, ouvrez l’explorateur de plugin. Le tableau liste les répertoires par lesquels la plupart des plugins commencent, et la disposition complète liste le reste.
Seul plugin.json va à l’intérieur de .claude-plugin/. Les composants enregistrés là ne se chargent pas.La racine du plugin est le répertoire propre du plugin, pas ~/.claude/ lui-même. Un .mcp.json enregistré à ~/.claude/.mcp.json ne se charge pas.

Développer sans marketplace

Vous n’avez pas besoin d’une marketplace pour exécuter un plugin que vous écrivez. Chargez-le directement à partir du disque ou d’une URL à la place :
  • --plugin-dir : charge un répertoire ou une archive .zip pour une session.
  • --plugin-url : récupère une archive .zip à partir d’une URL pour une session.
  • claude plugin init : crée un plugin sous ~/.claude/skills/ qui se charge à chaque session.
Si deux plugins chargés de différentes façons partagent un nom, voir Conflits de noms pour savoir lequel Claude Code conserve.

Charger un plugin pour une session

Vous pouvez charger un plugin pour une seule session de trois façons : à partir d’un répertoire ou d’une archive .zip sur le disque avec --plugin-dir, à partir d’une URL avec --plugin-url, ou à partir d’une variable d’environnement quand vous ne pouvez pas ajouter un drapeau. Chaque plugin se charge pour cette session uniquement, et rien n’est écrit dans vos paramètres pour celui-ci. Quand vous modifiez les fichiers du plugin pendant la session, exécutez /reload-plugins pour charger les modifications.

À partir d’un répertoire ou .zip

Quand vous démarrez claude à partir de votre shell, passez --plugin-dir avec le répertoire racine du plugin ou une archive .zip de celui-ci. Répétez le drapeau pour charger plusieurs plugins :

À partir d’un dossier de plugins

Pour charger plusieurs plugins à partir d’un seul endroit, passez un dossier qui les contient, par exemple --plugin-dir ./plugins. Charger un dossier de plugins nécessite Claude Code v2.1.265 ou ultérieur. Si le dossier n’a pas de répertoire .claude-plugin/ et pas de composants de plugin au niveau supérieur, Claude Code le traite comme un dossier de plugins. Chaque sous-dossier immédiat qui a un manifeste .claude-plugin/plugin.json se charge alors comme un plugin séparé. Tout le reste dans le dossier est ignoré sans erreur, y compris un sous-dossier qui n’a pas de manifeste. Si un plugin dans le dossier ne se charge pas, vérifiez que son sous-dossier a un .claude-plugin/plugin.json. Dans une session interactive, vous pouvez également ajouter et supprimer des plugins dans le dossier après le démarrage :
  • Un sous-dossier que vous ajoutez se charge comme un nouveau plugin une fois que son manifeste existe.
  • Quand vous supprimez un sous-dossier, son plugin se décharge.
Un message apparaît dans la session pour chacun de ces changements. Si charger ou décharger un plugin en milieu de conversation invaliderait le cache de prompt, le changement est retenu à la place, et le message vous dit d’exécuter /reload-plugins pour l’appliquer.

À partir d’une URL

Quand vous démarrez claude à partir de votre shell, passez --plugin-url avec l’adresse d’une archive .zip, par exemple un artefact de build que votre CI publie :
Claude Code télécharge l’archive au démarrage. Pour en charger plusieurs, répétez le drapeau ou passez les URL séparées par des espaces dans un argument entre guillemets. Pointez le drapeau uniquement vers des archives que vous contrôlez ou en lesquelles vous avez confiance. Si Claude Code ne peut pas récupérer l’archive, ou si l’archive est invalide, il démarre sans le plugin et enregistre une erreur de chargement de plugin que vous pouvez examiner dans l’onglet Errors du gestionnaire /plugin.

À partir d’une variable d’environnement

Pour charger des plugins dans une session où vous ne pouvez pas ajouter le drapeau --plugin-dir, listez leurs chemins absolus dans la variable d’environnement CLAUDE_CODE_PLUGIN_DIRS à la place. Claude Code charge chaque chemin comme il charge un chemin --plugin-dir. Ces plugins se chargent en plus de ceux que vous passez avec --plugin-dir. Les paramètres de projet et locaux ne peuvent pas définir cette variable. CLAUDE_CODE_PLUGIN_DIRS nécessite Claude Code v2.1.280 ou ultérieur. Les paramètres gérés peuvent désactiver --plugin-dir et CLAUDE_CODE_PLUGIN_DIRS. Voir Drapeaux qui chargent un plugin pour une session. Pour tester un plugin avec un plugin dont il dépend, voir Tester un plugin et sa dépendance localement.

Faire charger un plugin à chaque session

Votre répertoire de skills personnel est ~/.claude/skills/. Claude Code charge n’importe quel dossier là qui contient un .claude-plugin/plugin.json comme un plugin à chaque session, sans drapeau et sans étape d’installation. claude plugin init en crée un pour vous.

Créer le plugin avec claude plugin init

claude plugin init écrit un plugin de démarrage sous ~/.claude/skills/. Nécessite Claude Code v2.1.157 ou ultérieur. Créez-en un à partir de votre shell :
La commande crée ~/.claude/skills/my-tool/ avec un .claude-plugin/plugin.json et un SKILL.md racine. Elle imprime ✔ Created plugin "my-tool" at ~/.claude/skills/my-tool suivi de It will auto-load next session as my-tool@skills-dir. Run /reload-plugins to load it now. Passez --with skills pour que claude plugin init crée un skill sous skills/ pour vous. Les autres valeurs --with sont sur la référence des commandes de plugin.

Nommer les skills du plugin

Le skill racine à ~/.claude/skills/my-tool/SKILL.md est aussi un skill personnel, donc vous l’invoquez comme /my-tool, pas /my-tool:my-tool. Les skills que vous ajoutez sous skills/ à l’intérieur du plugin reçoivent le préfixe du nom du plugin, par exemple /my-tool:example.

Arrêter de charger le plugin

Pour arrêter de charger un plugin créé, supprimez son répertoire, ou exécutez claude plugin disable my-tool@skills-dir dans votre shell avec le nom my-tool@skills-dir que claude plugin init a imprimé. Dans l’ID my-tool@skills-dir, skills-dir se tient à la place où un nom de marketplace serait, car le plugin se charge à partir de votre répertoire de skills plutôt que d’une marketplace.

Partager le plugin via un référentiel

claude plugin init écrit le plugin dans votre répertoire de skills personnel à ~/.claude/skills/, donc il se charge pour vous dans chaque projet. Pour faire charger un plugin pour tout le monde dans un référentiel, créez la même disposition vous-même à <project>/.claude/skills/<name>/, y compris son .claude-plugin/plugin.json. Voir Plugins partagés via un référentiel pour les conditions sous lesquelles Claude Code le charge.

Tester et déboguer

Quand un changement à votre plugin ne s’affiche pas, travaillez à travers ces vérifications dans l’ordre. Chacune vous dit ce que Claude Code a fait avec le plugin :
  1. Dans votre shell, exécutez claude plugin validate <path>. Il vérifie le manifeste et le frontmatter de chaque fichier de skill, agent et command, et quitte avec 0 sur Validation passed. Ajoutez --strict pour échouer aussi sur les avertissements. Les codes de sortie et la gestion des répertoires sont sur la référence des commandes de plugin.
  2. Dans la session en cours, exécutez /reload-plugins pour appliquer les modifications que vous avez apportées sur le disque. Il imprime une ligne Reloaded: avec des comptages. Ensuite, confirmez qu’un skill s’est chargé en tapant sa commande /plugin-name:skill, ou en trouvant le plugin dans l’onglet Installed de /plugin.
  3. Dans la même session, exécutez /plugin. L’onglet Installed liste votre plugin et, dans les détails du plugin, les composants que Claude Code a trouvés. L’onglet Errors liste ce qui n’a pas pu se charger et pourquoi, par exemple un chemin dans votre manifeste qui n’existe pas.
  4. De retour dans votre shell, exécutez claude plugin list. Il imprime les plugins de session uniquement et du répertoire de skills dans leurs propres sections avec Status: ✔ loaded ou l’erreur de chargement. Pour inclure le plugin que vous développez, passez --plugin-dir avec son chemin avant plugin list.
Pour vérifier un serveur MCP, exécutez /mcp dans la session pour voir l’état du serveur. Quand le serveur est sain, /mcp le liste comme connecté. Si ce n’est pas le cas, voir Serveurs MCP qui ne démarrent pas. Pour vérifier un hook, déclenchez l’événement qu’il correspond. Par exemple, demandez à Claude d’éditer un fichier pour déclencher un hook PostToolUse. Ensuite, lisez le journal de débogage, qui montre quels hooks ont correspondu, leurs codes de sortie et leur sortie. Les sections suivantes couvrent les défaillances que vous êtes le plus susceptible de rencontrer lors du développement, et la page de dépannage a l’entrée complète pour chacune.

Un chemin de composant n’est pas trouvé

L’onglet Errors de /plugin affiche <component> path not found: <path>, par exemple commands path not found. Un chemin de composant dans votre manifeste, tel que commands, skills, agents ou hooks, ne pointe vers rien. Corrigez le chemin ou créez le répertoire, puis exécutez /reload-plugins dans la session. Voir commands path not found.

--plugin-dir à la racine d’une marketplace ne charge pas les plugins sous plugins/

--plugin-dir prend le répertoire racine du plugin, celui qui contient .claude-plugin/plugin.json et les répertoires de composants tels que skills/. Si vous le pointez à la racine d’une marketplace à la place, Claude Code ne lit pas marketplace.json, donc un plugin sous plugins/ ne se charge pas, et vous ne voyez pas d’erreur. Pointez le drapeau vers le dossier d’un plugin, ou ajoutez la marketplace. Voir l’entrée de dépannage.

Le plugin se charge mais ses skills manquent

Le répertoire skills/ est à l’intérieur de .claude-plugin/, ou une entrée skills dans le manifeste pointe vers un fichier. Déplacez skills/ à la racine du plugin, pointez chaque entrée skills vers un répertoire qui contient SKILL.md, et exécutez /reload-plugins dans la session. Voir Le plugin se charge mais ses skills manquent.

Le dialogue userConfig n’apparaît jamais

Le dialogue pour les options userConfig de votre plugin fait partie de l’installation via /plugin dans une session. Charger avec --plugin-dir ne l’affiche pas, et claude plugin install dans le shell non plus. Avec le plugin chargé, exécutez /plugin configure <plugin-name> dans la session pour l’ouvrir. Voir Le dialogue userConfig n’apparaît jamais.

Vérifier que le plugin change le comportement de Claude

Un plugin qui se charge sans erreurs peut toujours échouer à diriger Claude de la façon que vous avez l’intention. claude plugin eval, que vous exécutez dans votre shell, exécute vos cas de test avec et sans le plugin et note la différence. Voir Tester les plugins avec des evals, en commençant par Créer votre première suite d’eval.

Convertir une configuration .claude/ existante

Si vous avez déjà des skills, agents ou hooks sous le répertoire .claude/ d’un projet, vous pouvez les déplacer dans un plugin sans les réécrire. Exécutez les commandes de ces étapes à partir de la racine du projet, qui est le répertoire qui contient .claude/, car les chemins cp sont relatifs à celui-ci.
1

Créer la structure du plugin

Créez le répertoire du plugin et son dossier .claude-plugin/ à côté de .claude/. Vous pouvez déplacer le plugin n’importe où après.
Créez my-plugin/.claude-plugin/plugin.json :
my-plugin/.claude-plugin/plugin.json
2

Copier vos fichiers existants

Copiez chaque répertoire de configuration que vous avez à la racine du plugin, et ignorez la commande pour tout répertoire que vous n’avez pas.
Exécutez ls -a my-plugin pour confirmer que chaque répertoire que vous avez copié apparaît à côté de .claude-plugin.
3

Déplacer vos hooks

Si vous avez des hooks dans .claude/settings.json ou .claude/settings.local.json, créez un répertoire de hooks :
Créez my-plugin/hooks/hooks.json et copiez l’objet hooks de votre fichier de paramètres dedans. Le format est le même.Cet exemple montre la forme avec un hook qui exécute un linter sur chaque fichier que Claude écrit ou édite. Remplacez l’exemple par votre propre objet hooks.
my-plugin/hooks/hooks.json
4

Tester le plugin migré

Chargez le plugin pour une session :
Vérifiez chaque composant sous son nouveau nom :
  • Skills : exécutez /my-plugin:deploy pour un skill qui était /deploy.
  • Sous-agents : demandez à Claude d’utiliser l’agent my-plugin:reviewer pour un agent qui était reviewer.
  • Hooks : déclenchez l’événement que chaque hook correspond.
Si quelque chose manque, travaillez à travers Tester et déboguer.
Tant que les originaux sont toujours sous .claude/, ils restent chargés à côté des copies du plugin :
  • Skills et agents : les deux ensembles ne se heurtent pas, car les skills et agents du plugin portent le préfixe my-plugin:. /deploy et /my-plugin:deploy fonctionnent tous les deux, et Claude voit reviewer et my-plugin:reviewer comme deux sous-agents.
  • Hooks : les hooks n’ont pas de préfixe, donc un hook qui est à la fois dans votre fichier de paramètres et dans hooks/hooks.json s’exécute deux fois chaque fois que son événement se déclenche.
Après avoir confirmé que le plugin fonctionne, supprimez les originaux de .claude/ et supprimez l’objet hooks de votre fichier de paramètres.

Étapes suivantes