Plugins dans le SDK
Chargez des plugins personnalisés pour étendre Claude Code avec des skills, des agents, des hooks et des serveurs MCP 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 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
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
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[
{"type": "local", "path": "./my-plugin"},
{"type": "local", "path": "/absolute/path/to/another-plugin"},
]
),
):
# Plugin commands, agents, and other features are now available
pass
asyncio.run(main())
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")
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"]
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./my-plugin"}]
),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
# Vérifier les plugins chargés
print("Plugins:", message.data.get("plugins"))
# Exemple : [{"name": "my-plugin", "path": "./my-plugin"}]
# Les compétences du plugin apparaissent avec le nom du plugin comme préfixe
print("Skills:", message.data.get("skills"))
# Exemple : ["my-plugin:greet"]
# Les commandes du plugin utilisent le même préfixe, et les compétences apparaissent également ici
print("Commands:", message.data.get("slash_commands"))
# Exemple : ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
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);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
async def main():
# Load a plugin with a custom /greet skill
async for message in query(
prompt="/demo-plugin:greet", # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]
),
):
# Claude executes the custom greeting skill from the plugin
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")
asyncio.run(main())
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);
#!/usr/bin/env python3
"""Example demonstrating how to use plugins with the Agent SDK."""
from pathlib import Path
import anyio
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
SystemMessage,
TextBlock,
query,
)
async def run_with_plugin():
"""Example using a custom plugin."""
plugin_path = Path(__file__).parent / "plugins" / "demo-plugin"
print(f"Loading plugin from: {plugin_path}")
options = ClaudeAgentOptions(
plugins=[{"type": "local", "path": str(plugin_path)}],
max_turns=3,
)
async for message in query(
prompt="What custom commands do you have available?", options=options
):
if isinstance(message, SystemMessage) and message.subtype == "init":
print(f"Loaded plugins: {message.data.get('plugins')}")
print(f"Available skills: {message.data.get('skills')}")
print(f"Available commands: {message.data.get('slash_commands')}")
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Assistant: {block.text}")
if __name__ == "__main__":
anyio.run(run_with_plugin)
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 :
- 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
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, le parent de
skills/,agents/,hooks/,commands/(hérité), ou.claude-plugin/ - Validez plugin.json : Si votre plugin inclut un manifeste, assurez-vous qu'il a une syntaxe JSON valide
- 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 :
- Utilisez l'espace de noms : Invoquez les skills des plugins en tant que
/plugin-name:skill-name - Vérifiez le message d'initialisation : Vérifiez que le skill apparaît dans la liste
skillsavec l'espace de noms correct - Validez les fichiers de skill : Assurez-vous que chaque skill a un fichier
SKILL.mddans son propre sous-répertoire sousskills/, par exempleskills/my-skill/SKILL.md
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
- Commands - Utilisation des commandes dans le SDK
- Subagents - Travail avec des agents spécialisés
- Skills - Utilisation des Agent Skills