Référence des plugins

​

Référence des composants de plugin

​

Skills

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

• Les skills et les commandes sont découverts automatiquement lors de l’installation du plugin
• Claude peut les invoquer automatiquement en fonction du contexte de la tâche
• Les skills peuvent inclure des fichiers de support à côté de SKILL.md

​

Agents

---
name: agent-name
description: Ce dans quoi cet agent se spécialise et quand Claude devrait l'invoquer
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Invite système détaillée pour l'agent décrivant son rôle, son expertise et son comportement.

• Les agents apparaissent dans la saisie semi-automatique @-mention sous leur nom délimité, tel que my-plugin:code-reviewer, une fois que le plugin est activé
• 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

​

Hooks

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

• command : exécuter des commandes shell ou des scripts
• http : envoyer l’événement JSON en tant que requête POST à une URL
• mcp_tool : appeler un outil sur un serveur MCP configuré
• prompt : évaluer une invite avec un LLM (utilise l’espace réservé $ARGUMENTS pour le contexte)
• agent : exécuter un vérificateur agentic avec des outils pour les tâches de vérification complexes

​

Serveurs 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"]
    }
  }
}

• 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 de manière transparente avec les outils existants de Claude
• Les serveurs de plugin peuvent être configurés indépendamment des serveurs MCP de l’utilisateur

​

Serveurs LSP

• Diagnostics instantanés : Claude voit les erreurs et les avertissements immédiatement après chaque modification
• Navigation de code : aller à la définition, trouver les références et les informations au survol
• Sensibilisation au langage : informations de type et documentation pour les symboles de code

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

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

​

Moniteurs

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Changements de statut de déploiement"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Journal d'erreurs de l'application",
    "when": "on-skill-invoke:debug"
  }
]

​

Thèmes

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

​

Portées d’installation des plugins

​

Plugins du répertoire des skills

​

Choisir d’où le plugin se charge

• Les serveurs MCP qu’il déclare passent par l’approbation par serveur identique qu’un .mcp.json de projet
• Les serveurs LSP démarrent seulement après que vous fassiez confiance à l’espace de travail
• Les moniteurs en arrière-plan ne se chargent pas

​

Modifier, recharger et désactiver un plugin du répertoire des skills

claude plugin disable my-tool@skills-dir

​

Schéma du manifeste du plugin

​

Schéma complet

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

Champs obligatoires

​

Champs non reconnus

claude plugin validate ./my-plugin --strict

​

Champs de métadonnées

​

Activation par défaut

• Le paramètre de l’utilisateur : une entrée pour le plugin dans enabledPlugins à n’importe quelle portée de paramètres. Une fois écrite, elle persiste entre les mises à jour et réinstallations du plugin, donc changer defaultEnabled dans une version ultérieure ne bascule pas un utilisateur existant.
• Une exigence de dépendance : quand un plugin est requis par un autre qui est actif, Claude Code écrit true pour lui au moment de l’installation ou de l’activation. Cela lui donne un paramètre explicite, donc sa propre valeur par défaut ne s’applique plus. Consultez Activer ou désactiver un plugin avec des dépendances.

​

Champs de chemin de composant

​

Composants expérimentaux

​

Configuration utilisateur

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "Point de terminaison API",
      "description": "Le point de terminaison API de votre équipe"
    },
    "api_token": {
      "type": "string",
      "title": "Jeton API",
      "description": "Jeton d'authentification API",
      "sensitive": true
    }
  }
}

​

Canaux

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Jeton de bot",
          "description": "Jeton de bot Telegram",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "ID du propriétaire",
          "description": "Votre ID utilisateur Telegram"
        }
      }
    }
  ]
}

​

Règles de comportement des chemins

• Remplace le répertoire par défaut : commands, agents, outputStyles, experimental.themes, experimental.monitors. Par exemple, quand le manifeste spécifie commands, le répertoire par défaut commands/ n’est pas analysé. Pour conserver le répertoire par défaut et en ajouter d’autres, listez-le explicitement : "commands": ["./commands/", "./extras/"]
• S’ajoute au répertoire par défaut : skills. Le répertoire par défaut skills/ est toujours analysé, et les répertoires listés dans skills sont chargés à côté de lui. Exception : pour une entrée de marketplace dont la source se résout à la racine de la marketplace, déclarer des sous-répertoires spécifiques remplace l’analyse par défaut skills/
• Règles de fusion propres : hooks, Serveurs MCP, et Serveurs LSP. Consultez chaque section pour savoir comment plusieurs sources se combinent

• Tous les chemins doivent être relatifs à la racine du plugin et commencer par ./
• Les composants des chemins personnalisés utilisent les mêmes règles de nommage et d’espace de noms
• Plusieurs chemins peuvent être spécifiés sous forme de tableaux
• Quand un chemin de skill pointe vers un répertoire qui contient directement un SKILL.md, par exemple "skills": ["./"] pointant vers la racine du plugin, le champ frontmatter name dans SKILL.md détermine le nom d’invocation de la skill. Cela donne un nom stable indépendamment du répertoire d’installation. Si name n’est pas défini dans le frontmatter, le nom de base du répertoire est utilisé comme secours.

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

​

Variables d’environnement

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

​

Répertoire de données persistantes

{
  "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\""
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

​

Mise en cache des plugins et résolution des fichiers

• Via claude --plugin-dir ou claude --plugin-url, pour la durée d’une session.
• Via une marketplace, installés pour les sessions futures.

​

Limitations de traversée de répertoires

​

Partager des fichiers au sein d’une marketplace avec des liens symboliques

• Au sein du répertoire propre du plugin : le lien symbolique est préservé en tant que lien symbolique relatif dans le cache, donc il continue de se résoudre à la cible copiée au moment de l’exécution.
• Ailleurs au sein de la même marketplace : le lien symbolique est déréférencé. Le contenu de la cible est copié dans le cache à sa place. Cela permet au répertoire skills/ d’un meta-plugin de créer un lien vers les skills définis par d’autres plugins de la marketplace.
• En dehors de la marketplace : le lien symbolique est ignoré pour des raisons de sécurité. Cela empêche les plugins de récupérer des fichiers hôtes arbitraires tels que les chemins système dans le cache.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Structure du répertoire des plugins

​

Disposition standard des plugins

enterprise-plugin/
├── .claude-plugin/           # Répertoire de métadonnées (optionnel)
│   └── plugin.json             # manifeste du plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills en tant que fichiers markdown plats
│   ├── status.md
│   └── logs.md
├── agents/                   # Définitions de subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Définitions de style de sortie
│   └── terse.md
├── themes/                   # Définitions de thème de couleur
│   └── dracula.json
├── monitors/                 # Configurations de moniteur en arrière-plan
│   └── monitors.json
├── hooks/                    # Configurations des hooks
│   ├── hooks.json           # Configuration principale des hooks
│   └── security-hooks.json  # Hooks supplémentaires
├── bin/                      # Exécutables de plugin ajoutés à PATH
│   └── my-tool               # Invocable en tant que commande nue dans l'outil Bash
├── settings.json            # Paramètres par défaut pour le plugin
├── .mcp.json                # Définitions du serveur MCP
├── .lsp.json                # Configurations du serveur LSP
├── scripts/                 # Scripts de hooks et d'utilitaires
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Fichier de licence
└── CHANGELOG.md             # Historique des versions

​

Référence des emplacements de fichiers

​

Référence des commandes CLI

​

plugin init

claude plugin init <name> [options]

• <name> : Nom du plugin. Devient l’espace de noms de la skill et le nom du répertoire sous ~/.claude/skills/, donc il ne peut pas contenir d’espaces ou de séparateurs de chemin.

# Générer un plugin minimal
claude plugin init my-helper

# Générer avec des dossiers de skill et de hook
claude plugin init my-helper --with skills hooks

# Écraser un scaffold existant
claude plugin init my-helper --force

​

plugin install

claude plugin install <plugin> [options]

• <plugin> : Nom du plugin ou plugin-name@marketplace-name pour une marketplace spécifique

# Installer dans la portée utilisateur (par défaut)
claude plugin install formatter@my-marketplace

# Installer dans la portée du projet (partagé avec l'équipe)
claude plugin install formatter@my-marketplace --scope project

# Installer dans la portée locale (ignorée par git)
claude plugin install formatter@my-marketplace --scope local

​

plugin uninstall

claude plugin uninstall <plugin> [options]

• <plugin> : Nom du plugin ou plugin-name@marketplace-name

​

plugin prune

claude plugin prune [options]

​

plugin enable

claude plugin enable <plugin> [options]

• <plugin> : Nom du plugin ou plugin-name@marketplace-name

​

plugin disable

claude plugin disable <plugin> [options]

• <plugin> : Nom du plugin ou plugin-name@marketplace-name

​

plugin update

claude plugin update <plugin> [options]

• <plugin> : Nom du plugin ou plugin-name@marketplace-name

​

plugin list

claude plugin list [options]

​

plugin details

claude plugin details <name>

• <name> : Nom du plugin ou plugin-name@marketplace-name

• Always-on : tokens ajoutés à chaque session par le texte de liste du plugin, comme les descriptions de compétences, les descriptions d’agents et les noms de commandes, indépendamment du fait qu’un composant se déclenche ou non.
• On-invoke : tokens qu’un composant coûte quand il se déclenche. Affiché par composant, pas comme un total de plugin, car une session typique n’invoque qu’un sous-ensemble de composants.

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

​

plugin tag

claude plugin tag [options]

​

Outils de débogage et de développement

​

Commandes de débogage

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

​

Problèmes courants

​

Exemples de messages d’erreur

• Invalid JSON syntax: Unexpected token } in JSON at position 142 : vérifiez les virgules manquantes, les virgules supplémentaires ou les chaînes non citées
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required : un champ obligatoire est manquant
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ... : erreur de syntaxe JSON

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories. : le chemin de commande existe mais ne contient aucun fichier de commande valide
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path. : le chemin source dans marketplace.json pointe vers un répertoire inexistant
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components. : supprimez les définitions de composants en double ou supprimez strict: false dans l’entrée de la marketplace

​

Dépannage des hooks

1. Vérifiez que le script est exécutable : chmod +x ./scripts/your-script.sh
2. Vérifiez la ligne shebang : La première ligne doit être #!/bin/bash ou #!/usr/bin/env bash
3. Vérifiez que le chemin utilise ${CLAUDE_PLUGIN_ROOT} : "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Testez le script manuellement : ./scripts/your-script.sh

1. Vérifiez que le nom de l’événement est correct (sensible à la casse) : PostToolUse, pas postToolUse
2. Vérifiez que le motif de correspondance correspond à vos outils : "matcher": "Write|Edit" pour les opérations de fichier
3. Confirmez que le type de hook est valide : command, http, mcp_tool, prompt, ou agent

​

Dépannage du serveur MCP

1. Vérifiez que la commande existe et est exécutable
2. Vérifiez que tous les chemins utilisent la variable ${CLAUDE_PLUGIN_ROOT}
3. Vérifiez les journaux du serveur MCP : claude --debug affiche les erreurs d’initialisation
4. Testez le serveur manuellement en dehors de Claude Code

1. Assurez-vous que le serveur est correctement configuré dans .mcp.json ou plugin.json
2. Vérifiez que le serveur implémente correctement le protocole MCP
3. Vérifiez les délais d’expiration de la connexion dans la sortie de débogage

​

Erreurs de structure de répertoire

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Seul le manifeste ici
├── commands/            ← Au niveau racine
├── agents/              ← Au niveau racine
└── hooks/               ← Au niveau racine

1. Exécutez claude --debug et recherchez les messages « loading plugin »
2. Vérifiez que chaque répertoire de composants est listé dans la sortie de débogage
3. Vérifiez que les permissions de fichier permettent de lire les fichiers du plugin

​

Référence de distribution et de versioning

​

Gestion des versions

1. Le champ version dans le plugin.json du plugin
2. Le champ version dans l’entrée marketplace du plugin dans marketplace.json
3. Le SHA du commit git du plugin source, pour les sources github, url, git-subdir et relative-path dans une marketplace hébergée sur git
4. unknown, pour les sources npm ou les répertoires locaux ne se trouvant pas dans un référentiel git

​

Voir aussi

• Plugins - Tutoriels et utilisation pratique
• Marketplaces de plugins - Création et gestion des marketplaces
• Skills - Détails du développement des skills
• Subagents - Configuration et capacités des agents
• Hooks - Gestion des événements et automatisation
• MCP - Intégration des outils externes
• Paramètres - Options de configuration pour les plugins