Ajouter des composants à un plugin

​

Explorez le répertoire du plugin

• Une skill de révision et une commande about
• Un sous-agent de révision de sécurité
• Un hook qui formate les fichiers après que Claude les édite, et le dossier scripts/ qu’il appelle
• Un moniteur de journal
• Un style de sortie et un thème de couleur
• Un workflow d’audit de route
• Un exécutable hello-plugin
• Les paramètres par défaut
• Un serveur MCP local et un serveur de langage Go

​

Ajouter chaque type de composant

​

Skills

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• Nom de la commande : /<plugin>:<directory>, donc skills/review/SKILL.md dans my-plugin est /my-plugin:review. Si vous définissez name dans le frontmatter, il remplace le dernier segment et le préfixe du plugin reste. Consultez comment une skill obtient son nom de commande
• Qui l’invoque : Claude, l’utilisateur, ou les deux, contrôlé par le frontmatter. Consultez Contrôler qui invoque une skill

• Répertoires supplémentaires : listez-les dans la clé de manifeste skills. Ils s’ajoutent au scan skills/ par défaut plutôt que de le remplacer, contrairement à commands et agents
• Une seule skill à la racine du plugin : sans répertoire skills/ et sans clé de manifeste skills, un SKILL.md à la racine du plugin charge comme une skill. Définissez name dans son frontmatter, car sinon une installation marketplace nomme la skill d’après son répertoire de cache plutôt que votre plugin

​

Commandes

​

Définir les commandes dans le manifeste

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Agents

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

Organiser les agents dans des sous-dossiers

• Frontmatter name : il remplace seulement le nom du fichier, donc name: audit dans agents/review/security.md charge comme my-plugin:review:audit
• Champ de manifeste agents : un fichier que vous listez là charge sans noms de sous-dossier, donc "agents": "./custom/review/security.md" charge comme my-plugin:security

​

Champs de frontmatter dans les agents du plugin

• Champs supportés : name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, et la clé cacheTtl de experimental. La seule valeur isolation valide est "worktree". Consultez champs de frontmatter supportés pour ce que chacun fait
• Champs ignorés : permissionMode, hooks, mcpServers, et initialPrompt. Un fichier d’agent ne peut pas ajouter des hooks ou des serveurs MCP par lui-même, donc ajoutez-les comme plugin hooks et serveurs MCP à la place
• Frontmatter qui ne s’analyse pas : l’agent charge quand même avec chaque champ ignoré. Il est nommé d’après le fichier, et sa description lit Agent from my-plugin plugin. Exécutez claude plugin validate dans votre shell pour trouver ces fichiers

​

Hooks

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

​

Quand les hooks du plugin se déclenchent

​

Environnement, guillemets et correspondance des outils MCP

• Environnement : chaque processus de hook reçoit CLAUDE_PLUGIN_ROOT et CLAUDE_PLUGIN_DATA dans son environnement, plus CLAUDE_PLUGIN_OPTION_<KEY> pour chaque valeur de configuration utilisateur, donc votre script peut les lire de là
• Guillemets : quand command n’a pas args, il s’exécute via un shell, donc enveloppez le chemin ${CLAUDE_PLUGIN_ROOT} entre guillemets doubles, comme l’exemple hooks/hooks.json sous Hooks le fait, pour garder le chemin développé un mot shell. Quand vous passez args à la place, chaque élément est passé comme un argument sans shell et n’a besoin d’aucun guillemet. Consultez forme exec et forme shell
• Correspondance des outils MCP du plugin : un outil d’un serveur MCP que ce plugin déclare est nommé mcp__plugin_<plugin>_<server>__<tool>, donc écrivez ce nom complet dans le matcher. Un matcher sur le nom du serveur seul ne se déclenche jamais. Consultez Correspondance des outils MCP

​

Serveurs MCP

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

Atteindre les utilisateurs sur claude.ai et Cowork

​

Noms de serveur, noms d’outils et rechargements

• Nom du serveur : plugin:<plugin>:<server>, donc le serveur db dans my-plugin est plugin:my-plugin:db dans /mcp. Utilisez la même forme pour nommer le serveur dans un hook mcp_tool
• Noms d’outils : mcp__plugin_<plugin>_<server>__<tool>, donc un outil query sur ce serveur db est mcp__plugin_my-plugin_db__query. C’est le nom à utiliser dans les règles de permission et les matchers de hook
• Substitution : ${CLAUDE_PLUGIN_ROOT} et les autres variables de chemin sont substituées dans command, args, et env. Aucun guillemet n’est nécessaire dans args, car chaque élément est passé comme un argument
• Rechargement : quand l’utilisateur exécute /reload-plugins et que le rechargement s’applique, un serveur dont la configuration est inchangée garde sa connexion. Un serveur dont la configuration a changé se reconnecte, et un que vous avez supprimé se déconnecte

​

Inclure un serveur MCPB emballé

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

​

Serveurs LSP

{
  "gopls": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

• Binaire manquant : Claude Code démarre command par nom depuis le PATH de l’utilisateur. Quand le binaire n’est pas là, le serveur échoue à démarrer et claude --debug enregistre LSP server <name> failed to start
• Conflits d’extension : quand deux serveurs activés revendiquent la même extension, le premier enregistré gère ces fichiers et l’autre n’est pas utilisé pour eux, que les serveurs proviennent d’un plugin ou de deux. L’onglet Errors de /plugin montre l’avertissement LSP server "<name>" is not used for <ext> files

​

Exécutables

#!/bin/bash
echo "hello from my-plugin"

​

Paramètres par défaut

{
  "agent": "security-reviewer"
}

• Fichier sur manifeste : quand les deux existent et settings.json définit au moins une clé supportée, settings.json s’applique et le settings du manifeste est ignoré
• Paramètres utilisateur sur paramètres par défaut du plugin : dans les sources de paramètres, les paramètres par défaut du plugin sont la couche la plus basse, donc un agent personnel de l’utilisateur dans ~/.claude/settings.json remplace le vôtre
• Deux plugins définissent la même clé : la valeur du plugin chargé en dernier s’applique, et claude --debug enregistre overrides setting

​

Thèmes et styles de sortie

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

​

Canaux

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

​

Moniteurs

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

• Sessions interactives seulement : les moniteurs du plugin démarrent dans une session interactive et jamais en mode non-interactif avec le drapeau -p. Ils démarrent aussi seulement où l’outil Monitor est disponible
• Pas de configuration utilisateur : command obtient les variables de chemin et ${ENV_VAR} de l’environnement, mais jamais ${user_config.*}. Un moniteur qui en référence un ne démarre pas, et les processus de moniteur ne reçoivent pas non plus CLAUDE_PLUGIN_OPTION_<KEY>
• Désactivation en cours de session : si vous désactivez un plugin en cours de session, Claude Code n’arrête pas les moniteurs qui s’exécutent déjà. Ils s’arrêtent quand la session se termine

​

Demander à l’utilisateur des valeurs de configuration

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

Quand la boîte de dialogue de configuration apparaît

• Installe le plugin dans /plugin
• Exécute /plugin install <plugin>@<marketplace> à l’intérieur d’une session
• Active le plugin à partir de l’onglet Installed dans /plugin

​

Référencer les chemins du plugin et stocker les données

• ${CLAUDE_PLUGIN_ROOT} : le répertoire d’installation du plugin. Chaque version a son propre répertoire de cache, donc le chemin change quand le plugin se met à jour. N’écrivez pas d’état là
• ${CLAUDE_PLUGIN_DATA} : un répertoire qui survit aux mises à jour, pour node_modules, les environnements virtuels, et les caches. Il se résout en ~/.claude/plugins/data/<id>/ et est créé quand d’abord référencé
• ${CLAUDE_PROJECT_DIR} : la racine du projet, la même valeur que les hooks reçoivent

​

Installer les dépendances dans le répertoire de données

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

​

Étapes suivantes

• Référence du manifeste du plugin : champs plugin.json, règles de chemin, et la disposition standard
• Tester les plugins avec des evals : vérifiez que les composants que vous avez ajoutés changent le comportement de Claude de la façon que vous avez l’intention
• Publier et distribuer un plugin : versionnez le plugin et mettez-le dans une marketplace
• Dépanner les plugins : quoi faire quand un composant ne charge pas ou qu’un hook ne se déclenche pas