Skip to main content
Les plugins vous permettent d’étendre Claude Code avec des fonctionnalités personnalisées qui peuvent être partagées entre les projets. Via le SDK Agent, vous pouvez charger programmatiquement des plugins à partir de répertoires locaux pour ajouter des capacités à vos sessions d’agent. Un plugin peut inclure :
  • Skills : capacités que Claude invoque de manière autonome lorsqu’elles sont pertinentes. Vous pouvez également invoquer directement un skill de plugin avec /plugin-name:skill-name.
  • Agents : sous-agents spécialisés pour des tâches spécifiques
  • Hooks : gestionnaires d’événements qui répondent à l’utilisation d’outils et à d’autres événements
  • Serveurs MCP : intégrations d’outils externes via Model Context Protocol
Pour des informations complètes sur la structure des plugins et comment créer des plugins, consultez Plugins.

Chargement des plugins

Chargez les plugins en fournissant leurs chemins du système de fichiers local dans votre configuration d’options. Le champ type doit être "local", la seule valeur que le SDK accepte. Le SDK supporte le chargement de plusieurs plugins à partir de différents emplacements. Pour utiliser un plugin distribué via une marketplace ou un référentiel distant, téléchargez-le d’abord et fournissez le chemin du répertoire local. Pour la disposition du répertoire dont un plugin a besoin, consultez la référence de structure des plugins ci-dessous.

Spécifications des chemins

Les chemins des plugins peuvent être :
  • Chemins relatifs : résolus par rapport à l’option cwd (par exemple, "./plugins/my-plugin")
  • Chemins absolus : chemins complets du système de fichiers (par exemple, "/home/user/plugins/my-plugin")
Le chemin doit pointer vers le répertoire racine du plugin : le parent de skills/, agents/, hooks/, commands/, ou .claude-plugin/.

Vérification de l’installation du plugin

Lorsque les plugins se chargent avec succès, ils apparaissent dans le message d’initialisation du système. Vous pouvez vérifier que vos plugins sont disponibles :

Utilisation des skills des plugins

Les skills des plugins sont automatiquement espacés de noms avec le nom du plugin pour éviter les conflits. Pour invoquer l’un d’eux directement, envoyez /plugin-name:skill-name comme prompt.
Si vous avez installé un plugin via la CLI (par exemple, /plugin install my-plugin@marketplace), vous pouvez toujours l’utiliser dans le SDK en fournissant son chemin d’installation. Vérifiez ~/.claude/plugins/ pour les plugins installés via la CLI.

Exemple complet

Voici un exemple complet démontrant le chargement et l’utilisation des plugins :

Référence de la structure des plugins

Un répertoire de plugin contient généralement un fichier manifeste .claude-plugin/plugin.json. Le manifeste est optionnel. Lorsqu’il est omis, Claude Code découvre automatiquement les composants à partir de la disposition du répertoire. Le répertoire peut inclure :
Le répertoire commands/ contient les skills sous forme de fichiers Markdown plats. Utilisez skills/ pour les nouveaux plugins. Claude Code supporte les deux emplacements.

Plusieurs sources de plugins

Combinez les plugins de différents emplacements :
Le SDK n’étend pas les chemins avec tilde comme ~/plugins. Si un chemin de plugin n’existe pas, le SDK ignore ce plugin et la session continue, donc vérifiez la liste plugins dans le message d’initialisation pour confirmer que chaque plugin s’est chargé.

Dépannage

Plugin ne se charge pas

Si votre plugin n’apparaît pas dans la liste plugins du message d’initialisation, vérifiez son champ plugin_errors pour connaître la raison, puis travaillez à travers ces vérifications :
  1. Vérifiez le chemin : assurez-vous que le chemin pointe vers le répertoire racine du plugin, le parent de skills/, agents/, hooks/, commands/, ou .claude-plugin/
  2. Validez plugin.json : si votre plugin inclut un manifeste, assurez-vous qu’il a une syntaxe JSON valide
  3. Vérifiez les permissions de fichier : assurez-vous que le répertoire du plugin est lisible
  4. Confirmez que le répertoire existe : le SDK ignore un chemin inexistant, et le plugin n’apparaît pas dans la liste plugins du message d’initialisation

Les skills n’apparaissent pas

Si les skills des plugins ne fonctionnent pas :
  1. Utilisez l’espace de noms : invoquez les skills des plugins en tant que /plugin-name:skill-name
  2. Vérifiez le message d’initialisation : vérifiez que le skill apparaît dans la liste skills avec l’espace de noms correct
  3. Validez les fichiers de skill : assurez-vous que chaque skill a un fichier SKILL.md dans son propre sous-répertoire sous skills/, par exemple skills/my-skill/SKILL.md

Voir aussi