Anatomie d'un plugin Claude Code (skills, hooks, sub-agents, MCP)

Pourquoi ce module

Hooks, skills, commandes slash, sub-agents, serveurs MCP : on les apprend souvent comme des sujets séparés. Mais en 2026, l'unité qui les emballe et les distribue s'appelle un plugin. Un plugin Claude Code est un dossier auto-suffisant qui peut contenir, à la fois, des skills, des commandes, des hooks, des sub-agents et des serveurs MCP — installable en une commande, partageable via une marketplace.

Comprendre cette anatomie, c'est le socle de tout le reste : sans elle, les modules avancés (MCP en production, marketplace, agents autonomes) flottent. Ce module pose les définitions, montre comment les briques s'emboîtent, et vous fait créer puis publier un plugin minimal.

Prérequis : avoir pratiqué Claude Code en CLI (quelques semaines), être à l'aise avec JSON / Markdown / Git. Aucun prérequis sur les briques individuelles — ce module est le point d'entrée.

Objectifs pédagogiques

À l'issue de ce module, vous serez capable de :

1. Définir un plugin et lister les composants qu'il peut empaqueter (skills, commands, hooks, sub-agents, serveurs MCP)
2. Lire et écrire un plugin.json et comprendre la découverte par convention de dossiers
3. Choisir le bon composant pour un besoin donné : skill vs commande vs sub-agent vs hook vs MCP
4. Comprendre les hooks : à quels événements s'accrocher, et le format de déclaration
5. Installer un plugin via une marketplace (/plugin marketplace add, /plugin install) et héberger la sienne
6. Distinguer ce qui se distribue (plugin/marketplace) de ce qui reste local, et situer le plugin face au Claude Agent SDK

Plan détaillé

1. Qu'est-ce qu'un plugin (et ce que ce n'est pas)
2. Le manifeste plugin.json
3. Les 5 composants empaquetables
4. Skill vs commande vs sub-agent vs hook vs MCP — quand utiliser quoi
5. Les hooks : événements et automatisation
6. Arborescence complète d'un plugin
7. Marketplaces : marketplace.json, commandes, hébergement
8. Marketplaces officielles, installation et sécurité
9. Plugin vs Claude Agent SDK vs MEMORY.md
10. Atelier : créer et publier un mini-plugin

Qu'est-ce qu'un plugin (et ce que ce n'est pas)

Un plugin est un dossier versionnable contenant un manifeste .claude-plugin/plugin.json et un ou plusieurs composants. Une fois installé, ses composants deviennent disponibles dans Claude Code comme s'ils étaient natifs.

C'est un conteneur de distribution, pas une nouvelle capacité en soi. Les briques (skills, hooks, MCP…) existaient déjà séparément ; le plugin les regroupe pour qu'on les installe, versionne et partage ensemble.

Ce qu'un plugin n'est PAS :

• Ce n'est pas le Claude Agent SDK (qui sert à coder des agents en Python/TS — voir section 9).
• Ce n'est pas un MEMORY.md (mémoire de projet) ni un AGENTS.md (instructions projet).
• Ce n'est pas payant : le marketplace officiel Anthropic est gratuit et ne reverse pas de revenus aux créateurs (cf. M14).

Le manifeste plugin.json

Le seul fichier obligatoire est .claude-plugin/plugin.json. Seul name est requis ; tout le reste est métadonnée optionnelle.

{
  "name": "mon-plugin-qualite",
  "version": "1.0.0",
  "description": "Hooks de lint + skill de revue + agent reviewer",
  "author": { "name": "Acme", "email": "dev@acme.io" },
  "homepage": "https://github.com/acme/mon-plugin-qualite",
  "repository": "https://github.com/acme/mon-plugin-qualite",
  "license": "MIT",
  "keywords": ["lint", "review", "quality"]
}

Découverte par convention : vous n'avez pas besoin de déclarer chaque composant dans le manifeste. Claude Code découvre automatiquement skills/, commands/, agents/, hooks/hooks.json et .mcp.json à la racine du plugin. Les champs correspondants (skills, commands, agents, hooks, mcpServers, lspServers) servent uniquement à pointer vers des emplacements non standards.

Les 5 composants empaquetables

1. Skills — skills/<nom>/SKILL.md

Une skill est une instruction réutilisable que Claude peut invoquer (de lui-même ou sur demande). C'est un fichier SKILL.md : un frontmatter YAML + un corps Markdown (les instructions). Elle peut embarquer des fichiers de référence et des scripts.

---
name: revue-securite
description: Audite le diff courant pour les failles de sécurité courantes
allowed-tools: Bash(git diff:*), Read
argument-hint: "[chemin optionnel]"
---

Analyse le diff (`git diff`) et signale injections, secrets en clair,
contrôles d'accès manquants. Donne fichier:ligne pour chaque finding.

Champs de frontmatter utiles : description (clé — c'est ce qui aide Claude à décider quand l'utiliser), allowed-tools / disallowed-tools, disable-model-invocation (la rend déclenchable uniquement par l'utilisateur), model, argument-hint, context: fork (l'exécute dans un sub-agent isolé). Arguments : $ARGUMENTS, $1, $2…

🆕 context: fork tourne en arrière-plan par défaut (v2.1.218). Une skill forkée ne bloque plus la session : elle part en tâche de fond et remonte son résultat à la fin. Pour retrouver l'exécution bloquante — utile quand la suite du travail dépend directement du résultat — ajoutez background: false dans le frontmatter de la skill.

Même version, petit confort qui évite une classe entière de bugs silencieux : les booléens de frontmatter (skills comme plugins) acceptent désormais yes/no/on/off/1/0, insensibles à la casse, en plus de true/false. Un disable-model-invocation: yes n'est plus ignoré sans un mot.

2. Commandes slash — commands/<nom>.md

Historiquement, une commande est un fichier Markdown plat invoqué par /<nom>. Format quasi identique à une skill (même frontmatter). En 2026, le format skill en répertoire (skills/<nom>/SKILL.md) est le mécanisme recommandé et recouvre l'ancien : une skill user-invocable apparaît aussi dans le menu /.

3. Hooks — hooks/hooks.json

Un hook exécute une commande shell à un événement du cycle de vie (ex : après chaque écriture de fichier). C'est le levier d'automatisation déterministe (cf. section 5).

4. Sub-agents — agents/<nom>.md

Un sub-agent est un assistant spécialisé avec son propre system prompt et un accès outils restreint, que Claude peut déléguer.

---
name: reviewer
description: Relit le code pour bugs et lisibilité. À utiliser après chaque PR.
tools: Read, Bash(git diff:*)
model: inherit
---

Tu es un relecteur senior. Concentre-toi sur les bugs de correction et la
clarté. Sois concis : liste les problèmes par sévérité, avec fichier:ligne.

Frontmatter : name, description (déclenche la délégation), tools, model, effort, permissionMode. Le corps après --- est le system prompt.

5. Serveurs MCP — .mcp.json

Un plugin peut embarquer des serveurs MCP (Model Context Protocol) pour brancher des outils tiers (GitHub, bases de données, SaaS). C'est l'objet du module M7.

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

Composants plus avancés (confirmés mais hors socle) : un plugin peut aussi exposer des serveurs LSP (.lsp.json, intelligence de code), des monitors de tâches de fond (monitors/monitors.json, ex. suivre un fichier de logs) et des exécutables (bin/, ajoutés au PATH). À survoler ici, à approfondir selon les besoins.

Skill vs commande vs sub-agent vs hook vs MCP

C'est la confusion la plus fréquente. Règle de décision :

Mnémonique : skill = savoir-faire, sub-agent = collègue spécialisé, hook = réflexe automatique, MCP = prise vers le monde extérieur.

Les hooks : événements et automatisation

Un hook s'accroche à un événement et lance une commande. Les événements couvrent tout le cycle de vie d'une session. En voici un échantillon représentatif (la liste réelle en compte une trentaine et évolue — vérifiez la doc) :

Exemple : lancer le linter après chaque écriture ou édition de fichier (hooks/hooks.json) :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npx eslint --fix \"$CLAUDE_FILE_PATHS\"" }
        ]
      }
    ]
  }
}

Les hooks se déclarent dans settings.json / settings.local.json (niveau utilisateur/projet) ou dans hooks/hooks.json d'un plugin. Cas typiques : bloquer une commande destructrice (PreToolUse), lint/format/test (PostToolUse), notifier (Notification).

⚠️ Les hooks exécutent du code arbitraire : c'est puissant et c'est un vecteur de risque. N'installez que des plugins de confiance (cf. section 8).

Arborescence complète d'un plugin

mon-plugin-qualite/
├── .claude-plugin/
│   └── plugin.json          # manifeste (seul fichier obligatoire)
├── skills/
│   └── revue-securite/
│       └── SKILL.md         # une skill
├── commands/
│   └── deploy.md            # une commande slash (legacy)
├── agents/
│   └── reviewer.md          # un sub-agent
├── hooks/
│   └── hooks.json           # hooks (ex. lint post-écriture)
├── .mcp.json                # serveurs MCP embarqués
└── README.md

Tous les sous-dossiers sont optionnels : un plugin peut ne contenir qu'une skill, ou que des hooks. La force du format est de pouvoir tout regrouper de façon cohérente.

Marketplaces : marketplace.json, commandes, hébergement

Une marketplace est un catalogue de plugins, décrit par un marketplace.json (hébergé sur un repo Git, une URL ou un dossier local).

{
  "name": "acme-plugins",
  "owner": { "name": "Acme", "email": "dev@acme.io" },
  "plugins": [
    {
      "name": "mon-plugin-qualite",
      "source": { "source": "github", "repo": "acme/mon-plugin-qualite" },
      "description": "Lint + revue + reviewer agent"
    }
  ]
}

Champs racine : name (✅), owner (✅), plugins (✅), plus description, version. Chaque entrée de plugins[] requiert name et source ; le reste (description, version, author, category, keywords…) est optionnel.

Valeurs de source : chemin relatif ("./plugins/x"), GitHub ({ source: "github", repo: "owner/repo" }), URL Git, sous-dossier Git, ou npm.

Commandes (slash) côté utilisateur :

/plugin marketplace add acme/marketplace-repo   # ajouter un catalogue (owner/repo GitHub)
/plugin marketplace list                        # lister les marketplaces
/plugin install mon-plugin-qualite@acme-plugins # installer un plugin
/plugin marketplace update acme-plugins         # rafraîchir le catalogue
/plugin marketplace remove acme-plugins         # retirer

Héberger sa marketplace : un simple repo GitHub contenant marketplace.json (et les plugins, ou des pointeurs vers leurs repos). Pour une équipe, on peut la pré-déclarer dans .claude/settings.json du projet pour que tous l'aient automatiquement.

Marketplaces officielles, installation et sécurité

• anthropics/claude-plugins-official — catalogue curé par Anthropic, enregistré automatiquement au premier lancement. Les plugins individuels doivent cependant être installés manuellement avec /plugin install {nom}@claude-plugins-official.
• anthropics/claude-plugins-community — contributions tierces (validées). Le marketplace communautaire doit être ajouté manuellement avec /plugin marketplace add anthropics/claude-plugins-community, puis les plugins installés individuellement avec /plugin install {nom}@claude-community.

Côté création, la publication d'une skill passe par une pull request sur le dépôt GitHub anthropics/skills, tandis que la publication d'un plugin officiel à la marketplace Claude Code passe par un formulaire de soumission (clau.de/plugin-directory-submission). Il n'existe pas de CLI anthropic skills publish ni de revenue-share (détaillé dans M14).

Sécurité — à enseigner systématiquement :

• Un plugin peut exécuter du code arbitraire (hooks, bin/, serveurs MCP). Traitez-le comme une dépendance.
• N'installez que depuis des sources de confiance ; lisez les hooks et les commandes avant d'activer.
• Combinez avec des deny rules dans settings.json (ex. interdire Bash(rm -rf:*)) et le mode permission adapté.
• Épinglez une version/SHA pour les usages sensibles plutôt que de suivre HEAD.

Plugin vs Claude Agent SDK vs MEMORY.md

Trois choses souvent confondues :

À noter : skills et SDK partagent le standard ouvert AgentSkills — une SKILL.md écrite pour Claude Code est réutilisable côté SDK. (L'« Anthropic SDK » historique est aujourd'hui le Claude Agent SDK.)

Atelier : créer et publier un mini-plugin (45 min)

Livrable : un plugin qualite-mini contenant une skill, un sub-agent et un hook, publié sur une marketplace GitHub perso.

Étapes :

1. Initialiser la structure : .claude-plugin/plugin.json (avec name, version, description).
2. Ajouter une skill skills/revue-securite/SKILL.md (frontmatter + instructions).
3. Ajouter un sub-agent agents/reviewer.md.
4. Ajouter un hook hooks/hooks.json : PostToolUse sur Write|Edit qui lance le formateur.
5. Tester en local : /plugin marketplace add ./chemin/vers/dossier puis /plugin install qualite-mini@..., et vérifier que la skill apparaît dans /, que le hook se déclenche.
6. Publier : pousser sur un repo GitHub avec un marketplace.json, puis installer depuis owner/repo.

Critères de succès :

• ✅ plugin.json valide, plugin installable
• ✅ La skill est invocable (par / et par Claude)
• ✅ Le hook se déclenche sur Write/Edit
• ✅ Le sub-agent est délégable
• ✅ Note de sécurité rédigée (ce que le plugin exécute, deny rules conseillées)

Pour aller plus loin

• 📖 Plugins — créer
• 📖 Référence plugins (manifeste, composants)
• 📖 Marketplaces de plugins
• 📖 Skills · Hooks · Sub-agents
• 🎯 Modules complémentaires : M7 MCP OAuth + écosystème (brancher des serveurs MCP), M14 Skills marketplace (packaging, distribution, publication)