Guides

Plugins dans le SDK

Chargez des plugins personnalisés pour étendre Claude Code avec des commandes, des agents, des compétences et des hooks via le SDK Agent

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 par programme des plugins à partir de répertoires locaux pour ajouter des commandes slash personnalisées, des agents, des compétences, 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 :

Commandes : Commandes slash personnalisées
Agents : Sous-agents spécialisés pour des tâches spécifiques
Compétences : Capacités invoquées par le modèle que Claude utilise de manière autonome
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 SDK prend en charge 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 de chemin

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 répertoire contenant .claude-plugin/plugin.json).

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 commandes de plugin

Les commandes des plugins sont automatiquement espacées avec le nom du plugin pour éviter les conflits. Le format est plugin-name:command-name.

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 de plugins :

Référence de structure de plugin

Un répertoire de plugin doit contenir un fichier manifeste .claude-plugin/plugin.json. Il peut éventuellement inclure :

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Pour des informations détaillées sur la création de plugins, consultez :

Plugins - Guide complet de développement de plugins
Référence des plugins - Spécifications techniques et schémas

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

Le plugin ne se charge pas

Si votre plugin n'apparaît pas dans le message d'initialisation :

Vérifiez le chemin : Assurez-vous que le chemin pointe vers le répertoire racine du plugin (contenant .claude-plugin/)
Validez plugin.json : Assurez-vous que votre fichier manifeste a une syntaxe JSON valide
Vérifiez les permissions de fichier : Assurez-vous que le répertoire du plugin est lisible

Les commandes ne sont pas disponibles

Si les commandes de plugin ne fonctionnent pas :

Utilisez l'espace de noms : Les commandes de plugin nécessitent le format plugin-name:command-name
Vérifiez le message d'initialisation : Vérifiez que la commande apparaît dans slash_commands avec l'espace de noms correct
Validez les fichiers de commande : Assurez-vous que les fichiers markdown de commande se trouvent dans le répertoire commands/

Problèmes de résolution de chemin

Si les chemins relatifs ne fonctionnent pas :

Vérifiez le répertoire de travail : Les chemins relatifs sont résolus à partir de votre répertoire de travail actuel
Utilisez des chemins absolus : Pour la fiabilité, envisagez d'utiliser des chemins absolus
Normalisez les chemins : Utilisez les utilitaires de chemin pour construire les chemins correctement

Voir aussi

Plugins - Guide complet de développement de plugins
Référence des plugins - Spécifications techniques
Commandes slash - Utilisation des commandes slash dans le SDK
Sous-agents - Travail avec des agents spécialisés
Compétences - Utilisation des compétences d'agent

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") {
    // Check loaded plugins
    console.log("Plugins:", message.plugins);
    // Example: [{ name: "my-plugin", path: "./my-plugin" }]

    // Check available commands from plugins
    console.log("Commands:", message.slash_commands);
    // Example: ["/help", "/compact", "my-plugin:custom-command"]
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet",  // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

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 commands:", message.slash_commands);
    }

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

runWithPlugin().catch(console.error);