Passer au contenu principal
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 skills, des agents, des hooks et des serveurs MCP à vos sessions d’agent.

​
Que sont les plugins ?

Les plugins sont des packages d’extensions Claude Code qui peuvent inclure :
  • Skills : Capacités invoquées par le modèle que Claude utilise de manière autonome (peuvent également être invoquées avec /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
Le répertoire commands/ est un format hérité. Utilisez skills/ pour les nouveaux plugins. Claude Code continue de supporter les deux formats pour la compatibilité rétroactive.
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. 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. Le SDK supporte le chargement de plusieurs plugins à partir de différents emplacements. 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [
      { type: "local", path: "./my-plugin" },
      { type: "local", path: "/absolute/path/to/another-plugin" }
    ]
  }
})) {
  // Plugin commands, agents, and other features are now available
}

​
Spécifications des chemins

Les chemins des plugins peuvent être :
  • Chemins relatifs : Résolus par rapport à votre répertoire de travail actuel (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/ (hérité), ou .claude-plugin/, et non un sous-répertoire.

​
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 : 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Vérifier les plugins chargés
    console.log("Plugins:", message.plugins);
    // Exemple : [{ name: "my-plugin", path: "./my-plugin" }]

    // Les compétences du plugin apparaissent avec le nom du plugin comme préfixe
    console.log("Skills:", message.skills);
    // Exemple : ["my-plugin:greet"]

    // Les commandes du plugin utilisent le même préfixe, et les compétences apparaissent également ici
    console.log("Commands:", message.slash_commands);
    // Exemple : ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
  }
}

​
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. 
import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet skill
for await (const message of query({
  prompt: "/my-plugin:greet", // Use plugin skill with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting skill from the plugin
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}
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 : 
import { query } from "@anthropic-ai/claude-agent-sdk";
import * as path from "path";

async function runWithPlugin() {
  const pluginPath = path.join(__dirname, "plugins", "my-plugin");

  console.log("Loading plugin from:", pluginPath);

  for await (const message of query({
    prompt: "What custom commands do you have available?",
    options: {
      plugins: [{ type: "local", path: pluginPath }],
      maxTurns: 3
    }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      console.log("Loaded plugins:", message.plugins);
      console.log("Available skills:", message.skills);
      console.log("Available commands:", message.slash_commands);
    }

    if (message.type === "assistant") {
      console.log("Assistant:", message.message.content);
    }
  }
}

runWithPlugin().catch(console.error);

​
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 : 
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifeste du plugin (optionnel, composants découverts automatiquement sans lui)
├── skills/                   # Agent Skills (invoquées de manière autonome ou via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Héritage : utilisez skills/ à la place
│   └── custom-cmd.md
├── agents/                   # Agents personnalisés
│   └── specialist.md
├── hooks/                    # Gestionnaires d'événements
│   └── hooks.json
└── .mcp.json                # Définitions du serveur MCP
Pour des informations détaillées sur la création de plugins, consultez :

​
Cas d’usage courants

​
Développement et test

Chargez les plugins pendant le développement sans les installer globalement : 
plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }];

​
Extensions spécifiques au projet

Incluez les plugins dans votre référentiel de projet pour la cohérence à l’échelle de l’équipe : 
plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];

​
Plusieurs sources de plugins

Combinez les plugins de différents emplacements : 
plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];

​
Dépannage

​
Plugin ne se charge pas

Si votre plugin n’apparaît pas dans le message d’initialisation :
  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/ (hérité), 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

​
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

​
Problèmes de résolution de chemin

Si les chemins relatifs ne fonctionnent pas :
  1. Vérifiez le répertoire de travail : Les chemins relatifs sont résolus à partir de votre répertoire de travail actuel
  2. Utilisez des chemins absolus : Pour la fiabilité, envisagez d’utiliser des chemins absolus
  3. Normalisez les chemins : Utilisez les utilitaires de chemin pour construire les chemins correctement

​
Voir aussi