Manuel de référence des plugins Claude Code

Les plugins sont lecœur de l'expansion fonctionnelle, qui peuvent vous aider à ajouter des commandes slash personnalisées, des sous-agents, des hooks d'automatisation et d'autres capacités. Ce tutoriel couvre lescomposants principaux、spécifications de configuration、Gestion de la CLItrois dimensions, pour vous aider rapidement à maîtriser les points clés de l'utilisation et du développement des plugins.


Composants principaux des plugins : 5 types de capacités d'extension

Les plugins réalisent l'extension fonctionnelle grâce à 5 types de composants, chacun avec des emplacements de stockage et des exigences de format fixes.

Type de composant Emplacement de stockage Format de fichier Fonction principale
Commande Répertoire racine du plugincommands/ Fichier Markdown avec métadonnées frontmatter Ajouter des commandes slash personnalisées, par ex.,/deploy /code-review
Agent Répertoire racine du pluginagents/ Fichier Markdown Fournir des sous-agents dédiés, tels que des agents de revue de code, des agents de test de performance
Compétence Répertoire racine du pluginskills/ contenantSKILL.mdrépertoire Permettre à Claude de reconnaître automatiquement des scénarios et de les invoquer, par exemple, analyse de PDF, visualisation de données
Hook Répertoire racine du pluginhooks/hooks.jsonouplugin.jsonEn ligne Fichier de configuration JSON Écouter les événements de Claude et répondre automatiquement, par exemple, formater automatiquement le code après l'édition d'un fichier
Serveur MCP Répertoire racine du plugin.mcp.jsonouplugin.jsonEn ligne Fichier de configuration JSON Connecter des outils externes (tels que GitHub, Jira) et transformer leurs fonctionnalités en outils utilisables par Claude
Serveur LSP Répertoire racine du plugin.lsp.jsonouplugin.jsonEn ligne Fichier de configuration JSON Fournir des capacités d'intelligence de code, telles que la vérification de la syntaxe, l'accès à la définition, les infobulles

Exemples de composants clés

1. Exemple de configuration de Hook: Formater automatiquement après l'édition d'un fichier

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

: Prise en charge des suggestions intelligentes pour le langage Go

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

Spécifications de base du plugin : portée d'installation et manifeste

1. Portée d'installation : détermine la plage de disponibilité du plugin

Lors de l'installation d'un plugin, vous devez choisir une portée. Différentes portées correspondent à différents fichiers de configuration et scénarios d'utilisation :

Portée Chemin du fichier de configuration Scénario d'application
user ~/.claude/settings.json Personnelle, commune à tous les projets (par défaut)
project .claude/settings.json Équipe, synchronisée avec le dépôt
local .claude/settings.local.json Spécifique au projet, est.gitignoreignoré
managed managed-settings.json Plugin géré, en lecture seule et mis à jour automatiquement

2. Manifeste du plugin :plugin.jsonPoints clés à connaître

plugin.jsonest lefichier de configuration principal du plugin, stocké dans.claude-plugin/le répertoire, utilisé pour définir les métadonnées du plugin et les chemins des composants.

a. Champs obligatoires

Champ Type Exigence Exemple
name string Identifiant unique, format kebab-case "go-code-helper"

b. Champs de métadonnées principaux

{
  "version": "1.0.0", // 语义化版本
  "description": "提供 Go 语言代码智能和调试能力",
  "author": {
    "name": "Dev Team",
    "email": "dev@example.com"
  },
  "license": "MIT"
}

c. Champs de chemin des composants

Sert à spécifier l'emplacement des composants personnalisés. Le chemin doit êtrerelatif au répertoire racine du pluginet./commencer par :

{
  "commands": ["./custom-commands/deploy.md"],
  "agents": "./custom-agents/",
  "hooks": "./hooks.json"
}

d. Variables d'environnement

${CLAUDE_PLUGIN_ROOT}Chemin absolu du répertoire racine du plugin, utilisé pour référencer des fichiers au sein du plugin dans les scripts et les configurations, en évitant les erreurs de chemin.

3. Structure standard des répertoires de plugin

my-plugin/
├── .claude-plugin/           # 元数据目录
│   └── plugin.json          # 插件清单(必需)
├── commands/                 # 自定义斜杠命令
├── agents/                   # 子代理定义
├── skills/                   # 自动技能
├── hooks/                    # 事件钩子配置
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 服务器配置
└── scripts/                 # 钩子执行脚本

Remarque :commands/ agents/Les répertoires de composants tels que ceux-ci doivent se trouver dans lerépertoire racine du pluginet ne peuvent pas être placés.claude-plugin/à l'intérieur.


Gestion des plugins : Référence rapide des commandes CLI

Via la CLI Claude Code, vous pouvez rapidement installer, désinstaller, activer/désactiver des plugins, adapté aux scénarios de scripting et d'automatisation.

Commande Objectif Exemple
claude plugin install <插件名> -s <范围> Installer un plugin claude plugin install go-lsp --scope project
claude plugin uninstall <插件名> Désinstaller le plugin claude plugin uninstall go-lsp
claude plugin enable <插件名> Activer un plugin désactivé claude plugin enable go-lsp
claude plugin disable <插件名> Désactiver le plugin (sans le désinstaller) claude plugin disable go-lsp
claude plugin update <插件名> Mettre à jour le plugin vers la dernière version claude plugin update go-lsp

Débogage et dépannage : Solutions aux problèmes courants

1. Commandes de débogage

Exécutez la commande suivante pour afficher les détails de chargement des plugins et localiser les problèmes de configuration et de chargement :

claude --debug

Vous pouvez consulter : l'état de chargement des plugins, les erreurs de syntaxe du manifeste, l'état d'enregistrement des composants, les journaux d'initialisation du serveur MCP/LSP.

2. Problèmes fréquents et solutions

Problème Cause Solution
Plugin non chargé plugin.jsonErreur de syntaxe ou champs obligatoires manquants useclaude plugin validateValidez la syntaxe JSON, ajoutez le manquantnamechamp
Commandes personnalisées non affichées Fichier de commande placé dans.claude-plugin/à l'intérieur vacommands/Déplacez le répertoire vers le répertoire racine du plugin
Script de hook non exécuté Le script n'a pas la permission d'exécution Exécutezchmod +x scripts/your-script.shpour accorder la permission
Invite LSPExecutable not found Serveur de langage correspondant non installé Installez le fichier binaire (par ex., Go nécessite l'installationgopls)
Échec du démarrage du serveur MCP Le chemin utilise un chemin absolu, n'utilisant pas${CLAUDE_PLUGIN_ROOT} Remplacez par une référence à une variable d'environnement, telle que${CLAUDE_PLUGIN_ROOT}/server

Gestion et distribution des versions

  • Spécification de version: Suivez le versionnage sémantiqueMAJOR.MINOR.PATCH, par exemple1.2.3
  • Canaux de distribution: Distribuez via la marketplace des plugins, ou partagez directement le répertoire du plugin (doit inclure la structure complète)
  • Journal des modifications: Il est recommandé d'ajouter dans le répertoire racine du pluginCHANGELOG.mdpour enregistrer le contenu de mise à jour de version
Autres extensions