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 :
- Installer le plugin de quelqu’un d’autre : voir Installer des plugins
- Vous ne savez pas si vous avez besoin d’un plugin : voir Décider si vous avez besoin d’un plugin dans l’aperçu
- Les utilisateurs de votre plugin sont sur claude.ai ou dans Cowork : le même dossier s’installe là avec un sous-ensemble différent de composants. Voir Plugins sur claude.ai et dans Cowork
- Rien encore : suivez Créer votre premier plugin, puis Développer sans marketplace et Tester et déboguer.
- Fichiers sous
.claude/déjà présents : faites la procédure pas à pas du premier plugin une fois pour apprendre la disposition, puis suivez Convertir une configuration.claude/existante.
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.jsonet.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 skillhellosans collision.
.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é Les quatre champs font ceci :
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
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.nameest requis à l’intérieur ;emaileturlsont optionnels.
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 Ensuite, créez La ligne
skills/ qui contient un fichier SKILL.md. Créez le répertoire du skill :my-first-plugin/skills/hello/SKILL.md avec ce contenu :my-first-plugin/skills/hello/SKILL.md
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.
--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
.zipde 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.
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.zippour 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.
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.
/reload-plugins pour l’appliquer.
À partir d’une URL
Quand vous démarrezclaude à partir de votre shell, passez --plugin-url avec l’adresse d’une archive .zip, par exemple un artefact de build que votre CI publie :
/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 :
~/.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écutezclaude 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 :- 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 avec0surValidation passed. Ajoutez--strictpour é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. - Dans la session en cours, exécutez
/reload-pluginspour appliquer les modifications que vous avez apportées sur le disque. Il imprime une ligneReloaded: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. - 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. - 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 avecStatus: ✔ loadedou l’erreur de chargement. Pour inclure le plugin que vous développez, passez--plugin-diravec son chemin avantplugin list.
/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épertoireskills/ 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 Créez
.claude-plugin/ à côté de .claude/. Vous pouvez déplacer le plugin n’importe où après.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 Créez
.claude/settings.json ou .claude/settings.local.json, créez un répertoire de hooks :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:deploypour un skill qui était/deploy. - Sous-agents : demandez à Claude d’utiliser l’agent
my-plugin:reviewerpour un agent qui étaitreviewer. - Hooks : déclenchez l’événement que chaque hook correspond.
.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:./deployet/my-plugin:deployfonctionnent tous les deux, et Claude voitrevieweretmy-plugin:reviewercomme 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.jsons’exécute deux fois chaque fois que son événement se déclenche.
.claude/ et supprimez l’objet hooks de votre fichier de paramètres.
Étapes suivantes
- Composants de plugin : ajoutez des agents, des hooks, des serveurs MCP, des serveurs LSP et une configuration utilisateur à votre plugin
- Tester les plugins avec des evals : écrivez des cas d’eval et exécutez-les avec
claude plugin evalpour vérifier la fiabilité avec laquelle le plugin guide le comportement de Claude - Publier un plugin : versionnez-le, mettez-le dans une marketplace et soumettez-le à la marketplace communautaire
- Plugins sur claude.ai et dans Cowork : le même dossier de plugin s’installe sur claude.ai et dans Cowork. Certains composants sont uniquement Claude Code
- Référence du manifeste de plugin : chaque champ
plugin.json, règle de chemin et répertoire - Skills : écrivez les skills que votre plugin fournit
- Plugins d’Anthropic dans le référentiel claude-code : des exemples complets de la disposition sur cette page, tels que
feature-devetcode-review