SpyBara
Go Premium

plugins-reference.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 139 additions and 69 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Sun 13 21:00 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

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 :

Événement Quand il se déclenche
SessionStart Quand une session commence ou reprend
Setup Quand vous démarrez Claude Code avec --init-only, ou avec --init ou --maintenance en mode -p. Pour une préparation unique en CI ou dans les scripts
UserPromptSubmit Quand vous soumettez une invite, avant que Claude la traite
UserPromptExpansion Quand une commande tapée par l'utilisateur se développe en une invite, avant qu'elle n'atteigne Claude. Peut bloquer l'expansion
PreToolUse Avant qu'un appel d'outil s'exécute. Peut le bloquer
PermissionRequest Quand un appel d'outil nécessite une décision de permission
PermissionDenied Quand le mode automatique refuse un appel d'outil, y compris les refus sans verdict du classificateur. Utilisez la sortie JSON hookSpecificOutput.retry: true pour indiquer au modèle qu'il peut réessayer l'appel d'outil refusé. Claude Code ignore retry quand le classificateur n'a produit aucun verdict
PostToolUse Après qu'un appel d'outil réussisse
PostToolUseFailure Après qu'un appel d'outil échoue
PostToolBatch Après qu'un lot complet d'appels d'outils parallèles se résout, avant l'appel du modèle suivant
Notification Quand Claude Code envoie une notification
MessageDisplay Pendant que le texte du message assistant s'affiche
SubagentStart Quand un sous-agent est généré
SubagentStop Quand un sous-agent se termine
TaskCreated Quand une tâche est en cours de création via TaskCreate
TaskCompleted Quand une tâche est marquée comme complétée
Stop Quand Claude finit de répondre
StopFailure Quand le tour se termine en raison d'une erreur API
TeammateIdle Quand un coéquipier d'une équipe d'agents est sur le point de devenir inactif
InstructionsLoaded Quand un fichier CLAUDE.md ou .claude/rules/*.md est chargé dans le contexte. Se déclenche au démarrage de la session et quand les fichiers sont chargés paresseusement pendant une session
ConfigChange Quand un fichier de configuration change pendant une session
CwdChanged Quand le répertoire de travail change, par exemple quand Claude exécute une commande cd. Utile pour la gestion réactive de l'environnement avec des outils comme direnv
DirectoryAdded Quand un répertoire de travail est ajouté en milieu de session via /add-dir ou la demande de contrôle SDK register_repo_root
FileChanged Quand un fichier surveillé change sur le disque. Le champ matcher spécifie les noms de fichiers à surveiller
WorktreeCreate Quand un worktree est en cours de création via --worktree, isolation: "worktree", ou pour une session en arrière-plan. Remplace le comportement git par défaut
WorktreeRemove Quand un worktree est supprimé à la sortie de la session, quand un sous-agent se termine, ou quand vous supprimez une session en arrière-plan
PreCompact Avant la compaction du contexte
PostCompact Après la compaction du contexte est complétée
PreModelSwitch Avant que Claude Code applique un changement de modèle que vous ou un client avez demandé. Peut bloquer le changement
PostModelSwitch Après que le modèle de la session change, y compris les changements que Claude Code effectue de lui-même, comme la restauration du modèle quand vous reprenez une session
Elicitation Quand un serveur MCP demande une entrée utilisateur pendant un appel d'outil
ElicitationResult Après qu'un utilisateur réponde à une élicitation MCP, avant que la réponse soit renvoyée au serveur
SessionEnd Quand une session se termine

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 :

Field Description
command Le binaire LSP à exécuter (doit être dans PATH)
extensionToLanguage Mappe les extensions de fichier aux identifiants de langage

Champs optionnels :

Field Description
args Arguments de ligne de commande pour le serveur LSP
transport Transport de communication : stdio (par défaut) ou socket. Claude Code accepte socket mais exécute chaque serveur sur stdio, donc les règles du protocole stdout s'appliquent à tous les serveurs
env Variables d'environnement à définir au démarrage du serveur
initializationOptions Options passées au serveur lors de l'initialisation
settings Paramètres passés via workspace/didChangeConfiguration
workspaceFolder Chemin du dossier d'espace de travail pour le serveur
startupTimeout Temps maximum d'attente du démarrage du serveur (millisecondes)
shutdownTimeout Temps maximum d'attente de l'arrêt gracieux (millisecondes). Quand le délai d'attente s'écoule, Claude Code termine le processus du serveur. Quand non défini, aucun délai d'attente ne s'applique
restartOnCrash Si le serveur doit redémarrer après un crash. Par défaut true. Définissez à false pour laisser un serveur crashé arrêté au lieu de le redémarrer
maxRestarts Nombre maximum de tentatives de redémarrage avant d'abandonner
diagnostics Si les diagnostics doivent être poussés dans le contexte de Claude après les éditions (par défaut true). Définissez à false pour garder la navigation de code mais supprimer l'injection automatique de diagnostics.

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 :

Plugin Language server Install command
pyright-lsp Pyright (Python) pip install pyright ou npm install -g pyright
typescript-lsp TypeScript Language Server npm install -g typescript-language-server typescript
rust-analyzer-lsp rust-analyzer Voir l'installation de rust-analyzer

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 :

Field Description
name Identifiant unique au sein du plugin. Empêche les processus dupliqués quand le plugin se recharge ou un skill est invoqué à nouveau
command Commande shell exécutée comme un processus de fond persistant dans le répertoire de travail de la session
description Résumé court de ce qui est surveillé. Affiché dans le panneau de tâches et dans les résumés de notification

Champs optionnels :

Field Description
when Contrôle quand le moniteur démarre. "always" le démarre au démarrage de la session et au rechargement du plugin, et est la valeur par défaut. "on-skill-invoke:<skill-name>" le démarre la première fois que le skill nommé dans ce plugin est dispatché

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 :

Portée Fichier de paramètres Cas d'usage
user ~/.claude/settings.json Plugins personnels disponibles dans tous les projets (par défaut)
project .claude/settings.json Plugins d'équipe partagés via le contrôle de version
local .claude/settings.local.json Plugins spécifiques au projet, ignorés par git lorsque Claude Code enregistre un paramètre
managed Paramètres gérés Plugins gérés (lecture seule, mise à jour uniquement)

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 :

Ce que vous avez Ce que c'est
<skills-dir>/foo/SKILL.md sans manifeste Une simple compétence nommée foo
<skills-dir>/foo/.claude-plugin/plugin.json Un plugin foo@skills-dir, qui peut regrouper ses propres compétences, agents, hooks et bien plus
<plugin>/skills/bar/SKILL.md Une compétence bar empaquetée à l'intérieur d'un plugin

Choisir d'où le plugin se charge

Répertoire de compétences Portée Charge
~/.claude/skills/ personnel Dans chaque projet, puisque l'emplacement vous appartient uniquement
<cwd>/.claude/skills/ projet Uniquement après que vous acceptiez la boîte de dialogue de confiance de l'espace de travail pour ce dossier

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 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.

Champ Type Description Exemple
name string Identifiant unique en kebab-case, sans espaces, caractères de contrôle ou caractères de formatage bidirectionnel. Lorsqu'une entrée de marketplace répertorie le plugin sous un nom différent, le nom de l'entrée de marketplace est celui utilisé par les clés enabledPlugins et /plugin "deployment-tools"

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

Champ Type Description Exemple
$schema string URL du schéma JSON pour l'autocomplétion et la validation de l'éditeur. Claude Code ignore ce champ au moment du chargement. "https://json.schemastore.org/claude-code-plugin-manifest.json"
displayName string Nom lisible par l'homme affiché dans le sélecteur /plugin et autres surfaces d'interface utilisateur. Pour un plugin installé depuis une marketplace, un displayName sur l'entrée de marketplace prend précédence sur cette valeur. Lorsqu'aucun nom d'affichage n'est défini dans l'un ou l'autre endroit, les utilisateurs voient name. Contrairement à name, peut contenir des espaces et n'importe quelle casse. Non utilisé pour l'espace de noms ou la recherche. "Deployment Tools"
version string Facultatif. Version sémantique. La définition de ceci épingle le plugin à cette chaîne de version, de sorte que les utilisateurs ne reçoivent des mises à jour que lorsque vous la modifiez, sauf pour une command source ; voir Gestion des versions. S'il est également défini dans l'entrée de marketplace, plugin.json gagne. S'il est omis, la version provient de la source suivante dans Gestion des versions. "2.1.0"
description string Brève explication de l'objectif du plugin "Deployment automation tools"
author object Informations sur l'auteur {"name": "Dev Team", "email": "dev@company.com"}
homepage string URL de documentation "https://docs.example.com"
repository string URL du code source "https://github.com/user/plugin"
license string Identifiant de licence "MIT", "Apache-2.0"
keywords array Balises de découverte ["deployment", "ci-cd"]
metadata object Objet de forme libre pour vos propres données, telles que les champs d'habilitation ou de catalogue. Claude Code ne le lit pas, donc les valeurs n'affectent jamais le comportement du plugin. Claude Code ignore une valeur non-objet, et claude plugin validate la signale comme un avertissement. Avant v2.1.222, Claude Code traitait la clé comme un champ non reconnu. {"catalogId": "cat-123"}
defaultEnabled boolean Si le plugin démarre dans un état activé lorsque l'utilisateur n'en a pas défini un. Par défaut true. Voir Activation par défaut. false

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

Champ Type Description Exemple
skills string|array Répertoires de compétences personnalisés contenant <name>/SKILL.md. S'ajoute à l'analyse par défaut skills/. Voir Règles de comportement des chemins pour l'exception de racine de marketplace "./custom/skills/"
commands string|array Fichiers de compétences .md plats personnalisés ou répertoires (remplace le défaut commands/) "./custom/cmd.md" ou ["./cmd1.md"]
agents string|array Fichiers d'agent personnalisés (remplace le défaut agents/) "./custom/agents/reviewer.md"
workflows string|array Fichiers ou répertoires de scripts workflow personnalisés (remplace le défaut workflows/) "./custom/workflows/"
hooks string|array|object Chemins de configuration de hooks ou configuration en ligne "./my-extra-hooks.json"
mcpServers string|array|object Chemins de configuration MCP ou configuration en ligne "./my-extra-mcp-config.json"
outputStyles string|array Fichiers/répertoires de style de sortie personnalisés (remplace le défaut output-styles/) "./styles/"
lspServers string|array|object Configurations du Language Server Protocol pour l'intelligence du code (aller à la définition, trouver les références, etc.) "./.lsp.json"
experimental.themes string|array Fichiers/répertoires de thème de couleur (remplace le défaut themes/). Voir Thèmes "./themes/"
experimental.monitors string|array Configurations de Monitor en arrière-plan qui démarrent automatiquement lorsque le plugin est actif. Voir Moniteurs "./monitors.json"
experimental.evals string|array Répertoire sous la racine du plugin qui contient les cas d'évaluation du plugin, lorsqu'il n'est pas le défaut evals/. claude plugin eval --eval-dir le remplace "quality/evals"
userConfig object Valeurs configurables par l'utilisateur demandées au moment de l'activation. Voir Configuration utilisateur Voir ci-dessous
channels array Déclarations de canal pour l'injection de messages (style Telegram, Slack, Discord). Voir Canaux Voir ci-dessous
dependencies array Autres plugins que ce plugin nécessite, éventuellement avec des contraintes de version semver. Voir Contraindre les versions de dépendance du plugin [{ "name": "secrets-vault", "version": "~2.1.0" }]

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 :

Champ Obligatoire Description
type Oui L'un de string, number, boolean, directory, ou file
title Oui Étiquette affichée dans la boîte de dialogue de configuration
description Oui Texte d'aide affiché sous le champ
sensitive Non Si true, masque l'entrée et stocke la valeur dans le stockage sécurisé au lieu de settings.json
required Non Si true, la validation échoue lorsque le champ est vide
default Non Valeur utilisée lorsque l'utilisateur ne fournit rien
multiple Non Pour le type string, autoriser un tableau de chaînes
min / max Non Limites pour le type number

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 :

Champ rejeté Comment passer la valeur
Commandes de hook de forme shell Utilisez la forme exec avec args, ou lisez CLAUDE_PLUGIN_OPTION_<KEY> à partir de l'environnement du hook
Commandes Monitor Lisez la valeur à partir d'un fichier de configuration dans le script
MCP headersHelper Lisez la valeur à partir d'un fichier de configuration dans le script

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 :

Variable Se résout à Utilisez-la pour
${CLAUDE_PLUGIN_ROOT} Chemin absolu vers le répertoire d'installation du plugin Scripts, binaires et fichiers de configuration fournis avec le plugin
${CLAUDE_PLUGIN_DATA} Répertoire persistant qui survit aux mises à jour du plugin, créé à la première référence Dépendances installées telles que node_modules ou environnements virtuels Python, code généré et caches
${CLAUDE_PROJECT_DIR} La racine du projet Scripts et fichiers de configuration locaux au projet

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 :

Composant du plugin Champs où les espaces réservés se résolvent
Contenu des compétences et des agents N'importe où l'espace réservé apparaît
Commandes de hook et de moniteur N'importe où l'espace réservé apparaît
Serveurs MCP stdio command, args, env
Serveurs MCP http, sse, ws url, headers, headersHelper
Serveurs LSP command, args, env, workspaceFolder

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 :

Fichier de verrouillage Commande
bun.lock ou bun.lockb bun install --frozen-lockfile --ignore-scripts
npm-shrinkwrap.json ou package-lock.json npm ci --ignore-scripts

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.

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

Composant Emplacement par défaut Objectif
Manifeste .claude-plugin/plugin.json Métadonnées et configuration du plugin (optionnel)
Skills skills/ Skills avec la structure <name>/SKILL.md
Commandes commands/ Skills en tant que fichiers Markdown plats. Utilisez skills/ pour les nouveaux plugins
Agents agents/ Fichiers Markdown de sous-agents
Flux de travail workflows/ Fichiers de script de flux de travail
Styles de sortie output-styles/ Définitions de style de sortie
Thèmes themes/ Définitions de thème de couleur
Hooks hooks/hooks.json Configuration des hooks
Serveurs MCP .mcp.json Définitions du serveur MCP
Serveurs LSP .lsp.json Configurations du serveur de langage
Moniteurs monitors/monitors.json Configurations de moniteur en arrière-plan
Exécutables bin/ Exécutables ajoutés au PATH de l'outil Bash et invocables en tant que commandes nues tandis que le plugin est activé. Vous ne pouvez pas inclure ce répertoire dans un plugin que vous distribuez via les paramètres de l'organisation claude.ai
Paramètres settings.json Configuration par défaut appliquée lorsque le plugin est activé. Seules les clés agent et subagentStatusLine sont prises en charge

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 :

Option Description Par défaut
--description <text> Description du manifeste
--author <name> Nom de l'auteur git config user.name
--author-email <email> E-mail de l'auteur git config user.email
--with <components...> Créez également des dossiers de composants. Valeurs valides : skills, agents, hooks, mcp, lsp, output-style, channel
-f, --force Remplacez un .claude-plugin/ existant à la cible
-h, --help Afficher l'aide pour la commande

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é :

Composant Ce qu'il crée
skills Une compétence supplémentaire nommée <name>:example à côté de celle par défaut
agents Une définition de sous-agent agents/
hooks Un hooks/hooks.json avec un gestionnaire d'événements exemple
mcp Un .mcp.json avec des exemples de serveur HTTP et stdio
lsp Un exemple .lsp.json de serveur de langage
output-style Un output-styles/<name>.md qui s'applique automatiquement lorsque le plugin est activé
channel Un canal basé sur MCP : un serveur stdio (server.ts), son .mcp.json, et un package.json

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 :

Option Description Par défaut
-s, --scope <scope> Portée d'installation : user, project, ou local user
--config <key=value> Définissez une option userConfig déclarée dans le manifeste du plugin. Répétez le drapeau pour définir plusieurs options
-y, --yes Acceptez une commande que la marketplace du plugin déclare, sans l'invite de confirmation : la commande qui produit un plugin avec une command source, ou le headersHelper qui authentifie un téléchargement d'archive. Accepter un headersHelper nécessite Claude Code v2.1.238 ou ultérieur. Claude Code imprime toujours la commande en premier. Requis lorsque stdin ou stdout n'est pas un TTY. N'a aucun effet dans une session Claude Code, exécutez donc la commande depuis votre propre terminal
--json Imprimez le résultat en tant qu'un objet JSON sur la dernière ligne de stdout au lieu du message lisible par l'homme, pour une utilisation dans les scripts. Consultez Format de résultat JSON. Nécessite Claude Code v2.1.268 ou ultérieur
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
-s, --scope <scope> Désinstaller de la portée : user, project, ou local user
--keep-data Préservez le répertoire de données persistantes du plugin
--prune Supprimez également les dépendances auto-installées qu'aucun autre plugin ne nécessite. Consultez plugin prune
-y, --yes Ignorez l'invite de confirmation --prune. Requis lorsque stdin ou stdout n'est pas un TTY
--json Imprimez le résultat en tant qu'un objet JSON sur la dernière ligne de stdout, au même format que plugin install --json. Ne peut pas être combiné avec --prune. Nécessite Claude Code v2.1.268 ou ultérieur
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
-s, --scope <scope> Élaguer à la portée : user, project, ou local user
--dry-run Listez ce qui serait supprimé sans rien supprimer
-y, --yes Ignorez l'invite de confirmation. Requis lorsque stdin ou stdout n'est pas un TTY
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
-s, --scope <scope> Portée à activer : user, project, ou local. Lorsqu'elle est omise, Claude Code détecte la portée où le plugin est installé Détection automatique
--json Imprimez le résultat en tant qu'un objet JSON sur la dernière ligne de stdout, au même format que plugin install --json. Nécessite Claude Code v2.1.268 ou ultérieur
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
-a, --all Désactivez tous les plugins activés. Ne peut pas être combiné avec --scope
-s, --scope <scope> Portée à désactiver : user, project, ou local. Lorsqu'elle est omise, Claude Code détecte la portée où le plugin est installé Détection automatique
--json Imprimez le résultat en tant qu'un objet JSON sur la dernière ligne de stdout, au même format que plugin install --json. Nécessite Claude Code v2.1.268 ou ultérieur
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
-s, --scope <scope> Portée à mettre à jour : user, project, local, ou managed user
-y, --yes Acceptez une commande que la marketplace du plugin déclare, sans l'invite de confirmation : la commande qui produit un plugin avec une command source, ou le headersHelper qui authentifie un téléchargement d'archive. Accepter un headersHelper nécessite Claude Code v2.1.238 ou ultérieur. Claude Code imprime toujours la commande en premier. Requis lorsque stdin ou stdout n'est pas un TTY. N'a aucun effet dans une session Claude Code, exécutez donc la commande depuis votre propre terminal
--json Imprimez le résultat en tant qu'un objet JSON sur la dernière ligne de stdout, au même format que plugin install --json. Nécessite Claude Code v2.1.268 ou ultérieur
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
--json Sortie en JSON. Une ligne de plugin avec des problèmes de chargement ou des avertissements de création porte des tableaux de chaînes errors ou notes. Sur Claude Code v2.1.268 ou ultérieur, les tableaux parallèles errorDetails et noteDetails donnent à chaque entrée son type de diagnostic et les noms auxquels elle se réfère, comme le plugin, la marketplace, le serveur ou le fichier
--available Incluez les plugins disponibles des marketplaces. Nécessite --json
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
-h, --help Afficher l'aide pour la commande

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
  Analyse des dépendances pour les sessions Claude Code
  Source : dependency-guard@example-marketplace

Inventaire des composants
  Compétences (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — aucun coût de contexte du modèle)
  Serveurs MCP (0)
  Serveurs LSP (0)

Coût en jetons projeté
  Toujours actif :   ~180 tok   ajoutés à chaque session

Par composant (arrondi)
  composant            toujours-actif  à-l'invocation
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  Le coût à l'invocation est payé chaque fois qu'une compétence ou un agent se déclenche.
  Les comptages de jetons sont des estimations et peuvent différer de l'utilisation réelle.

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 :

La commande accepte ces options :

Option Description Par défaut
--strict Traitez les avertissements comme des erreurs et quittez 1 sur eux. Utilisez dans CI pour détecter les problèmes que le runtime tolère, comme les champs non reconnus
--json Sortez le rapport de validation en tant qu'un objet JSON avec les mêmes codes de sortie. Nécessite Claude Code v2.1.259 ou ultérieur
-h, --help Afficher l'aide pour la commande

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.

Option Description Par défaut
--runs <n> Exécutions par cas par bras runs de chaque cas, sinon 3
-j, --concurrency <n> Sessions d'agent à exécuter à la fois, 1 à 8. Elles partagent votre limite de débit 1
--model <model> Modèle pour l'agent en test model de chaque cas, sinon ANTHROPIC_MODEL s'il est défini, sinon la valeur par défaut de Claude Code
--judge-model <model> Modèle pour les évaluateurs llm et baseline Un petit modèle rapide
--ablation <mode> none ou with-without. Consultez Comparer par rapport à une ligne de base sans plugin with-without lorsqu'un plugin se résout, sinon none
--threshold <0..1> Quittez 1 si un cas quelconque note en dessous de ceci 1.0
--max-cost-usd <usd> Arrêtez avant la prochaine exécution une fois que les dépenses atteignent ceci, quittez 2, et rapportez les résultats partiels Pas de plafond
--allow-tools <tools...> Accordez des outils au-delà de l'ensemble en lecture seule, comme Bash, Write, Edit, ou "mcp__plugin_<plugin>_<server>__*". Consultez Accorder des outils
--scaffold Exécutez le scaffold_script de chaque cas Désactivé
--trust-plugin Ignorez l'invite de confiance à la première exécution, pour CI. Consultez Ce qu'une exécution peut accéder Désactivé
--mocks <mode> record ou off. Consultez Serveurs MCP fictifs record
--eval-dir <dir> Répertoire sous le plugin qui contient les cas Le experimental.evals du manifeste, sinon evals
--json [path] Imprimez le document de résultat sur stdout, ou écrivez-le dans un chemin .json
--no-publish Gardez le rapport HTML local
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
--bare Écrivez un prompt.md vierge et graders/criteria.md pour <name> au lieu d'exécuter l'interview
-i, --interactive Exigez l'interview. Échoue sans terminal au lieu d'écrire un modèle
--eval-dir <dir> Répertoire sous le répertoire courant pour écrire les cas dans Le experimental.evals du manifeste, sinon evals
-h, --help Afficher l'aide pour la commande

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 :

Option Description Par défaut
--push Poussez la balise vers le serveur distant après l'avoir créée
--dry-run Imprimez ce qui serait balisé sans créer la balise
-f, --force Créez la balise même si l'arborescence de travail est sale ou la balise existe déjà
-m, --message <msg> Message d'annotation de balise. Utilisez %s comme espace réservé pour la version
--remote <name> Serveur distant vers lequel pousser avec --push origin
-h, --help Afficher l'aide pour la commande

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

Problème Cause Solution
Plugin ne se charge pas plugin.json invalide Exécutez claude plugin validate ./my-plugin ou /plugin validate ./my-plugin, où ./my-plugin est votre répertoire de plugin, pour vérifier plugin.json, hooks/hooks.json et le frontmatter des skills, agents et commandes dans les répertoires par défaut du plugin pour les erreurs de syntaxe et de schéma. Consultez Validate a plugin or a directory without a manifest pour savoir ce qu'une exécution couvre
Les skills n'apparaissent pas Structure de répertoire incorrecte Assurez-vous que skills/ ou commands/ se trouve à la racine du plugin, pas à l'intérieur de .claude-plugin/
Les hooks ne se déclenchent pas Script non exécutable Exécutez chmod +x script.sh
Le serveur MCP échoue ${CLAUDE_PLUGIN_ROOT} manquant Utilisez la variable pour tous les chemins de plugin
Erreurs de chemin Chemins absolus utilisés Rendez les chemins relatifs, en commençant par ./ ; consultez Path behavior rules, qui couvrent l'exception "." du champ skills
LSP Executable not found in $PATH Serveur de langage non installé Installez le binaire (par exemple, npm install -g typescript-language-server typescript)

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 :

Approche Comment Comportement de mise à jour Idéal pour
Version explicite Définissez "version": "2.1.0" dans plugin.json Les utilisateurs reçoivent les mises à jour uniquement lorsque vous augmentez ce champ. Pousser de nouveaux commits sans l'augmenter n'a aucun effet, et /plugin update signale « déjà à la dernière version ». Plugins publiés avec des cycles de publication stables
Version SHA du commit Omettez version à la fois de plugin.json et de l'entrée marketplace Les utilisateurs reçoivent les mises à jour chaque fois que le commit résolu de la source change Plugins internes ou d'équipe en développement actif
Version du digest Utilisez une source archive et omettez version à la fois de plugin.json et de l'entrée marketplace Avec un pin sha256, les utilisateurs reçoivent les mises à jour lorsque vous modifiez le pin. Sans pin, les utilisateurs reçoivent les mises à jour chaque fois que les octets du fichier zip hébergé changent Plugins publiés en tant que fichiers zip sur un serveur statique ou un référentiel d'artefacts

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