Référence des plugins

Pour des tutoriels pratiques et une utilisation concrète, voir Plugins. Pour la gestion des plugins dans les équipes et communautés, voir Marchés de plugins.

Cette référence fournit les spécifications techniques complètes pour le système de plugins Claude Code, incluant les schémas de composants, les commandes CLI et les outils de développement.

Référence des composants de plugins

Cette section documente les quatre types de composants que les plugins peuvent fournir.

Commandes

Les plugins ajoutent des commandes slash personnalisées qui s’intègrent parfaitement avec le système de commandes de Claude Code. Emplacement : répertoire commands/ à la racine du plugin Format de fichier : fichiers Markdown avec frontmatter Pour des détails complets sur la structure des commandes de plugin, les modèles d’invocation et les fonctionnalités, voir Commandes de plugin.

Agents

Les plugins peuvent fournir des sous-agents spécialisés pour des tâches spécifiques que Claude peut invoquer automatiquement quand c’est approprié. Emplacement : répertoire agents/ à la racine du plugin Format de fichier : fichiers Markdown décrivant les capacités de l’agent Structure de l’agent :

---
description: Ce en quoi cet agent se spécialise
capabilities: ["tâche1", "tâche2", "tâche3"]
---

# Nom de l'Agent

Description détaillée du rôle de l'agent, de son expertise et de quand Claude devrait l'invoquer.

## Capacités
- Tâche spécifique dans laquelle l'agent excelle
- Une autre capacité spécialisée
- Quand utiliser cet agent plutôt que d'autres

## Contexte et exemples
Fournir des exemples de quand cet agent devrait être utilisé et quels types de problèmes il résout.

Points d’intégration :

Les agents apparaissent dans l’interface /agents
Claude peut invoquer les agents automatiquement selon le contexte de la tâche
Les agents peuvent être invoqués manuellement par les utilisateurs
Les agents de plugin fonctionnent aux côtés des agents intégrés de Claude

Hooks

Les plugins peuvent fournir des gestionnaires d’événements qui répondent automatiquement aux événements de Claude Code. Emplacement : hooks/hooks.json à la racine du plugin, ou inline dans plugin.json Format : configuration JSON avec des correspondances d’événements et des actions Configuration de hook :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Événements disponibles :

PreToolUse : Avant que Claude utilise un outil
PostToolUse : Après que Claude utilise un outil
UserPromptSubmit : Quand l’utilisateur soumet une invite
Notification : Quand Claude Code envoie des notifications
Stop : Quand Claude tente de s’arrêter
SubagentStop : Quand un sous-agent tente de s’arrêter
SessionStart : Au début des sessions
SessionEnd : À la fin des sessions
PreCompact : Avant que l’historique de conversation soit compacté

Types de hooks :

command : Exécuter des commandes shell ou des scripts
validation : Valider le contenu des fichiers ou l’état du projet
notification : Envoyer des alertes ou des mises à jour de statut

Serveurs MCP

Les plugins peuvent regrouper des serveurs Model Context Protocol (MCP) pour connecter Claude Code avec des outils et services externes. Emplacement : .mcp.json à la racine du plugin, ou inline dans plugin.json Format : configuration de serveur MCP standard Configuration de serveur MCP :

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Comportement d’intégration :

Les serveurs MCP de plugin démarrent automatiquement quand le plugin est activé
Les serveurs apparaissent comme des outils MCP standard dans la boîte à outils de Claude
Les capacités du serveur s’intègrent parfaitement avec les outils existants de Claude
Les serveurs de plugin peuvent être configurés indépendamment des serveurs MCP utilisateur

Schéma de manifeste de plugin

Le fichier plugin.json définit les métadonnées et la configuration de votre plugin. Cette section documente tous les champs et options supportés.

Schéma complet

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brève description du plugin",
  "author": {
    "name": "Nom de l'Auteur",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Champs requis

Champ	Type	Description	Exemple
`name`	string	Identifiant unique (kebab-case, pas d’espaces)	`"deployment-tools"`

Champs de métadonnées

Champ	Type	Description	Exemple
`version`	string	Version sémantique	`"2.1.0"`
`description`	string	Brève explication du but du plugin	`"Outils d'automatisation de déploiement"`
`author`	object	Informations sur l’auteur	`{"name": "Équipe Dev", "email": "[email protected]"}`
`homepage`	string	URL de documentation	`"https://docs.example.com"`
`repository`	string	URL du code source	`"https://github.com/user/plugin"`
`license`	string	Identifiant de licence	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Tags de découverte	`["deployment", "ci-cd"]`

Champs de chemin de composant

Champ	Type	Description	Exemple
`commands`	string\|array	Fichiers/répertoires de commandes supplémentaires	`"./custom/cmd.md"` ou `["./cmd1.md"]`
`agents`	string\|array	Fichiers d’agents supplémentaires	`"./custom/agents/"`
`hooks`	string\|object	Chemin de config de hook ou config inline	`"./hooks.json"`
`mcpServers`	string\|object	Chemin de config MCP ou config inline	`"./mcp.json"`

Règles de comportement des chemins

Important : Les chemins personnalisés complètent les répertoires par défaut - ils ne les remplacent pas.

Si commands/ existe, il est chargé en plus des chemins de commandes personnalisés
Tous les chemins doivent être relatifs à la racine du plugin et commencer par ./
Les commandes des chemins personnalisés utilisent les mêmes règles de nommage et d’espacement de noms
Plusieurs chemins peuvent être spécifiés sous forme de tableaux pour plus de flexibilité

Exemples de chemins :

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variables d’environnement

${CLAUDE_PLUGIN_ROOT} : Contient le chemin absolu vers votre répertoire de plugin. Utilisez ceci dans les hooks, serveurs MCP et scripts pour assurer des chemins corrects indépendamment de l’emplacement d’installation.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Structure de répertoire de plugin

Disposition de plugin standard

Un plugin complet suit cette structure :

enterprise-plugin/
├── .claude-plugin/           # Répertoire de métadonnées
│   └── plugin.json          # Requis : manifeste de plugin
├── commands/                 # Emplacement de commande par défaut
│   ├── status.md
│   └──  logs.md
├── agents/                   # Emplacement d'agent par défaut
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── hooks/                    # Configurations de hooks
│   ├── hooks.json           # Config de hook principale
│   └── security-hooks.json  # Hooks supplémentaires
├── .mcp.json                # Définitions de serveur MCP
├── scripts/                 # Scripts de hook et utilitaires
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Fichier de licence
└── CHANGELOG.md             # Historique des versions

Le répertoire .claude-plugin/ contient le fichier plugin.json. Tous les autres répertoires (commands/, agents/, hooks/) doivent être à la racine du plugin, pas à l’intérieur de .claude-plugin/.

Référence des emplacements de fichiers

Composant	Emplacement par Défaut	But
Manifeste	`.claude-plugin/plugin.json`	Fichier de métadonnées requis
Commandes	`commands/`	Fichiers markdown de commandes slash
Agents	`agents/`	Fichiers markdown de sous-agents
Hooks	`hooks/hooks.json`	Configuration de hooks
Serveurs MCP	`.mcp.json`	Définitions de serveurs MCP

Outils de débogage et de développement

Commandes de débogage

Utilisez claude --debug pour voir les détails de chargement des plugins :

claude --debug

Ceci montre :

Quels plugins sont en cours de chargement
Toute erreur dans les manifestes de plugin
Enregistrement de commandes, agents et hooks
Initialisation de serveur MCP

Problèmes courants

Problème	Cause	Solution
Plugin ne se charge pas	`plugin.json` invalide	Valider la syntaxe JSON
Commandes n’apparaissent pas	Structure de répertoire incorrecte	S’assurer que `commands/` est à la racine, pas dans `.claude-plugin/`
Hooks ne se déclenchent pas	Script non exécutable	Exécuter `chmod +x script.sh`
Serveur MCP échoue	`${CLAUDE_PLUGIN_ROOT}` manquant	Utiliser la variable pour tous les chemins de plugin
Erreurs de chemin	Chemins absolus utilisés	Tous les chemins doivent être relatifs et commencer par `./`

Référence de distribution et versioning

Gestion des versions

Suivez le versioning sémantique pour les versions de plugin :


## Voir aussi

- [Plugins](/fr/docs/claude-code/plugins) - Tutoriels et utilisation pratique
- [Marchés de plugins](/fr/docs/claude-code/plugin-marketplaces) - Création et gestion de marchés
- [Commandes slash](/fr/docs/claude-code/slash-commands) - Détails de développement de commandes
- [Sous-agents](/fr/docs/claude-code/sub-agents) - Configuration et capacités des agents
- [Hooks](/fr/docs/claude-code/hooks) - Gestion d'événements et automatisation
- [MCP](/fr/docs/claude-code/mcp) - Intégration d'outils externes
- [Paramètres](/fr/docs/claude-code/settings) - Options de configuration pour les plugins

Commencer

Créer avec Claude Code

SDK de code Claude

Déploiement

Administration

Configuration

Référence

Ressources

Référence des plugins

Référence des composants de plugins

Commandes

Agents

Hooks

Serveurs MCP

Schéma de manifeste de plugin

Schéma complet

Champs requis

Champs de métadonnées

Champs de chemin de composant

Règles de comportement des chemins

Variables d’environnement

Structure de répertoire de plugin

Disposition de plugin standard

Référence des emplacements de fichiers

Outils de débogage et de développement

Commandes de débogage

Problèmes courants

Référence de distribution et versioning

Gestion des versions

Commencer

Créer avec Claude Code

SDK de code Claude

Déploiement

Administration

Configuration

Référence

Ressources

​Référence des composants de plugins

​Commandes

​Agents

​Hooks

​Serveurs MCP

​Schéma de manifeste de plugin

​Schéma complet

​Champs requis

​Champs de métadonnées

​Champs de chemin de composant

​Règles de comportement des chemins

​Variables d’environnement

​Structure de répertoire de plugin

​Disposition de plugin standard

​Référence des emplacements de fichiers

​Outils de débogage et de développement

​Commandes de débogage

​Problèmes courants

​Référence de distribution et versioning

​Gestion des versions

Référence des composants de plugins

Commandes

Agents

Hooks

Serveurs MCP

Schéma de manifeste de plugin

Schéma complet

Champs requis

Champs de métadonnées

Champs de chemin de composant

Règles de comportement des chemins

Variables d’environnement

Structure de répertoire de plugin

Disposition de plugin standard

Référence des emplacements de fichiers

Outils de débogage et de développement

Commandes de débogage

Problèmes courants

Référence de distribution et versioning

Gestion des versions