Référence des plugins - Claude Code Docs

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

Cette référence fournit les spécifications techniques complètes du 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 cinq types de composants que les plugins peuvent fournir.

Commandes

Les plugins ajoutent des commandes slash personnalisées qui s’intègrent parfaitement au système de commandes de Claude Code. Emplacement : répertoire commands/ à la racine du plugin Format de fichier : fichiers Markdown avec frontmatter Pour plus de détails sur la structure des commandes de plugin, les modèles d’invocation et les fonctionnalités, consultez 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 si 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 dans quoi cet agent se spécialise
capabilities: ["task1", "task2", "task3"]
---

# Nom de l'agent

Description détaillée du rôle de l'agent, son expertise et 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 par rapport aux autres

## Contexte et exemples
Fournissez 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 en fonction du 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 Claude intégrés

Compétences

Les plugins peuvent fournir des compétences d’agent qui étendent les capacités de Claude. Les compétences sont invoquées par le modèle — Claude décide automatiquement quand les utiliser en fonction du contexte de la tâche. Emplacement : répertoire skills/ à la racine du plugin Format de fichier : répertoires contenant des fichiers SKILL.md avec frontmatter Structure de la compétence :

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optionnel)
│   └── scripts/ (optionnel)
└── code-reviewer/
    └── SKILL.md

Comportement d’intégration :

Les compétences de plugin sont automatiquement découvertes lors de l’installation du plugin
Claude invoque automatiquement les compétences en fonction du contexte de tâche correspondant
Les compétences peuvent inclure des fichiers de support aux côtés de SKILL.md

Pour le format SKILL.md et les conseils complets sur la création de compétences, consultez :

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 en ligne dans plugin.json Format : configuration JSON avec des correspondances d’événements et des actions Configuration des hooks :

{
  "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 en ligne dans plugin.json Format : configuration standard du serveur MCP Configuration du 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 aux outils existants de Claude
Les serveurs de plugin peuvent être configurés indépendamment des serveurs MCP de l’utilisateur

Schéma du 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": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "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 obligatoires

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	Explication brève du but du plugin	`"Deployment automation tools"`
`author`	object	Informations sur l’auteur	`{"name": "Dev Team", "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	Balises 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 configuration des hooks ou configuration en ligne	`"./hooks.json"`
`mcpServers`	string\|object	Chemin de configuration MCP ou configuration en ligne	`"./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, les serveurs MCP et les scripts pour assurer les chemins corrects indépendamment du lieu d’installation.

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

Structure du répertoire de plugin

Disposition standard du plugin

Un plugin complet suit cette structure :

enterprise-plugin/
├── .claude-plugin/           # Répertoire de métadonnées
│   └── plugin.json          # Obligatoire : manifeste du 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
├── skills/                   # Compétences d'agent
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Configurations des hooks
│   ├── hooks.json           # Configuration principale des hooks
│   └── security-hooks.json  # Hooks supplémentaires
├── .mcp.json                # Définitions du serveur MCP
├── scripts/                 # Scripts de hook et d'utilitaire
│   ├── 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/, skills/, 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	Objectif
Manifeste	`.claude-plugin/plugin.json`	Fichier de métadonnées obligatoire
Commandes	`commands/`	Fichiers markdown de commande slash
Agents	`agents/`	Fichiers markdown de sous-agent
Compétences	`skills/`	Compétences d’agent avec fichiers SKILL.md
Hooks	`hooks/hooks.json`	Configuration des hooks
Serveurs MCP	`.mcp.json`	Définitions du serveur MCP

Outils de débogage et de développement

Commandes de débogage

Utilisez claude --debug pour voir les détails du chargement du plugin :

claude --debug

Cela affiche :

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

Problèmes courants

Problème	Cause	Solution
Plugin ne se charge pas	`plugin.json` invalide	Valider la syntaxe JSON
Les commandes n’apparaissent pas	Structure de répertoire incorrecte	Assurez-vous que `commands/` est à la racine, pas dans `.claude-plugin/`
Les hooks ne se déclenchent pas	Script non exécutable	Exécutez `chmod +x script.sh`
Le serveur MCP échoue	`${CLAUDE_PLUGIN_ROOT}` manquant	Utilisez 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 de versioning

Gestion des versions

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

## Voir aussi

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

Référence

​Référence des composants de plugins

​Commandes

​Agents

​Compétences

​Hooks

​Serveurs MCP

​Schéma du manifeste de plugin

​Schéma complet

​Champs obligatoires

​Champs de métadonnées

​Champs de chemin de composant

​Règles de comportement des chemins

​Variables d’environnement

​Structure du répertoire de plugin

​Disposition standard du plugin

​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 de versioning

​Gestion des versions

Référence des composants de plugins

Commandes

Agents

Compétences

Hooks

Serveurs MCP

Schéma du manifeste de plugin

Schéma complet

Champs obligatoires

Champs de métadonnées

Champs de chemin de composant

Règles de comportement des chemins

Variables d’environnement

Structure du répertoire de plugin

Disposition standard du plugin

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 de versioning

Gestion des versions