Créer des plugins

Créez des plugins personnalisés pour étendre Claude Code avec des skills, des agents, des hooks et des serveurs MCP.

Les plugins vous permettent d'étendre Claude Code avec des fonctionnalités personnalisées qui peuvent être partagées entre les projets et les équipes. Ce guide couvre la création de vos propres plugins avec des skills, des agents, des hooks et des serveurs MCP.

Vous cherchez à installer des plugins existants ? Consultez Découvrir et installer des plugins. Pour les spécifications techniques complètes, consultez Référence des plugins.

Quand utiliser les plugins par rapport à la configuration autonome

Claude Code prend en charge deux façons d'ajouter des skills, des agents et des hooks personnalisés :

Utilisez la configuration autonome quand :

• Vous personnalisez Claude Code pour un seul projet
• La configuration est personnelle et n'a pas besoin d'être partagée
• Vous expérimentez avec des skills ou des hooks avant de les empaqueter
• Vous voulez des noms de skills courts comme /hello ou /deploy

Utilisez les plugins quand :

• Vous voulez partager des fonctionnalités avec votre équipe ou la communauté
• Vous avez besoin des mêmes skills/agents sur plusieurs projets
• Vous voulez le contrôle de version et les mises à jour faciles pour vos extensions
• Vous distribuez via une marketplace
• Vous êtes d'accord avec les skills avec espace de noms comme /my-plugin:hello (l'espace de noms prévient les conflits entre les plugins)

Démarrage rapide

Ce démarrage rapide vous guide dans la création d'un plugin avec un skill personnalisé. Vous allez créer un manifeste (le fichier de configuration qui définit votre plugin), ajouter un skill et le tester localement en utilisant le drapeau --plugin-dir.

Prérequis

• Claude Code installé et authentifié

Créez votre premier plugin

mkdir my-first-plugin

mkdir my-first-plugin/.claude-plugin

{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

mkdir -p my-first-plugin/skills/hello

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

claude --plugin-dir ./my-first-plugin

/my-first-plugin:hello

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

/my-first-plugin:hello Alex

Vous avez créé et testé avec succès un plugin avec ces composants clés :

• Manifeste du plugin (.claude-plugin/plugin.json) : décrit les métadonnées de votre plugin
• Répertoire des skills (skills/) : contient vos skills personnalisés
• Arguments du skill ($ARGUMENTS) : capture l'entrée de l'utilisateur pour un comportement dynamique

Aperçu de la structure du plugin

Vous avez créé un plugin avec un skill, mais les plugins peuvent inclure beaucoup plus : des agents personnalisés, des hooks, des serveurs MCP, des serveurs LSP et des moniteurs en arrière-plan.

Développer des plugins plus complexes

Une fois que vous êtes à l'aise avec les plugins de base, vous pouvez créer des extensions plus sophistiquées.

Ajoutez des Skills à votre plugin

Les plugins peuvent inclure des Agent Skills pour étendre les capacités de Claude. Les skills sont invoqués par le modèle : Claude les utilise automatiquement en fonction du contexte de la tâche.

Ajoutez un répertoire skills/ à la racine de votre plugin avec des dossiers de Skill contenant des fichiers SKILL.md :

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

Chaque SKILL.md contient un frontmatter YAML et des instructions. Incluez une description pour que Claude sache quand utiliser le skill :

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

Après l'installation du plugin, exécutez /reload-plugins pour charger les Skills. Pour des conseils complets sur la création de Skills incluant la divulgation progressive et les restrictions d'outils, consultez Agent Skills.

Ajoutez des serveurs LSP à votre plugin

Les plugins LSP (Language Server Protocol) donnent à Claude l'intelligence du code en temps réel. Si vous avez besoin de supporter un langage qui n'a pas de plugin LSP officiel, vous pouvez en créer un en ajoutant un fichier .lsp.json à votre plugin :

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Les utilisateurs qui installent votre plugin doivent avoir le binaire du serveur de langage installé sur leur machine.

Pour les options de configuration LSP complètes, consultez Serveurs LSP.

Ajoutez des moniteurs en arrière-plan à votre plugin

Les moniteurs en arrière-plan permettent à votre plugin de surveiller les journaux, les fichiers ou l'état externe en arrière-plan et de notifier Claude à mesure que les événements arrivent. Claude Code démarre automatiquement chaque moniteur quand le plugin est actif, donc vous n'avez pas besoin d'instruire Claude pour démarrer la surveillance.

Ajoutez un fichier monitors/monitors.json à la racine du plugin avec un tableau d'entrées de moniteur :

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Chaque ligne stdout de command est livrée à Claude en tant que notification pendant la session. Pour le schéma complet, incluant le déclencheur when et la substitution de variables, consultez Moniteurs.

Livrez les paramètres par défaut avec votre plugin

Les plugins peuvent inclure un fichier settings.json à la racine du plugin pour appliquer la configuration par défaut quand le plugin est activé. Actuellement, seules les clés agent et subagentStatusLine sont supportées.

Définir agent active l'un des agents personnalisés du plugin en tant que thread principal, en appliquant son invite système, ses restrictions d'outils et son modèle. Cela permet à un plugin de changer le comportement par défaut de Claude Code quand il est activé.

{
  "agent": "security-reviewer"
}

Cet exemple active l'agent security-reviewer défini dans le répertoire agents/ du plugin. Les paramètres de settings.json ont priorité sur les settings déclarés dans plugin.json. Les clés inconnues sont silencieusement ignorées.

Organisez les plugins complexes

Pour les plugins avec de nombreux composants, organisez votre structure de répertoires par fonctionnalité. Pour les dispositions de répertoires complètes et les modèles d'organisation, consultez Structure du répertoire du plugin.

Testez vos plugins localement

Utilisez le drapeau --plugin-dir pour tester les plugins pendant le développement. Cela charge votre plugin directement sans nécessiter d'installation.

claude --plugin-dir ./my-plugin

Le drapeau accepte également une archive .zip du répertoire du plugin, qui nécessite Claude Code v2.1.128 ou ultérieur.

claude --plugin-dir ./my-plugin.zip

Quand un plugin --plugin-dir a le même nom qu'un plugin marketplace installé, la copie locale prend la priorité pour cette session. Cela vous permet de tester les modifications d'un plugin que vous avez déjà installé sans le désinstaller d'abord. Les plugins marketplace forcément activés par les paramètres gérés sont la seule exception et ne peuvent pas être remplacés.

À mesure que vous apportez des modifications à votre plugin, exécutez /reload-plugins pour récupérer les mises à jour sans redémarrer. Cela recharge les plugins, les skills, les agents, les hooks, les serveurs MCP du plugin et les serveurs LSP du plugin. Testez vos composants de plugin :

• Essayez vos skills avec /plugin-name:skill-name
• Vérifiez que les agents apparaissent dans /agents
• Vérifiez que les hooks fonctionnent comme prévu

Pour tester un plugin qui est déjà empaqueté en tant qu'archive .zip et hébergé à une URL, comme un artefact de build CI, utilisez --plugin-url à la place. Claude Code récupère l'archive au démarrage et la charge pour cette session uniquement. Si la récupération échoue ou que l'archive est invalide, Claude Code signale une erreur de chargement de plugin et démarre sans elle. Les mêmes considérations de confiance s'appliquent que pour toute source de plugin : pointez uniquement ce drapeau vers des archives que vous contrôlez ou en lesquelles vous avez confiance.

Pour charger plusieurs plugins, répétez le drapeau pour chaque URL :

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

Ou passez des URL séparées par des espaces en tant qu'un seul argument entre guillemets :

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

Déboguez les problèmes de plugin

Si votre plugin ne fonctionne pas comme prévu :

1. Vérifiez la structure : Assurez-vous que vos répertoires sont à la racine du plugin, pas à l'intérieur de .claude-plugin/
2. Testez les composants individuellement : Vérifiez chaque skill, agent et hook séparément
3. Utilisez les outils de validation et de débogage : Consultez Outils de débogage et de développement pour les commandes CLI et les techniques de dépannage

Partagez vos plugins

Quand votre plugin est prêt à être partagé :

1. Ajoutez de la documentation : Incluez un README.md avec les instructions d'installation et d'utilisation
2. Choisissez une stratégie de versioning : Décidez si vous allez définir une version explicite ou vous fier au SHA du commit git. Consultez gestion des versions
3. Créez ou utilisez une marketplace : Distribuez via des marketplaces de plugins pour l'installation
4. Testez avec d'autres : Faites tester le plugin par les membres de l'équipe avant une distribution plus large

Une fois que votre plugin est dans une marketplace, d'autres peuvent l'installer en utilisant les instructions dans Découvrir et installer des plugins. Pour garder un plugin interne à votre équipe, hébergez la marketplace dans un référentiel privé.

Soumettez votre plugin à la marketplace officielle

Pour soumettre un plugin à la marketplace officielle d'Anthropic, utilisez l'un des formulaires de soumission dans l'application :

• Claude.ai : claude.ai/settings/plugins/submit
• Console : platform.claude.com/plugins/submit

Une fois que votre plugin est listé, vous pouvez avoir votre propre CLI qui invite les utilisateurs de Claude Code à l'installer. Consultez Recommander votre plugin à partir de votre CLI.

Convertir les configurations existantes en plugins

Si vous avez déjà des skills ou des hooks dans votre répertoire .claude/, vous pouvez les convertir en plugin pour un partage et une distribution plus faciles.

Étapes de migration

mkdir -p my-plugin/.claude-plugin

{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

mkdir my-plugin/hooks

{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}

claude --plugin-dir ./my-plugin

Ce qui change lors de la migration

Prochaines étapes

Maintenant que vous comprenez le système de plugins de Claude Code, voici les chemins suggérés pour différents objectifs :

Pour les utilisateurs de plugins

• Découvrir et installer des plugins : parcourir les marketplaces et installer des plugins
• Configurer les marketplaces d'équipe : configurer les plugins au niveau du référentiel pour votre équipe

Pour les développeurs de plugins

• Créer et distribuer une marketplace : empaqueter et partager vos plugins
• Référence des plugins : spécifications techniques complètes
• Approfondissez les composants spécifiques du plugin :
  • 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 d'outils externes