Plugins — Empaqueter et distribuer des extensions Claude Code — Claude Code — Le guide pratique

Ce que tu vas apprendre

Créer un plugin avec un manifeste, des commandes, des agents et des hooks
Installer un plugin depuis le marketplace ou un dépôt Git
Tester un plugin en local avant de le publier
Comprendre quand un plugin est pertinent (et quand ce n’est pas la peine)

Prérequis

Claude Code v2.1.83+
Avoir lu les modules slash commands, skills, subagents, MCP et hooks
Un projet avec un dossier .claude/

Un plugin = un dossier structuré avec un fichier .claude-plugin/plugin.json. Il regroupe plusieurs fonctionnalités (slash commands, subagents, MCP, hooks, scripts) dans un seul paquet installable avec /plugin install. C’est le mécanisme de partage le plus complet : une commande, et toute l’équipe a le même setup.

Étapes

1. Créer la structure d’un plugin

Crée un dossier pour ton plugin :

mkdir -p mon-plugin/{.claude-plugin,commands,agents,skills,hooks,scripts}

Structure minimale :

mon-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest obligatoire
├── commands/                # Slash commands (fichiers .md)
├── agents/                  # Subagents (fichiers .md)
├── skills/                  # Skills (dossiers avec SKILL.md)
├── hooks/                   # Hooks (fichiers .js ou .sh)
├── scripts/                 # Scripts utilitaires
└── bin/                     # Exécutables ajoutés au PATH

2. Écrire le manifeste

Fichier .claude-plugin/plugin.json :

{
  "name": "mon-plugin",
  "version": "1.0.0",
  "description": "Description claire et concise",
  "author": {
    "name": "Ton Nom"
  },
  "license": "MIT"
}

Champs obligatoires : name (kebab-case), version (semver), description.

3. Ajouter des slash commands

Fichier commands/review.md :

---
name: Review
description: Lance une revue de code complète
---

# Revue de code

1. Analyse les fichiers modifiés (git diff)
2. Vérifie la sécurité, la performance, la qualité
3. Signale les problèmes avec sévérité et localisation

4. Ajouter des subagents

Fichier agents/security-reviewer.md :

---
name: security-reviewer
description: Revue de code axée sécurité
tools: Read, Grep, Bash
---

Tu es un expert sécurité. Analyse le code pour :
- Injections SQL / XSS / command injection
- Exposition de données sensibles
- Problèmes d'authentification / autorisation
- Configuration insecure

Format de retour :
- Sévérité : Critique / Haut / Moyen / Bas
- Fichier:ligne
- Description + suggestion de correction

5. Ajouter un MCP server

Fichier .mcp.json à la racine du plugin :

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

6. Ajouter des hooks

Fichier hooks/pre-review.js :

#!/usr/bin/env node
const { execSync } = require('child_process');

try {
  execSync('git rev-parse --git-dir', { stdio: 'pipe' });
} catch {
  console.error('Pas un dépôt git');
  process.exit(1);
}

console.log('Pré-revue OK');

Configure les hooks dans .claude-plugin/plugin.json :

{
  "name": "mon-plugin",
  "version": "1.0.0",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node ${CLAUDE_PLUGIN_DATA}/pre-review.js"
          }
        ]
      }
    ]
  }
}

7. Ajouter des options utilisateur (v2.1.83+)

Dans plugin.json :

{
  "name": "mon-plugin",
  "version": "1.0.0",
  "userConfig": {
    "apiKey": {
      "description": "Clé API pour le service",
      "sensitive": true
    },
    "region": {
      "description": "Région de déploiement",
      "default": "us-east-1"
    }
  }
}

sensitive: true stocke la valeur dans le trousseau système, pas en clair.

8. Tester en local

Lance Claude Code avec ton plugin :

claude --plugin-dir ./mon-plugin

Vérifie que tout charge :

/plugin list --installed

Tu dois voir mon-plugin avec ses composants.

Pour tester plusieurs plugins :

claude --plugin-dir ./mon-plugin --plugin-dir ./autre-plugin

Tu peux aussi tester depuis une archive zip (v2.1.128+) :

claude --plugin-dir ./mon-plugin.zip

Ou depuis une URL (v2.1.129+) :

claude --plugin-url https://example.com/mon-plugin-1.0.0.zip

9. Installer depuis le marketplace

# Lister les plugins disponibles
/plugin list

# Voir les détails d'un plugin
claude plugin details pr-review

# Installer
/plugin install pr-review

# Ou depuis une marketplace spécifique
claude plugin install pr-review@anthropic

10. Gérer le cycle de vie

# Mettre à jour
claude plugin update mon-plugin

# Activer / désactiver
/plugin enable mon-plugin
/plugin disable mon-plugin

# Désinstaller
claude plugin uninstall mon-plugin

# Recharger sans redémarrer
/reload-plugins

11. Publier un plugin

Crée un dépôt Git avec la structure complète
Tag la release :

claude plugin tag v1.0.0

Cette commande valide le format semver et crée le tag git.

Soumets au marketplace officiel : claude.ai/settings/plugins/submit
Ou distribue via marketplace privé :

/plugin marketplace add mon-org/mon-marketplace

12. Créer un marketplace privé

Fichier .claude-plugin/marketplace.json :

{
  "name": "mon-team-plugins",
  "owner": "mon-org",
  "plugins": [
    {
      "name": "code-standards",
      "source": "./plugins/code-standards",
      "description": "Standards de code internes",
      "version": "1.2.0"
    },
    {
      "name": "deploy-helper",
      "source": {
        "source": "github",
        "repo": "mon-org/deploy-helper",
        "ref": "v2.0.0"
      }
    }
  ]
}

Sources supportées : chemin relatif, GitHub, git URL, sous-dossier git, npm, pip.

Vérification

Dossier .claude-plugin/plugin.json présent et valide
name en kebab-case, version en semver
Scripts dans bin/ et scripts/ sont exécutables (chmod +x)
claude --plugin-dir ./mon-plugin charge sans erreur
/plugin list affiche le plugin
Les slash commands sont accessibles via /mon-plugin:command
Les subagents apparaissent dans /agents
Les MCP servers sont listés dans claude mcp list
claude plugin details mon-plugin montre le coût contexte par tour

Pièges courants

Plugin non reconnu → Vérifie que plugin.json est dans .claude-plugin/, pas à la racine
Commandes pas disponibles → Le plugin doit être activé : /plugin enable mon-plugin
MCP avec 0 outils → Vérifie les credentials et la connexion réseau
Hooks qui ne s’exécutent pas → Vérifie les permissions et le chemin du script
Nom en majuscules ou espaces → Utilise uniquement minuscules et tirets
Token hardcodé → Utilise ${VAR} dans les configs et exporte la variable
Context bloat → claude plugin details montre le coût en tokens. Évite les skills trop gros
Désactivation refusée → Depuis v2.1.143, un plugin ne se désactive pas si un autre en dépend

Récapitulatif

Action	Commande
Installer un plugin	`/plugin install nom`
Lister les installés	`/plugin list --installed`
Détails + coût contexte	`claude plugin details nom`
Mettre à jour	`claude plugin update nom`
Activer / désactiver	`/plugin enable nom` / `/plugin disable nom`
Désinstaller	`claude plugin uninstall nom`
Tester en local	`claude --plugin-dir ./chemin`
Recharger	`/reload-plugins`
Tag une release	`claude plugin tag v1.0.0`
Ajouter un marketplace	`claude plugin marketplace add source`
Nettoyer les dépendances orphelines	`claude plugin prune`

@diagram:cc-plugins

Approche	Quand l’utiliser
Standalone (skill/command)	Perso, rapide, un seul fichier
Plugin	Partage d’équipe, plusieurs composants, versioning

Pour aller plus loin

Inspiré du guide claude-howto de luongnv89 (MIT)