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"
}
]
}
]
}
}
{
"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émantique
MAJOR.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 plugin
CHANGELOG.mdpour enregistrer le contenu de mise à jour de version