Référence des plugins

Référence technique complète pour le système de plugins Claude Code, incluant les schémas, les commandes CLI et les spécifications des composants.

Un plugin est un répertoire autonome de composants qui étend Claude Code avec des fonctionnalités personnalisées. Les composants de plugin incluent skills, agents, hooks, serveurs MCP, serveurs LSP et moniteurs.

Référence des composants de plugin

Skills

Les plugins ajoutent des skills à Claude Code, créant des raccourcis /name que vous ou Claude pouvez invoquer.

Emplacement : répertoire skills/ ou commands/ à la racine du plugin, ou un seul fichier SKILL.md à la racine du plugin

Format de fichier : Les skills sont des répertoires avec SKILL.md ; les commandes sont de simples fichiers markdown

Structure du skill :

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

Les skills et les commandes sont automatiquement découverts lors de l'installation du plugin.

Si un plugin n'a pas de répertoire skills/ et pas de champ manifest skills, un SKILL.md à la racine du plugin est chargé comme un skill unique. Définissez le champ frontmatter name pour contrôler le nom d'invocation du skill. Sans cela, Claude Code revient au nom du répertoire d'installation, qui pour les plugins installés depuis la marketplace est une chaîne de version qui change à chaque mise à jour. Pour les plugins qui fournissent plus d'un skill, utilisez la disposition du répertoire skills/ montrée ci-dessus.

Dans les skills et commandes de plugin, les champs frontmatter booléens tels que disable-model-invocation acceptent yes, no, on, off, 1 et 0 dans n'importe quelle casse de lettre, en plus de true et false. Avant v2.1.218, Claude Code ne reconnaissait que true et false.

Pour plus de détails, consultez Skills.

Agents

Les plugins peuvent fournir des sous-agents spécialisés pour des tâches spécifiques que Claude peut invoquer automatiquement si approprié.

Emplacement : répertoire agents/ à la racine du plugin

Format de fichier : Fichiers markdown décrivant les capacités de l'agent

Structure de l'agent :

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

Les agents de plugin supportent les champs frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background et isolation. La seule valeur isolation valide est "worktree". Pour des raisons de sécurité, hooks, mcpServers et permissionMode ne sont pas supportés pour les agents fournis par les plugins.

Claude Code charge un agent de plugin même quand son frontmatter n'a pas de name ou ne s'analyse pas :

• Pas de name : Claude Code nomme l'agent d'après le fichier, donc agents/reviewer.md dans un plugin nommé my-plugin se charge comme my-plugin:reviewer
• Frontmatter qui ne s'analyse pas : Claude Code nomme l'agent d'après le fichier, utilise Agent from my-plugin plugin comme sa description, et ignore tous les champs du fichier

En contraste, Claude Code ignore un fichier d'agent de projet, utilisateur ou géré dont le frontmatter n'a pas de name ou ne s'analyse pas.

Pour trouver les fichiers dans le répertoire agents/ par défaut d'un plugin dont le frontmatter ne s'analyse pas, exécutez claude plugin validate. Le chemin que vous passez dépend de si le plugin a un manifest, et les deux exemples utilisent ./my-plugin comme répertoire du plugin :

• Un plugin avec un manifest : claude plugin validate ./my-plugin
• Un plugin sans manifest : claude plugin validate ./my-plugin/agents. Nécessite Claude Code v2.1.233 ou ultérieur.

Les agents apparaissent dans la typeahead @-mention sous leur nom scopé, tel que my-plugin:code-reviewer, une fois que le plugin est activé.

Pour plus de détails, consultez Sous-agents.

Hooks

Les plugins peuvent fournir des gestionnaires d'événements qui répondent automatiquement aux événements de Claude Code.

Emplacement : hooks/hooks.json à la racine du plugin, ou en ligne dans plugin.json

Format : Configuration JSON avec des matchers d'événements et des actions

Configuration du hook :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Les hooks de plugin répondent aux mêmes événements de cycle de vie que les hooks définis par l'utilisateur :

Types de hook :

• command : exécuter des commandes shell ou des scripts
• http : envoyer l'événement JSON comme une requête POST à une URL
• mcp_tool : appeler un outil sur un serveur MCP configuré
• prompt : évaluer un prompt avec un LLM (utilise le placeholder $ARGUMENTS pour le contexte)
• agent : exécuter un vérificateur agentic avec des outils pour les tâches de vérification complexes

Les hooks qui ciblent le serveur MCP bundlé du plugin doivent utiliser ses noms scopés. Les matchers d'outils et les champs if prennent le nom d'outil scopé mcp__plugin_<plugin-name>_<server-name>__<tool>, et le champ server d'un hook mcp_tool prend plugin:<plugin-name>:<server-name>. Un matcher écrit contre la clé de serveur nue ne se déclenche jamais. Consultez Match MCP tools et Plugin-provided MCP servers.

MCP servers

Les plugins peuvent bundler des serveurs Model Context Protocol (MCP) pour connecter Claude Code avec des outils et services externes.

Emplacement : .mcp.json à la racine du plugin, ou en ligne dans plugin.json

Format : Configuration standard du serveur MCP

Configuration du serveur MCP :

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

Comportement d'intégration :

• Les serveurs MCP de plugin démarrent automatiquement quand le plugin est activé
• Les serveurs apparaissent comme des outils MCP standard dans la boîte à outils de Claude
• Les serveurs de plugin peuvent être configurés indépendamment des serveurs MCP utilisateur
• Si vous exécutez /reload-plugins en milieu de session, Claude Code maintient les connexions actives des serveurs dont la configuration est inchangée

LSP servers

Les plugins peuvent fournir des serveurs Language Server Protocol (LSP) pour donner à Claude une intelligence de code en temps réel en travaillant sur votre base de code.

Emplacement : .lsp.json à la racine du plugin, ou en ligne dans plugin.json

Format : Configuration JSON mappant les noms de serveurs de langage à leurs configurations

Format du fichier .lsp.json :

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

En ligne dans plugin.json :

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Champs obligatoires :

Champs optionnels :

restartOnCrash et shutdownTimeout nécessitent Claude Code v2.1.205 ou ultérieur. Avant v2.1.205, le schéma de configuration acceptait les deux options mais définir l'une d'elles causait à Claude Code de sauter ce serveur LSP entièrement au démarrage, avec la raison visible uniquement dans la sortie claude --debug.

Plusieurs serveurs pour la même extension : quand plus d'un serveur LSP activé déclare la même extension de fichier dans extensionToLanguage, que les serveurs proviennent d'un plugin ou de différents plugins, le premier serveur enregistré gère les fichiers avec cette extension et les autres ne démarrent jamais. L'interface /plugin affiche un avertissement nommant le plugin dont le serveur est actif.

Serveurs qui échouent à initialiser : Claude Code ignore un serveur dont la configuration est invalide, par exemple un manquant command ou extensionToLanguage, et les autres serveurs configurés démarrent toujours. Exécutez claude --debug pour voir pourquoi un serveur a été ignoré.

Un serveur ignoré ne réclame pas ses extensions de fichier, donc un autre serveur valide qui déclare la même extension, du même plugin ou d'un plugin différent, gère toujours ces fichiers.

Envoyez la sortie de log à stderr, pas stdout : Claude Code lit le stdout d'un serveur comme des messages de protocole uniquement, et accepte les en-têtes de message jusqu'à 64 KiB et un corps de message jusqu'à 32 MiB. Claude Code déconnecte un serveur qui dépasse l'une ou l'autre limite ou écrit une sortie non-protocole à stdout, et compte la déconnexion comme un crash pour restartOnCrash et maxRestarts. Quand vous exécutez avec --debug, Claude Code écrit une erreur nommant la cause au journal de débogage.

Plugins LSP disponibles :

Installez d'abord le serveur de langage, puis installez le plugin depuis la marketplace.

Monitors

Les plugins peuvent déclarer des moniteurs de fond que Claude Code démarre automatiquement quand le plugin est actif. Chaque moniteur exécute une commande shell pour la durée de vie de la session et livre chaque ligne stdout à Claude comme une notification, donc Claude peut réagir aux entrées de log, changements de statut, ou événements sondés sans être demandé de démarrer la montre lui-même.

Les moniteurs de plugin utilisent le même mécanisme que l'outil Monitor et partagent ses contraintes de disponibilité. Ils s'exécutent uniquement dans les sessions CLI interactives, s'exécutent non-sandboxés au même niveau de confiance que les hooks, et sont ignorés sur les hôtes où l'outil Monitor est indisponible.

Emplacement : monitors/monitors.json à la racine du plugin, ou en ligne dans plugin.json

Format : Tableau JSON d'entrées de moniteur

Le monitors/monitors.json suivant surveille un point de terminaison de statut de déploiement et un journal d'erreurs local :

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Pour déclarer les moniteurs en ligne, définissez experimental.monitors dans plugin.json au même tableau. Pour charger depuis un chemin non-par défaut, définissez experimental.monitors à une chaîne de chemin relatif telle que "./config/monitors.json". Les moniteurs sont un composant expérimental.

Champs obligatoires :

Champs optionnels :

La valeur command supporte les substitutions de chemin ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} et ${CLAUDE_PROJECT_DIR}, plus n'importe quel ${ENV_VAR} de l'environnement. Préfixez la commande avec cd "${CLAUDE_PLUGIN_ROOT}" && si le script doit s'exécuter depuis le répertoire du plugin lui-même.

Une command de moniteur ne peut pas référencer les valeurs ${user_config.*}. La commande s'exécute via un shell, donc Claude Code rejette le moniteur avec une erreur au lieu de substituer la valeur. Les processus de moniteur ne reçoivent pas les variables d'environnement CLAUDE_PLUGIN_OPTION_<KEY>, donc faites en sorte que le script de moniteur lise la valeur depuis un fichier de configuration qu'il possède.

Si vous désactivez un plugin en milieu de session, Claude Code n'arrête pas les moniteurs qui sont déjà en cours d'exécution ; ils s'arrêtent quand la session se termine.

Themes

Les plugins peuvent fournir des thèmes de couleur qui apparaissent dans /theme aux côtés des présets intégrés et des thèmes locaux de l'utilisateur. Un thème est un fichier JSON dans themes/ avec un préset base et une carte overrides clairsemée de jetons de couleur. Les thèmes sont un composant expérimental.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Quand un utilisateur sélectionne un thème de plugin, Claude Code enregistre custom:<plugin-name>:<slug> dans sa configuration. Les thèmes de plugin sont en lecture seule : quand un utilisateur appuie sur Ctrl+E sur l'un d'eux dans /theme, Claude Code le copie dans ~/.claude/themes/ pour qu'ils puissent éditer la copie.

Portées d'installation des plugins

Lorsque vous installez un plugin, vous choisissez une portée qui détermine où le plugin est disponible et qui d'autre peut l'utiliser :

Les plugins utilisent le même système de portée que les autres configurations de Claude Code. Pour les instructions d'installation et les drapeaux de portée, consultez Installer des plugins. Pour une explication complète des portées, consultez Portées de configuration.

Plugins du répertoire de compétences

Tout dossier situé sous un répertoire de compétences qui contient un manifeste .claude-plugin/plugin.json est chargé en tant que plugin nommé <name>@skills-dir lors de la session suivante, sans marketplace et sans étape d'installation. Générez-en un avec plugin init. Contrairement à une installation marketplace copiée, le plugin est découvert sur place plutôt que copié dans le cache des plugins.

Un arborescence de répertoire de compétences prend en charge trois choses distinctes :

Choisir d'où le plugin se charge

Un plugin de portée projet est archivé dans le référentiel et atteint chaque collaborateur qui le clone. Parce que ce contenu provient du référentiel plutôt que de vous, il se charge uniquement après la même barrière de confiance qui régit les règles d'autorisation du projet dans .claude/settings.json, donc faire confiance à un dossier parent ou exécuter avec -p ne suffit pas, et les composants qui exécutent du code sont davantage restreints :

• Les serveurs MCP qu'il déclare passent par la même approbation par serveur qu'un .mcp.json de projet
• Les serveurs LSP ne démarrent qu'après que vous fassiez confiance à l'espace de travail
• Les moniteurs en arrière-plan ne se chargent pas

Les plugins de portée personnelle n'ont aucune de ces restrictions.

Modifier, recharger et désactiver un plugin du répertoire de compétences

Les modifications que vous apportez au SKILL.md d'une compétence prennent effet immédiatement dans la session actuelle. Les modifications apportées aux autres composants du plugin, tels que hooks/, .mcp.json, agents/ et output-styles/, ne le font pas. Exécutez /reload-plugins ou redémarrez Claude Code pour les récupérer. Voir Détection des changements en direct.

Pour arrêter le chargement d'un plugin du répertoire de compétences, supprimez son dossier ou désactivez-le par nom. Il n'y a pas d'étape uninstall car rien n'a été installé à partir d'une marketplace.

claude plugin disable my-tool@skills-dir

Plugins synchronisés depuis claude.ai

Dans Cowork et les sessions cloud, Claude Code télécharge les plugins activés pour votre compte claude.ai dans ~/.claude/plugins/synced/ dans l'environnement propre de la session et charge chacun d'eux en tant que <name>@synced, sans marketplace et sans enregistrement d'installation. Claude Code ne les charge pas dans les sessions que vous démarrez dans votre propre terminal. À l'intérieur de cet environnement Cowork ou cloud, claude plugin list affiche les copies téléchargées sous un en-tête Synced from claude.ai. Avant la v2.1.239, Claude Code chargeait ces plugins en tant que <name>@inline, l'identité que les plugins --plugin-dir utilisent.

Gérez un plugin synchronisé par l'ID <name>@synced que claude plugin list affiche :

• Désactiver un plugin : dans la session synchronisée, exécutez claude plugin disable <name>@synced, ou demandez à Claude de l'exécuter. Claude Code enregistre le choix en tant que "<name>@synced": false dans le enabledPlugins au niveau utilisateur de cet environnement. Pour réactiver le plugin, exécutez claude plugin enable <name>@synced dans la même session. Pour exclure un plugin de chaque session synchronisée, désactivez-le pour votre compte claude.ai. Pour l'exclure des sessions synchronisées d'un projet dans chaque environnement, définissez "<name>@synced": false sous enabledPlugins dans le .claude/settings.json engagé de ce projet.
• Gérer le plugin lui-même sur claude.ai : claude plugin install, update et uninstall ne s'appliquent pas à un plugin synchronisé. Pour en supprimer un, désactivez le plugin pour votre compte claude.ai ; la prochaine session synchronisée démarre sans lui.

Lorsqu'un plugin activé provenant de toute autre source, comme une installation marketplace, un plugin du répertoire de skills, ou un plugin --plugin-dir, correspond au nom d'un plugin synchronisé, Claude Code charge ce plugin et signale que la copie synchronisée n'est pas chargée. Pour utiliser la copie claude.ai à la place, désactivez votre propre copie. Avant la v2.1.239, Claude Code chargeait la copie synchronisée à la place d'une installation marketplace portant le même nom.

Schéma du manifeste du plugin

Le fichier .claude-plugin/plugin.json définit les métadonnées et la configuration de votre plugin.

Le manifeste est facultatif. S'il est omis, Claude Code découvre automatiquement les composants dans les emplacements par défaut et dérive le nom du plugin du nom du répertoire. Utilisez un manifeste lorsque vous devez fournir des métadonnées ou des chemins de composants personnalisés.

Schéma complet

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Champs obligatoires

Si vous incluez un manifeste, name est le seul champ obligatoire.

Ce nom est utilisé pour l'espace de noms des composants. Par exemple, dans l'interface utilisateur, l'agent agent-creator pour le plugin nommé plugin-dev apparaîtra comme plugin-dev:agent-creator.

Champs non reconnus

Claude Code ignore les champs de niveau supérieur qu'il ne reconnaît pas. Vous pouvez conserver les métadonnées d'un autre écosystème dans plugin.json et le plugin se charge toujours. Cela rend pratique de maintenir un seul manifeste qui sert également de manifeste d'extension VS Code ou Cursor, d'un package.json npm, ou d'un manifeste de bundle MCPB/DXT.

claude plugin validate signale les champs non reconnus comme des avertissements, pas des erreurs. Si un champ est décalé d'un ou deux caractères par rapport à un champ reconnu, l'avertissement suggère le nom probablement prévu. Un plugin avec uniquement des avertissements de champs non reconnus réussit toujours la validation et se charge au moment de l'exécution.

La façon dont Claude Code gère un champ reconnu dont la valeur a le mauvais type dépend du champ :

• La plupart des champs : le plugin ne se charge pas. Par exemple, une valeur keywords qui est une chaîne au lieu d'un tableau est une erreur de chargement, et claude plugin validate la signale comme telle.
• experimental et metadata : Claude Code ignore une valeur non-objet, et claude plugin validate signale un avertissement.

Passez --strict pour traiter les avertissements comme des erreurs. Utilisez-le dans CI pour détecter un nom de champ mal orthographié ou un champ laissé par l'outil de manifeste d'un autre avant la publication, même si le plugin se chargerait au moment de l'exécution.

claude plugin validate ./my-plugin --strict

Champs de métadonnées

Activation par défaut

Définissez defaultEnabled: false dans plugin.json pour livrer un plugin qui s'installe désactivé. L'utilisateur l'active avec claude plugin enable <plugin> ou l'interface /plugin. Utilisez ceci pour les plugins qui ajoutent un coût ou une portée auquel un utilisateur devrait s'inscrire, comme celui qui se connecte à un service externe.

defaultEnabled est le repli lorsque rien d'autre n'a décidé l'état du plugin. Deux choses prennent précédence sur lui :

• Le paramètre de l'utilisateur : une entrée pour le plugin dans enabledPlugins à n'importe quelle portée de paramètres. Une fois écrite, elle persiste à travers les mises à jour et réinstallations du plugin, donc changer defaultEnabled dans une version ultérieure ne bascule pas un utilisateur existant.
• Une exigence de dépendance : lorsqu'un plugin est requis par un autre qui est actif, Claude Code écrit true pour lui au moment de l'installation ou de l'activation. Cela lui donne un paramètre explicite, donc sa propre valeur par défaut ne s'applique plus. Voir Activer ou désactiver un plugin avec des dépendances.

Le même champ peut apparaître dans l'entrée de marketplace d'un plugin, où il prend précédence sur la valeur dans plugin.json. Voir Champs de plugin facultatifs.

Champs de chemin de composant

Composants expérimentaux

Les composants sous la clé experimental, themes et monitors, ont un schéma de manifeste qui peut changer entre les versions pendant qu'ils se stabilisent. L'endroit où vous les déclarez est une migration séparée : le niveau supérieur fonctionne toujours, claude plugin validate avertit, et une version future exigera experimental.*.

Configuration utilisateur

Le champ userConfig déclare les valeurs pour lesquelles Claude Code demande à l'utilisateur lorsque le plugin est activé. Utilisez ceci au lieu d'exiger que les utilisateurs modifient manuellement settings.json.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Les clés doivent être des identifiants valides. Chaque option prend en charge ces champs :

Chaque valeur est disponible pour la substitution comme ${user_config.KEY} dans les configurations de serveur MCP et LSP et les commandes de hook. Les valeurs non sensibles peuvent également être substituées dans le contenu des compétences et des agents. Toutes les valeurs sont exportées vers les processus de hook en tant que variables d'environnement CLAUDE_PLUGIN_OPTION_<KEY>, où <KEY> est la clé d'option en majuscules.

Les champs qui s'exécutent dans un shell rejettent ${user_config.*} : substituer une valeur configurée dans une commande shell permettrait au shell d'exécuter tout ce que cette valeur contient, donc le composant échoue avec une erreur à la place. Chaque champ rejeté a une autre façon de passer la valeur :

Avant v2.1.207, ces champs substituaient les valeurs ${user_config.KEY} ; mettez à jour les plugins qui en dépendaient.

Les valeurs non sensibles sont stockées sous la clé pluginConfigs dans votre settings.json utilisateur comme pluginConfigs[<plugin-id>].options.

Sur macOS, Claude Code stocke les valeurs sensibles dans le Keychain macOS, en revenant à ~/.claude/.credentials.json lorsque le Keychain rejette l'écriture. Sur les plates-formes sans un keychain pris en charge, il les stocke dans ~/.claude/.credentials.json. Le stockage Keychain est partagé avec les jetons OAuth et a une limite totale d'environ 2 KB, donc gardez les valeurs sensibles petites.

Claude Code lit toutes les valeurs pluginConfigs à partir de seulement trois sources de paramètres :

• Paramètres utilisateur : ~/.claude/settings.json, le fichier que l'invite au moment de l'activation écrit
• --settings : l'indicateur CLI ou les paramètres en ligne du SDK
• Paramètres gérés : politique contrôlée par l'organisation

Lorsque plusieurs sources définissent la même clé, les paramètres gérés prennent précédence, puis --settings, puis les paramètres utilisateur. La seule source que vous pouvez supprimer de cette liste est les paramètres utilisateur : passez --setting-sources sans user et Claude Code les ignore. Les paramètres gérés et --settings restent quels que soient les paramètres que vous passez. L'option settingSources du SDK définit la même liste.

Les entrées dans le .claude/settings.json ou .claude/settings.local.json d'un projet sont ignorées. Les deux fichiers vivent dans l'espace de travail, donc un référentiel cloné pourrait fournir des valeurs là, et ces valeurs s'écouleraient dans les commandes de hook de plugin, les configurations de serveur MCP, les commandes LSP et les commandes de moniteur. Avant v2.1.207, ces entrées étaient lues. La restriction est spécifique à pluginConfigs : enabledPlugins honore toujours les paramètres de projet et locaux.

Canaux

Le champ channels permet à un plugin de déclarer un ou plusieurs canaux de message qui injectent du contenu dans la conversation. Chaque canal se lie à un serveur MCP que le plugin fournit.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Le champ server est obligatoire et doit correspondre à une clé dans le mcpServers du plugin. Le userConfig optionnel par canal utilise le même schéma que le champ de niveau supérieur, permettant au plugin de demander des jetons de bot ou des ID de propriétaire lorsque le plugin est activé.

Règles de comportement des chemins

Si un chemin personnalisé remplace ou étend le répertoire par défaut du plugin dépend du champ :

• Remplace le défaut : commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Par exemple, lorsque le manifeste spécifie commands, le répertoire par défaut commands/ n'est pas analysé. Pour conserver le défaut et en ajouter plus, listez-le explicitement : "commands": ["./commands/", "./extras/"]
• S'ajoute au défaut : skills. Le répertoire par défaut skills/ est toujours analysé, et les répertoires listés dans skills sont chargés à côté de lui. Exception : pour une entrée de marketplace dont la source se résout à la racine de marketplace, déclarer des sous-répertoires spécifiques remplace l'analyse par défaut skills/
• Règles de fusion propres : hooks, serveurs MCP, et serveurs LSP. Voir chaque section pour savoir comment plusieurs sources se combinent

Lorsqu'un plugin a à la fois un dossier par défaut et la clé de manifeste correspondante, Claude Code avertit du dossier ignoré dans claude plugin list et la vue de détail /plugin. Le plugin se charge toujours en utilisant les chemins du manifeste. Claude Code n'avertit pas lorsque la clé de manifeste pointe dans le dossier par défaut, par exemple "commands": ["./commands/deploy.md"], car ce chemin nomme le dossier explicitement.

Pour tous les champs de chemin :

• Tous les chemins doivent être relatifs à la racine du plugin et commencer par ./, sauf que le champ skills accepte également "."
  • À la fois "." et "./" désignent la racine du plugin elle-même
  • Avant v2.1.221, "." échouait la validation du manifeste et le plugin ne se chargeait pas, donc utilisez "./" pour prendre en charge les versions antérieures
• Les composants des chemins personnalisés utilisent les mêmes règles de nommage et d'espace de noms
• Plusieurs chemins peuvent être spécifiés comme des tableaux
• Un chemin de compétence peut pointer vers un répertoire qui contient directement un SKILL.md, par exemple "skills": ["."] pour la racine du plugin
  • Claude Code prend le nom d'invocation de la compétence à partir du champ name du frontmatter dans SKILL.md, donc le nom reste stable quel que soit le nom du répertoire d'installation
  • Si name n'est pas défini dans le frontmatter, Claude Code revient au nom de base du répertoire

Un plugin qui a un SKILL.md à sa racine, aucun sous-répertoire skills/, et aucun champ de manifeste skills est automatiquement chargé comme un plugin à compétence unique. Vous n'avez pas besoin de définir "skills": ["./"] dans plugin.json pour cette disposition.

Exemples de chemins :

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variables d'environnement

Claude Code fournit trois variables pour référencer les chemins :

Les trois sont exportés en tant que variables d'environnement vers les processus de hook et vers les sous-processus de serveur MCP et LSP. Les champs qui les substituent en ligne dépendent du composant du plugin :

Dans les commandes de hook, utilisez la forme exec avec args afin que chaque chemin soit passé comme un argument sans guillemets. Dans les hooks de forme shell et les commandes de moniteur, enveloppez les variables entre guillemets doubles, comme dans "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Ce hook de forme shell exécute un script fourni avec un plugin :

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} change lorsque le plugin se met à jour. Le répertoire de la version précédente reste sur le disque pendant une période de grâce après une mise à jour, mais traitez-le comme éphémère et n'écrivez pas d'état là. Voir mise en cache du plugin pour la sémantique de nettoyage.

Lorsqu'un plugin se met à jour en milieu de session, les commandes de hook, les moniteurs, les serveurs MCP et les serveurs LSP continuent d'utiliser le chemin de la version précédente. Exécutez /reload-plugins pour basculer les hooks, les serveurs MCP et les serveurs LSP vers le nouveau chemin ; les moniteurs nécessitent un redémarrage de session. Dans une session sans terminal interactif, le rechargement laisse les serveurs MCP du plugin sur l'ancien chemin jusqu'à la session suivante. Pour un plugin avec une source command, Claude Code peut recharger le plugin lui-même.

Les serveurs MCP peuvent également appeler la demande roots/list pour lire les répertoires de travail de la session au moment de l'exécution. Voir ce que roots/list retourne et quand Claude Code notifie le serveur des changements.

Répertoire de données persistant

Le répertoire ${CLAUDE_PLUGIN_DATA} se résout à ~/.claude/plugins/data/{id}/, où {id} est l'identifiant du plugin avec les caractères en dehors de a-z, A-Z, 0-9, _, et - remplacés par -. Pour un plugin installé comme formatter@my-marketplace, le répertoire est ~/.claude/plugins/data/formatter-my-marketplace/.

Un usage courant est d'installer les dépendances de langage une fois et de les réutiliser à travers les sessions et les mises à jour du plugin. Utilisez-le pour les dépendances Python, les dépendances verrouillées avec Yarn ou pnpm, et les packages dont les scripts de cycle de vie doivent s'exécuter. Pour un plugin installé depuis une marketplace, vous n'en aurez peut-être pas besoin du tout : Claude Code installe automatiquement les dépendances de package Node.js éligibles lorsqu'il met en cache le plugin.

Parce que le répertoire de données survit à n'importe quelle version de plugin unique, une vérification de l'existence du répertoire seule ne peut pas détecter lorsqu'une mise à jour change le manifeste de dépendance du plugin. Le modèle recommandé compare le manifeste fourni par rapport à une copie dans le répertoire de données et réinstalle lorsqu'ils diffèrent.

Ce hook SessionStart installe node_modules à la première exécution et à nouveau chaque fois qu'une mise à jour du plugin inclut un package.json modifié :

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

Le diff sort avec un code non-zéro lorsque la copie stockée est manquante ou diffère de celle fournie, couvrant à la fois la première exécution et les mises à jour changeant les dépendances. Si npm install échoue, le rm final supprime le manifeste copié afin que la session suivante réessaye.

Les scripts fournis dans ${CLAUDE_PLUGIN_ROOT} peuvent ensuite s'exécuter contre le node_modules persistant :

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Le répertoire de données est supprimé automatiquement lorsque vous désinstallez le plugin de la dernière portée où il est installé. L'interface /plugin affiche la taille du répertoire et demande une confirmation avant de supprimer. Le CLI supprime par défaut ; passez --keep-data pour le conserver.

Mise en cache des plugins et résolution des fichiers

Les plugins sont spécifiés de deux façons :

• Via claude --plugin-dir ou claude --plugin-url, pour la durée d'une session.
• Via une marketplace, installés pour les sessions futures.

À des fins de sécurité et de vérification, Claude Code copie les plugins de marketplace dans le cache de plugins local de l'utilisateur (~/.claude/plugins/cache) plutôt que de les utiliser sur place, sauf pour les sources command en mode lien, que Claude Code utilise sur place via des liens dans l'entrée du cache.

Pour les plugins copiés, chaque version installée est un répertoire distinct dans le cache, regroupé par marketplace et plugin et nommé pour la version résolue, avec sa propre copie des fichiers du plugin et des dépendances de packages Node.js. Une dépendance résolue à partir d'une balise de version obtient un nom de répertoire avec un suffixe de commit-SHA.

Lorsque vous mettez à jour ou désinstallez un plugin, Claude Code marque le répertoire de la version précédente comme orphelin et le supprime lors d'un balayage en arrière-plan environ 14 jours plus tard. La période de grâce permet aux sessions Claude Code concurrentes qui ont déjà chargé l'ancienne version de continuer à fonctionner sans erreurs. Claude Code exécute le balayage uniquement si au moins un plugin est installé ; après avoir désinstallé votre dernier plugin, les répertoires orphelins restent sur le disque jusqu'à ce que vous installiez à nouveau un plugin.

Claude Code supprime un dossier de plugin ou de marketplace du cache uniquement lorsqu'il ne contient plus aucun répertoire ou lien symbolique. Si vous créez un lien symbolique vers une extraction de développement dans le cache en tant qu'entrée de version d'un plugin, Claude Code ne marque jamais le lien comme orphelin et ne le supprime jamais, ni les dossiers qui le contiennent. Claude Code n'écrit jamais non plus ses fichiers de suivi de version à l'intérieur de l'extraction liée.

Les outils Glob et Grep de Claude ignorent les répertoires de version orphelins lors des recherches, de sorte que les résultats de fichiers n'incluent pas le code de plugin obsolète.

Dépendances de packages Node.js

Lorsque Claude Code copie un plugin dans le cache, il installe également les dépendances de packages Node.js du plugin à cet endroit, afin que les hooks et serveurs MCP du plugin puissent les charger. Cette section couvre les packages npm et Bun qu'un plugin déclare dans son propre package.json. Pour les plugins qui dépendent d'autres plugins, voir versions de dépendances de plugins.

Claude Code exécute l'installation dans le répertoire de version copié chaque fois qu'il en crée un : lorsque vous installez un plugin, lorsque Claude Code met à jour un plugin vers une nouvelle version, et au démarrage de la session lorsqu'un plugin activé n'est pas encore en cache, par exemple sur une nouvelle machine. L'installation s'exécute uniquement lorsque le répertoire racine du plugin contient à la fois un package.json et un fichier de verrouillage pris en charge :

Si un plugin contient plus d'un de ces fichiers de verrouillage, Claude Code utilise la première correspondance, en vérifiant dans l'ordre : bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json. Claude Code ignore yarn.lock et pnpm-lock.yaml car Yarn et pnpm prennent en charge les hooks de configuration au moment de la résolution qui contournent --ignore-scripts.

Livrez un fichier de verrouillage npm pour la plus large portée. Claude Code exécute le gestionnaire de packages du fichier de verrouillage correspondant à partir du PATH de l'utilisateur et ne revient pas au fichier de verrouillage alternatif s'il est manquant. Pour un plugin distribué via une source npm, utilisez npm-shrinkwrap.json ; npm exclut package-lock.json des packages publiés.

Claude Code contraint cette installation de dépendances de sorte qu'aucun code du plugin ou de ses packages ne s'exécute pendant celle-ci, et limite la durée pendant laquelle elle peut s'exécuter :

• Résolution figée : Bun et npm installent exactement ce que le fichier de verrouillage épingle, et échouent plutôt que de re-résoudre les versions lorsque package.json et le fichier de verrouillage ne sont pas d'accord.
• Pas de scripts de cycle de vie : --ignore-scripts empêche les scripts preinstall, install et postinstall de s'exécuter, de sorte que les dépendances qui construisent des modules natifs dans ces scripts téléchargent mais ne se compilent pas pendant cette installation.
• Délai d'expiration de 60 secondes : Claude Code arrête une installation qui s'exécute plus longtemps et la traite comme échouée.

L'extraction d'un plugin lui-même à partir d'une source npm exécute npm install avec les scripts de cycle de vie activés, avant que cette installation de dépendances ne s'exécute.

Une installation échouée ou ignorée ne bloque jamais le plugin. Lorsque l'installation échoue, ou que Claude Code ignore un fichier de verrouillage yarn ou pnpm, il enregistre la raison comme un avertissement dans la sortie de débogage. Un plugin avec un package.json et aucun fichier de verrouillage est ignoré sans entrée de journal. Une installation qui expire peut laisser un arbre node_modules partiel dans la copie en cache.

Vous ne pouvez pas désactiver l'installation automatique ; aucun paramètre ou variable d'environnement ne la désactive. Dans les réseaux restreints, voir les exigences d'accès réseau pour les hôtes à autoriser.

Pour les dépendances que l'installation automatique ne peut pas fournir, telles que les packages qui ont besoin de leurs scripts de cycle de vie pour se construire, les dépendances Python, ou un plugin verrouillé avec Yarn ou pnpm, installez-les à partir d'un hook dans le répertoire de données persistantes.

Limitations de traversée de chemin

Claude Code ne permet pas à un plugin de référencer des fichiers en dehors de son propre répertoire. Il rejette un chemin de composant qui se résout en dehors de la racine du plugin, que le chemin soit déclaré dans plugin.json ou dans une entrée de marketplace. Cela couvre un chemin qui pointe en dehors du plugin tel qu'écrit, comme ../shared-utils, et un lien symbolique qui mène en dehors du plugin, autre que les liens au sein d'une marketplace.

Sur macOS et Linux, Claude Code rejette également un chemin de composant qui contient une barre oblique inverse n'importe où dedans, même lorsque le chemin reste à l'intérieur du plugin. Les composants déclarés avec des chemins de barre oblique inverse se chargent donc uniquement sous Windows. Écrivez les chemins de composant avec des barres obliques avant, comme ./commands/deploy.md.

Lorsque Claude Code rejette un chemin, il signale une erreur path escapes plugin directory et charge le plugin sans ce composant.

Claude Code ne copie pas non plus les fichiers en dehors du répertoire du plugin dans le cache lorsqu'il installe le plugin, de sorte que lorsqu'un script à l'intérieur d'un plugin copié lit un chemin au-dessus de la racine du plugin, il ne trouve pas non plus ces fichiers.

Partager des fichiers au sein d'une marketplace avec des liens symboliques

Si votre plugin doit partager des fichiers avec d'autres parties de la même marketplace, vous pouvez créer des liens symboliques à l'intérieur de votre répertoire de plugin. La façon dont un lien symbolique est traité lorsque le plugin est copié dans le cache dépend de l'endroit où sa cible se résout :

• Au sein du propre répertoire du plugin : le lien symbolique est préservé en tant que lien symbolique relatif dans le cache, de sorte qu'il continue de se résoudre à la cible copiée au moment de l'exécution.
• Ailleurs au sein de la même marketplace : le lien symbolique est déréférencé. Le contenu de la cible est copié dans le cache à sa place. Cela permet au répertoire skills/ d'un meta-plugin de créer un lien vers les compétences définies par d'autres plugins de la marketplace.
• En dehors de la marketplace : le lien symbolique est ignoré pour des raisons de sécurité. Cela empêche les plugins de tirer des fichiers hôtes arbitraires tels que les chemins système dans le cache.

Pour les plugins installés avec --plugin-dir, à partir d'un chemin local, ou à partir d'une source command en mode copie, seuls les liens symboliques qui se résolvent au sein du propre répertoire du plugin sont préservés. Tous les autres sont ignorés.

La commande suivante crée un lien à partir d'un plugin de marketplace vers une compétence partagée définie par un plugin frère. Sous Windows, utilisez mklink /D à partir d'une invite de commande élevée ou activez le mode développeur :

ln -s ../../shared-plugin/skills/foo ./skills/foo

Structure du répertoire des plugins

Disposition standard des plugins

Un plugin complet suit cette structure :

enterprise-plugin/
├── .claude-plugin/           # Répertoire de métadonnées (optionnel)
│   └── plugin.json             # manifeste du plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills en tant que fichiers .md plats
│   ├── status.md
│   └── logs.md
├── agents/                   # Définitions de sous-agents
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Scripts de flux de travail
│   └── release-audit.js
├── output-styles/            # Définitions de style de sortie
│   └── terse.md
├── themes/                   # Définitions de thème de couleur
│   └── dracula.json
├── monitors/                 # Configurations de moniteur en arrière-plan
│   └── monitors.json
├── hooks/                    # Configurations de hooks
│   ├── hooks.json           # Configuration principale des hooks
│   └── security-hooks.json  # Hooks supplémentaires
├── bin/                      # Exécutables du plugin ajoutés à PATH
│   └── my-tool               # Invocable en tant que commande nue dans l'outil Bash
├── settings.json            # Paramètres par défaut du plugin
├── .mcp.json                # Définitions du serveur MCP
├── .lsp.json                # Configurations du serveur LSP
├── scripts/                 # Scripts de hooks et utilitaires
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Fichier de licence
└── CHANGELOG.md             # Historique des versions

Un fichier CLAUDE.md à la racine du plugin n'est pas chargé en tant que contexte de projet. Les plugins contribuent au contexte par le biais de skills, d'agents et de hooks plutôt que par CLAUDE.md. Pour livrer des instructions qui se chargent dans le contexte de Claude, mettez-les dans un skill.

Référence des emplacements de fichiers

Référence des commandes CLI

Claude Code fournit des commandes CLI pour la gestion non-interactive des plugins, utiles pour les scripts et l'automatisation.

plugin init

Créez un nouveau plugin dans ~/.claude/skills/<name>/. À la prochaine session Claude Code, il se charge automatiquement en tant que <name>@skills-dir et apparaît dans /plugin et claude plugin list sans étape d'installation.

Consultez Plugins du répertoire de compétences pour les exigences de portée et de confiance.

claude plugin init <name> [options]

La commande prend ces arguments :

• <name> : Nom du plugin. Devient l'espace de noms de la compétence et le nom du répertoire sous ~/.claude/skills/, il ne peut donc pas contenir d'espaces ou de séparateurs de chemin.

La commande accepte ces options :

claude plugin new est un alias pour cette commande.

Chaque valeur --with ajoute un fichier de démarrage pour ce composant, prêt à être modifié :

Le plugin créé utilise la source @skills-dir plutôt qu'une marketplace. Les administrateurs peuvent bloquer cette source avec strictKnownMarketplaces ou en ajoutant {"source": "skills-dir"} à blockedMarketplaces dans les paramètres gérés. Lorsqu'elle est bloquée, plugin init échoue avant d'écrire.

Ces exemples montrent les invocations courantes :

# Créer un plugin minimal
claude plugin init my-helper

# Créer avec des dossiers de compétences et de hooks
claude plugin init my-helper --with skills hooks

# Remplacer un scaffold existant
claude plugin init my-helper --force

plugin install

Installez un plugin à partir des marketplaces disponibles.

claude plugin install <plugin> [options]

La commande prend ces arguments :

• <plugin> : Nom du plugin ou plugin-name@marketplace-name pour une marketplace spécifique

La commande accepte ces options :

La portée détermine quel fichier de paramètres le plugin installé est ajouté à. Par exemple, --scope project écrit dans enabledPlugins dans .claude/settings.json, rendant le plugin disponible pour tous ceux qui clonent le référentiel du projet.

Avec --json, la dernière ligne de stdout est un objet JSON. Analysez uniquement cette ligne, car Claude Code imprime toute commande que la marketplace déclare avant elle. Trois champs sont toujours présents :

• command : la sous-commande qui a été exécutée, comme install
• outcome : ok ou failed
• message : une description lisible par l'homme du résultat

D'autres champs, tels que pluginId, scope, et failureCode, n'apparaissent que lorsqu'ils s'appliquent. L'option --json sur plugin uninstall, plugin update, plugin enable, et plugin disable imprime le même objet avec les propres champs de cette sous-commande. Une erreur d'utilisation, comme un --scope invalide, n'imprime aucune ligne de résultat et quitte 1 avec la raison sur stderr.

Ces exemples montrent les invocations courantes :

# Installer dans la portée utilisateur (par défaut)
claude plugin install formatter@my-marketplace

# Installer dans la portée du projet (partagé avec l'équipe)
claude plugin install formatter@my-marketplace --scope project

# Installer dans la portée locale (non partagé avec l'équipe)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Supprimez un plugin installé.

claude plugin uninstall <plugin> [options]

La commande prend ces arguments :

• <plugin> : Nom du plugin ou plugin-name@marketplace-name

La commande accepte ces options :

claude plugin remove et claude plugin rm sont des alias pour cette commande.

Par défaut, la désinstallation de la dernière portée restante supprime également le répertoire ${CLAUDE_PLUGIN_DATA} du plugin. Utilisez --keep-data pour le préserver, par exemple lors de la réinstallation après avoir testé une nouvelle version.

plugin prune

Supprimez les dépendances de plugin auto-installées qui ne sont plus requises par aucun plugin installé. Les dépendances que Claude Code a intégrées pour satisfaire le champ dependencies d'un autre plugin sont supprimées ; les plugins que vous avez installés directement ne sont jamais touchés.

claude plugin prune [options]

La commande accepte ces options :

claude plugin autoremove est un alias pour cette commande.

La commande liste les dépendances orphelines et demande une confirmation avant de les supprimer. Pour supprimer un plugin et nettoyer ses dépendances en une seule étape, exécutez claude plugin uninstall <plugin> --prune.

plugin enable

Activez un plugin désactivé. Lorsque la cible est installée à partir d'une marketplace et déclare des dépendances, Claude Code les active transitivement à la même portée. La commande échoue dans les conditions que Activer ou désactiver un plugin avec des dépendances énumère.

claude plugin enable <plugin> [options]

La commande prend ces arguments :

• <plugin> : Nom du plugin ou plugin-name@marketplace-name

La commande accepte ces options :

plugin disable

Désactivez un plugin sans le désinstaller. Lorsque la cible est installée à partir d'une marketplace, la commande échoue si un autre plugin activé en dépend. Le message d'erreur inclut une commande chaînée qui désactive d'abord chaque dépendant.

claude plugin disable [plugin] [options]

La commande prend ces arguments :

• [plugin] : Nom du plugin ou plugin-name@marketplace-name. Optionnel lors de l'utilisation de --all

La commande accepte ces options :

plugin update

Mettez à jour un plugin vers la dernière version.

claude plugin update <plugin> [options]

La commande prend ces arguments :

• <plugin> : Nom du plugin ou plugin-name@marketplace-name

La commande accepte ces options :

plugin list

Listez les plugins installés avec leur version, leur marketplace source et leur statut d'activation.

claude plugin list [options]

La commande accepte ces options :

Dans une session interactive, /plugin list imprime un listage similaire en ligne, mais il couvre uniquement les plugins installés depuis une marketplace :

• Les plugins chargés à partir des répertoires de compétences apparaissent dans l'interface /plugin et dans claude plugin list, mais pas dans la sortie en ligne /plugin list.
• Sur Claude Code v2.1.239 ou ultérieur, les plugins synchronisés depuis claude.ai apparaissent dans claude plugin list lorsque vous l'exécutez dans l'environnement où une session synchronisée les a téléchargés. Ils n'apparaissent pas dans la sortie en ligne /plugin list.
• Les plugins chargés pour la session avec --plugin-dir ou --plugin-url apparaissent dans l'interface /plugin, et dans claude plugin list uniquement lorsque le même drapeau précède la sous-commande, comme dans claude --plugin-dir <dir> plugin list. Seul le nom du drapeau indique leur emplacement, donc un claude plugin list nu ne peut pas les trouver, contrairement aux plugins synchronisés et aux plugins du répertoire de compétences, dont les répertoires fixes sont analysés par Claude Code.

La forme interactive accepte --enabled ou --disabled pour afficher uniquement les plugins dans cet état, et ls comme raccourci pour list.

plugin details

Affichez l'inventaire des composants d'un plugin et le coût en jetons projeté. La sortie énumère tous les composants que le plugin contribue, regroupés en tant que Compétences, Agents, Hooks, serveurs MCP et serveurs LSP, ainsi qu'une estimation du nombre de jetons qu'il ajoute à chaque session. Le groupe Compétences inclut à la fois les entrées skills/ et commands/.

claude plugin details <name>

La commande prend ces arguments :

• <name> : Nom du plugin ou plugin-name@marketplace-name

La commande accepte ces options :

La sortie affiche deux chiffres de coût pour chaque composant :

• Toujours actif : jetons ajoutés à chaque session par le texte de listage du plugin, comme les descriptions de compétences, les descriptions d'agents et les noms de commandes, indépendamment du fait qu'un composant se déclenche ou non.
• À l'invocation : jetons qu'un composant coûte lorsqu'il se déclenche. Affiché par composant, pas comme un total de plugin, car une session typique n'invoque qu'un sous-ensemble de composants.

Cet exemple montre à quoi ressemble la sortie pour un plugin avec deux compétences :

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

Le total toujours actif est calculé via l'API count_tokens pour votre modèle actif. Les nombres par composant sont proportionnellement mis à l'échelle à partir de ce total. Si l'API est inaccessible, la commande revient à une estimation basée sur les caractères.

plugin validate

Vérifiez un plugin ou une marketplace pour les erreurs de syntaxe et de schéma avant la publication.

La commande quitte 0 lorsque la validation réussit, 1 lorsqu'elle échoue, et 2 lorsque l'exécution de la validation elle-même échoue, par exemple lorsque le chemin que vous transmettez est illisible.

claude plugin validate <path> [options]

La commande prend ces arguments :

• <path> : Chemin vers un répertoire de plugin ou un répertoire de marketplace. Consultez Valider un plugin ou un répertoire sans manifeste pour savoir quels fichiers une exécution de plugin couvre.

La commande accepte ces options :

Avec --json, Claude Code écrit le rapport sur stdout en tant qu'un objet JSON avec ces champs de niveau supérieur :

• success : le même verdict que le code de sortie donne
• strict : si l'exécution a traité les avertissements comme des erreurs
• target : le chemin résolu que Claude Code a validé
• manifest : le propre résultat du manifeste, ou null pour une exécution sans manifeste
• contents : résultats par fichier, chacun nommant son file et portant des tableaux errors, warnings, et notes

À la sortie 2, la commande n'écrit rien sur stdout ; le message d'erreur va à stderr.

Dans une session interactive, /plugin validate <path> exécute les mêmes vérifications en ligne.

plugin eval

Exécutez les cas d'évaluation d'un plugin et rapportez les résultats notés. Nécessite Claude Code v2.1.269 ou ultérieur. Chaque cas est une invite plus des évaluateurs ; Claude Code l'exécute plusieurs fois dans une session isolée avec uniquement le plugin cible chargé, et par défaut aussi sans le plugin afin que le rapport montre la différence. Consultez Tester les plugins avec des évaluations pour le format des cas, les évaluateurs, les résultats et l'utilisation en CI.

claude plugin eval [target] [options]

La target optionnelle est un répertoire de plugin, un seul fichier prompt.md ou case.yaml, un plugin installé en tant que name ou name@marketplace, ou name@skills-dir, et par défaut le répertoire courant. Mettez-le avant --tag, --allow-tools, et --json.

Ce tableau énumère les options que la plupart des exécutions utilisent. Exécutez claude plugin eval --help pour l'ensemble complet, y compris --case, --tag, --output-dir, --report, --allow-real-servers, --keep-temp, et --verbose.

La commande quitte 0 lorsque chaque cas respecte le seuil, 1 sur un cas défaillant, une erreur de chargement, ou un répertoire de plugin non approuvé, 2 sur une exécution partielle, 130 lorsqu'elle est interrompue, et 143 lorsqu'elle est terminée. Consultez Exécuter les évaluations en CI.

plugin eval init

Créez une suite d'évaluation pour le plugin dans le répertoire courant. Nécessite Claude Code v2.1.269 ou ultérieur. Dans un terminal, cela démarre une interview de création qui lit le plugin, propose des cas et des évaluateurs, les teste, et écrit les fichiers. Avec --bare, ou sans terminal, il écrit un modèle de cas unique vierge à la place. Exécutez depuis une session Claude Code interactive, il imprime les instructions d'interview pour que cette session suive plutôt que d'écrire un modèle. Consultez Créer votre première suite d'évaluation.

claude plugin eval init [name] [options]

Le name optionnel est un nom de cas : l'interview n'en a pas besoin, tandis que --bare et le chemin du modèle sans terminal l'exigent. Il accepte ces options :

plugin tag

Créez une balise git de version pour un plugin. Par défaut, la commande balise le plugin dans le répertoire courant ; transmettez un chemin pour baliser un plugin ailleurs. Consultez Baliser les versions de plugin.

claude plugin tag [path] [options]

La commande prend ces arguments :

• [path] : Chemin vers le répertoire du plugin. Par défaut, le répertoire courant.

La commande accepte ces options :

Outils de débogage et de développement

Commandes de débogage

Utilisez claude --debug pour voir les détails du chargement des plugins :

Cela affiche :

• Les plugins en cours de chargement
• Les erreurs dans les manifestes de plugins
• L'enregistrement des skills, agents et hooks
• L'initialisation du serveur MCP

Problèmes courants

Exemples de messages d'erreur

Erreurs de validation de manifeste :

• Invalid JSON syntax: Unexpected token } in JSON at position 142 : vérifiez les virgules manquantes, les virgules supplémentaires ou les chaînes non citées
• Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined : un champ obligatoire est manquant
• Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ... : erreur de syntaxe JSON. Avant v2.1.246, Claude Code produisait également cette erreur pour un plugin.json enregistré en UTF-8 avec une marque d'ordre des octets (BOM), même lorsque le JSON était par ailleurs valide.

Erreurs de chargement de plugin :

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories. : le chemin de la commande existe mais ne contient aucun fichier de commande valide
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path. : le chemin source dans marketplace.json pointe vers un répertoire inexistant
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components. : supprimez les définitions de composants en double ou supprimez strict: false dans l'entrée marketplace

Dépannage des hooks

Le script du hook ne s'exécute pas :

1. Vérifiez que le script est exécutable : chmod +x ./scripts/your-script.sh
2. Vérifiez la ligne shebang : La première ligne doit être #!/bin/bash ou #!/usr/bin/env bash
3. Vérifiez que le chemin utilise ${CLAUDE_PLUGIN_ROOT} : "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Testez le script manuellement : ./scripts/your-script.sh

Le hook ne se déclenche pas sur les événements attendus :

1. Vérifiez que le nom de l'événement est correct (sensible à la casse) : PostToolUse, pas postToolUse
2. Vérifiez que le motif du matcher correspond à vos outils : "matcher": "Write|Edit" pour les opérations de fichier
3. Confirmez que le type de hook est valide : command, http, mcp_tool, prompt ou agent

Dépannage du serveur MCP

Le serveur ne démarre pas :

1. Vérifiez que la commande existe et est exécutable
2. Vérifiez que tous les chemins utilisent la variable ${CLAUDE_PLUGIN_ROOT}
3. Vérifiez les journaux du serveur MCP : claude --debug affiche les erreurs d'initialisation
4. Testez le serveur manuellement en dehors de Claude Code

Les outils du serveur n'apparaissent pas :

1. Assurez-vous que le serveur est correctement configuré dans .mcp.json ou plugin.json
2. Vérifiez que le serveur implémente correctement le protocole MCP
3. Vérifiez les délais d'expiration de la connexion dans la sortie de débogage

Erreurs de structure de répertoire

Symptômes : Le plugin se charge mais les composants (skills, agents, hooks) sont manquants.

Structure correcte : Les composants doivent être à la racine du plugin, pas à l'intérieur de .claude-plugin/. Seul plugin.json appartient à .claude-plugin/.

Liste de contrôle de débogage :

1. Exécutez claude --debug et recherchez les messages « loading plugin »
2. Vérifiez que chaque répertoire de composant est listé dans la sortie de débogage
3. Vérifiez que les permissions de fichier permettent de lire les fichiers du plugin

Référence de distribution et de versioning

Gestion des versions

Claude Code utilise la version du plugin comme clé de cache qui détermine si une mise à jour est disponible. Lorsque vous exécutez /plugin update ou que la mise à jour automatique se déclenche, Claude Code calcule la version actuelle et ignore la mise à jour si elle correspond à celle déjà installée.

Pour chaque type de source sauf command, Claude Code résout la version à partir du premier de ces éléments qui est défini :

1. Le champ version dans le fichier plugin.json du plugin
2. Le champ version dans l'entrée marketplace du plugin dans marketplace.json
3. Le SHA du commit git du plugin, pour les sources github, url, git-subdir et relative-path dans une marketplace hébergée sur git
4. Le digest SHA-256, pour les sources archive : le pin sha256 dans l'entrée marketplace, ou le digest du fichier téléchargé lorsque vous ne définissez aucun pin. Claude Code le raccourcit aux 12 premiers caractères
5. unknown, pour les sources npm ou les répertoires locaux ne se trouvant pas dans un dépôt git

Pour une source command, Claude Code dérive toujours la version à partir de ce que la commande a produit : un hash de contenu de 12 caractères seul, ou ajouté à la version plugin.json sous la forme <version>-<hash> lorsqu'une version est définie. Claude Code ignore le champ version de l'entrée marketplace pour les sources command. Une commande dont la sortie hachée change produit donc une nouvelle version, même lorsque la chaîne de version créée reste la même. En mode lien, le hash couvre le chemin réel du répertoire imprimé et ses entrées de niveau supérieur plutôt que le contenu des fichiers.

Pour ces types de sources, cela vous donne trois façons de versionner un plugin :

Si vous utilisez des versions explicites, suivez le versioning sémantique (MAJOR.MINOR.PATCH) : augmentez MAJOR pour les modifications incompatibles, MINOR pour les nouvelles fonctionnalités, PATCH pour les corrections de bogues. Documentez les modifications dans un fichier CHANGELOG.md.

Voir aussi

• Plugins - Tutoriels et utilisation pratique
• Marketplaces de plugins - Création et gestion des marketplaces
• Skills - Détails du développement des skills
• Subagents - Configuration et capacités des agents
• Hooks - Gestion des événements et automatisation
• MCP - Intégration des outils externes
• Paramètres - Options de configuration pour les plugins