Créer des plugins

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 :

Approche	Noms des skills	Idéal pour
Autonome (répertoire `.claude/`)	`/hello`	Flux de travail personnels, personnalisations spécifiques au projet, expériences rapides
Plugins (répertoires avec `.claude-plugin/plugin.json`)	`/plugin-name:hello`	Partage avec les coéquipiers, distribution à la communauté, versions publiées, réutilisable entre les projets

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)

Commencez par la configuration autonome dans .claude/ pour une itération rapide, puis convertissez en plugin quand vous êtes prêt à partager.

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é

Si vous ne voyez pas la commande /plugin, mettez à jour Claude Code vers la dernière version. Consultez Dépannage pour les instructions de mise à niveau.

Créez votre premier plugin

Créez le répertoire du plugin

Chaque plugin se trouve dans son propre répertoire contenant un manifeste et vos skills, agents ou hooks. Créez-en un maintenant :

mkdir my-first-plugin

Créez le manifeste du plugin

Le fichier manifeste à .claude-plugin/plugin.json définit l’identité de votre plugin : son nom, sa description et sa version. Claude Code utilise ces métadonnées pour afficher votre plugin dans le gestionnaire de plugins.Créez le répertoire .claude-plugin à l’intérieur de votre dossier de plugin :

mkdir my-first-plugin/.claude-plugin

Ensuite, créez my-first-plugin/.claude-plugin/plugin.json avec ce contenu :

my-first-plugin/.claude-plugin/plugin.json

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

Champ	Objectif
`name`	Identifiant unique et espace de noms du skill. Les skills sont préfixés avec ceci (par exemple, `/my-first-plugin:hello`).
`description`	Affiché dans le gestionnaire de plugins lors de la navigation ou de l’installation de plugins.
`version`	Optionnel. S’il est défini, les utilisateurs ne reçoivent les mises à jour que lorsque vous augmentez ce champ. S’il est omis et que votre plugin est distribué via git, le SHA du commit est utilisé et chaque commit compte comme une nouvelle version. Consultez gestion des versions.
`author`	Optionnel. Utile pour l’attribution.

Pour les champs supplémentaires comme homepage, repository et license, consultez le schéma manifeste complet.

Ajoutez un skill

Les skills se trouvent dans le répertoire skills/. Chaque skill est un dossier contenant un fichier SKILL.md. Le nom du dossier devient le nom du skill, préfixé par l’espace de noms du plugin (hello/ dans un plugin nommé my-first-plugin crée /my-first-plugin:hello).Créez un répertoire de skill dans votre dossier de plugin :

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

Ensuite, créez my-first-plugin/skills/hello/SKILL.md avec ce contenu :

my-first-plugin/skills/hello/SKILL.md

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

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

Testez votre plugin

Exécutez Claude Code avec le drapeau --plugin-dir pour charger votre plugin :

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

Une fois Claude Code démarré, essayez votre nouveau skill :

/my-first-plugin:hello

Vous verrez Claude répondre avec un salut. Exécutez /help pour voir votre skill listé sous l’espace de noms du plugin.

Pourquoi l’espace de noms ? Les skills des plugins sont toujours avec espace de noms (comme /my-first-plugin:hello) pour prévenir les conflits quand plusieurs plugins ont des skills avec le même nom.Pour changer le préfixe d’espace de noms, mettez à jour le champ name dans plugin.json.

Ajoutez des arguments au skill

Rendez votre skill dynamique en acceptant l’entrée de l’utilisateur. L’espace réservé $ARGUMENTS capture tout texte que l’utilisateur fournit après le nom du skill.Mettez à jour votre fichier SKILL.md :

my-first-plugin/skills/hello/SKILL.md

---
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.

Exécutez /reload-plugins pour récupérer les modifications, puis essayez le skill avec votre nom :

/my-first-plugin:hello Alex

Claude vous saluera par votre nom. Pour plus d’informations sur la transmission d’arguments aux skills, consultez Skills.

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

Le drapeau --plugin-dir est utile pour le développement et les tests. Quand vous êtes prêt à partager votre plugin avec d’autres, consultez Créer et distribuer une marketplace de plugins.

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.

Erreur courante : Ne mettez pas commands/, agents/, skills/ ou hooks/ à l’intérieur du répertoire .claude-plugin/. Seul plugin.json va à l’intérieur de .claude-plugin/. Tous les autres répertoires doivent être au niveau racine du plugin.

Répertoire	Emplacement	Objectif
`.claude-plugin/`	Racine du plugin	Contient le manifeste `plugin.json` (optionnel si les composants utilisent les emplacements par défaut)
`skills/`	Racine du plugin	Skills en tant que répertoires `<name>/SKILL.md`
`commands/`	Racine du plugin	Skills en tant que fichiers Markdown plats. Utilisez `skills/` pour les nouveaux plugins
`agents/`	Racine du plugin	Définitions d’agents personnalisés
`hooks/`	Racine du plugin	Gestionnaires d’événements dans `hooks.json`
`.mcp.json`	Racine du plugin	Configurations du serveur MCP
`.lsp.json`	Racine du plugin	Configurations du serveur LSP pour l’intelligence du code
`monitors/`	Racine du plugin	Configurations du moniteur en arrière-plan dans `monitors.json`
`bin/`	Racine du plugin	Exécutables ajoutés au `PATH` de l’outil Bash tandis que le plugin est activé
`settings.json`	Racine du plugin	Paramètres par défaut appliqués quand le plugin est activé

Prochaines étapes : Prêt à ajouter plus de fonctionnalités ? Allez à Développer des plugins plus complexes pour ajouter des agents, des hooks, des serveurs MCP et des serveurs LSP. Pour les spécifications techniques complètes de tous les composants du plugin, consultez Référence des plugins.

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

Pour les langages courants comme TypeScript, Python et Rust, installez les plugins LSP pré-construits à partir de la marketplace officielle. Créez des plugins LSP personnalisés uniquement quand vous avez besoin de support pour des langages non encore couverts.

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 :

.lsp.json

{
  "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 :

monitors/monitors.json

[
  {
    "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é.

settings.json

{
  "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

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

Vous pouvez charger plusieurs plugins à la fois en spécifiant le drapeau plusieurs fois :

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Déboguez les problèmes de plugin

Si votre plugin ne fonctionne pas comme prévu :

Vérifiez la structure : Assurez-vous que vos répertoires sont à la racine du plugin, pas à l’intérieur de .claude-plugin/
Testez les composants individuellement : Vérifiez chaque skill, agent et hook séparément
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é :

Ajoutez de la documentation : Incluez un README.md avec les instructions d’installation et d’utilisation
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
Créez ou utilisez une marketplace : Distribuez via des marketplaces de plugins pour l’installation
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.

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.

Pour les spécifications techniques complètes, les techniques de débogage et les stratégies de distribution, consultez Référence des plugins.

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

Créez la structure du plugin

Créez un nouveau répertoire de plugin :

mkdir -p my-plugin/.claude-plugin

Créez le fichier manifeste à my-plugin/.claude-plugin/plugin.json :

my-plugin/.claude-plugin/plugin.json

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

Copiez vos fichiers existants

Copiez vos configurations existantes dans le répertoire du plugin :

# 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/

Migrez les hooks

Si vous avez des hooks dans vos paramètres, créez un répertoire de hooks :

mkdir my-plugin/hooks

Créez my-plugin/hooks/hooks.json avec votre configuration de hooks. Copiez l’objet hooks de votre .claude/settings.json ou settings.local.json, car le format est le même. La commande reçoit l’entrée du hook en tant que JSON sur stdin, donc utilisez jq pour extraire le chemin du fichier :

my-plugin/hooks/hooks.json

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

Testez votre plugin migré

Chargez votre plugin pour vérifier que tout fonctionne :

claude --plugin-dir ./my-plugin

Testez chaque composant : exécutez vos commandes, vérifiez que les agents apparaissent dans /agents et vérifiez que les hooks se déclenchent correctement.

Ce qui change lors de la migration

Autonome (`.claude/`)	Plugin
Disponible uniquement dans un projet	Peut être partagé via des marketplaces
Fichiers dans `.claude/commands/`	Fichiers dans `plugin-name/commands/`
Hooks dans `settings.json`	Hooks dans `hooks/hooks.json`
Doit être copié manuellement pour partager	Installer avec `/plugin install`

Après la migration, vous pouvez supprimer les fichiers originaux de .claude/ pour éviter les doublons. La version du plugin aura la priorité quand elle est chargée.

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

Agents

Outils et plugins

Automatisation

Dépannage

Quand utiliser les plugins par rapport à la configuration autonome

Démarrage rapide

Prérequis

Créez votre premier plugin

Aperçu de la structure du plugin

Développer des plugins plus complexes

Ajoutez des Skills à votre plugin

Ajoutez des serveurs LSP à votre plugin

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

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

Organisez les plugins complexes

Testez vos plugins localement

Déboguez les problèmes de plugin

Partagez vos plugins

Soumettez votre plugin à la marketplace officielle

Convertir les configurations existantes en plugins

Étapes de migration

Ce qui change lors de la migration

Prochaines étapes

Pour les utilisateurs de plugins

Pour les développeurs de plugins

Agents

Outils et plugins

Automatisation

Dépannage

​Quand utiliser les plugins par rapport à la configuration autonome

​Démarrage rapide

​Prérequis

​Créez votre premier plugin

​Aperçu de la structure du plugin

​Développer des plugins plus complexes

​Ajoutez des Skills à votre plugin

​Ajoutez des serveurs LSP à votre plugin

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

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

​Organisez les plugins complexes

​Testez vos plugins localement

​Déboguez les problèmes de plugin

​Partagez vos plugins

​Soumettez votre plugin à la marketplace officielle

​Convertir les configurations existantes en plugins

​Étapes de migration

​Ce qui change lors de la migration

​Prochaines étapes

​Pour les utilisateurs de plugins

​Pour les développeurs de plugins

Quand utiliser les plugins par rapport à la configuration autonome

Démarrage rapide

Prérequis

Créez votre premier plugin

Aperçu de la structure du plugin

Développer des plugins plus complexes

Ajoutez des Skills à votre plugin

Ajoutez des serveurs LSP à votre plugin

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

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

Organisez les plugins complexes

Testez vos plugins localement

Déboguez les problèmes de plugin

Partagez vos plugins

Soumettez votre plugin à la marketplace officielle

Convertir les configurations existantes en plugins

Étapes de migration

Ce qui change lors de la migration

Prochaines étapes

Pour les utilisateurs de plugins

Pour les développeurs de plugins