Guide Pratique

Rappel rapide

Dans l'article précédent, nous avons exploré les concepts fondamentaux des Plugins : il s'agit du mécanisme de Claude Code pour empaqueter et distribuer des workflows, regroupant Commands, Skills, Agents, Hooks et d'autres composants en une seule unité pour le partage en équipe et la distribution communautaire. Cet article adopte une approche pratique et vous guide à travers le processus complet, de la création à la publication.

Créer votre premier Plugin

Etape 1 : Créer la structure de répertoires

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin
mkdir my-first-plugin/commands

Etape 2 : Créer le manifeste du plugin

Définissez les métadonnées de votre plugin dans .claude-plugin/plugin.json :

{
  "name": "my-first-plugin",
  "description": "我的第一个 Claude Code 插件",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Etape 3 : Ajouter des commandes slash

Créez des fichiers Markdown dans le répertoire commands/. Chaque fichier correspond à une commande :

commands/hello.md :

---
description: 向用户发送友好的问候
---

# Hello 命令

请热情地问候用户，并询问今天可以帮助他们做什么。

Etape 4 : Tester le plugin

Utilisez le drapeau --plugin-dir pour charger votre plugin local et le tester :

claude --plugin-dir ./my-first-plugin

Exécutez la commande dans Claude Code :

/my-first-plugin:hello

Etape 5 : Ajouter des arguments de commande

Les commandes prennent en charge les arguments fournis par l'utilisateur. Mettez à jour hello.md :

---
description: 向指定用户发送个性化问候
---

# Hello 命令

请热情地问候名为 "$ARGUMENTS" 的用户，并询问今天可以帮助他们做什么。

如果用户没有提供名字，就使用"朋友"作为称呼。

Testez la commande avec des arguments :

/my-first-plugin:hello 小明

Marqueurs d'arguments pris en charge :

• $ARGUMENTS - Toute la saisie de l'utilisateur
• $1, $2, $3 - Arguments individuels

Ajouter d'autres composants

Ajouter des Skills

Créez un répertoire skills/. Chaque Skill est un dossier contenant un fichier SKILL.md :

my-first-plugin/
├── skills/
│   └── code-review/
│       └── SKILL.md

skills/code-review/SKILL.md :

---
name: code-review
description: 审查代码质量、安全性和可维护性
---

当审查代码时，请检查以下方面：

1. **代码组织**：结构是否清晰
2. **错误处理**：异常是否被妥善处理
3. **安全隐患**：是否存在安全漏洞
4. **测试覆盖**：关键逻辑是否有测试

输出格式：
- 严重问题（必须修复）
- 警告（建议修复）
- 建议（可以改进）

Ajouter des Subagents

Créez un répertoire agents/ :

agents/code-reviewer.md :

---
name: code-reviewer
description: 专业的代码审查代理，用于代码质量检查
tools: Read, Grep, Glob, Bash
---

你是一位资深的代码审查专家。

当被调用时：
1. 运行 git diff 查看最近的更改
2. 分析修改的文件
3. 提供结构化的审查反馈

审查清单：
- 代码可读性和命名规范
- 错误处理和边界条件
- 安全漏洞（如注入、敏感信息泄露）
- 性能优化机会

Ajouter des Hooks

Les Hooks vous permettent d'exécuter automatiquement des scripts lorsque des événements spécifiques se produisent. Créez hooks/hooks.json :

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

Important : Utilisez la variable d'environnement ${CLAUDE_PLUGIN_ROOT} pour référencer les fichiers au sein du répertoire de votre plugin, garantissant que les chemins se résolvent correctement quel que soit l'emplacement d'installation du plugin.

Créez le script correspondant scripts/format-code.sh :

#!/bin/bash
# 格式化代码
cd "$CLAUDE_PROJECT_DIR" && make format 2>/dev/null || true

N'oubliez pas de définir les permissions d'exécution :

chmod +x scripts/format-code.sh

Ajouter des serveurs MCP

Si votre plugin a besoin de se connecter à des systèmes externes, créez .mcp.json :

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

Structure complète du Plugin

Un Plugin entièrement fonctionnel pourrait ressembler à ceci :

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # 插件清单
├── commands/
│   ├── review.md             # 代码审查命令
│   ├── deploy.md             # 部署命令
│   └── test.md               # 测试命令
├── agents/
│   ├── code-reviewer.md      # 代码审查代理
│   └── debugger.md           # 调试代理
├── skills/
│   └── code-standards/
│       └── SKILL.md          # 代码规范知识
├── hooks/
│   └── hooks.json            # 事件钩子配置
├── scripts/
│   ├── format-code.sh        # 格式化脚本
│   └── run-tests.sh          # 测试脚本
├── .mcp.json                  # MCP 配置
├── LICENSE
├── README.md
└── CHANGELOG.md

Le plugin.json correspondant :

{
  "name": "dev-toolkit",
  "version": "1.0.0",
  "description": "开发者工具箱：代码审查、测试、部署一站式解决方案",
  "author": {
    "name": "Your Team",
    "email": "team@example.com"
  },
  "homepage": "https://github.com/you/dev-toolkit",
  "repository": "https://github.com/you/dev-toolkit",
  "license": "MIT",
  "keywords": ["development", "code-review", "deployment"],
  "commands": "./commands/",
  "agents": "./agents/",
  "skills": "./skills/",
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json"
}

Publier sur le Marketplace

Qu'est-ce que le Marketplace

Le Marketplace est le centre de distribution des Plugins. Vous pouvez le considérer comme une "boutique de plugins" : les utilisateurs peuvent installer vos plugins publiés avec une simple commande.

Créer la configuration du Marketplace

Créez .claude-plugin/marketplace.json dans votre dépôt GitHub :

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "plugins": [
    {
      "name": "dev-toolkit",
      "source": "./plugins/dev-toolkit",
      "description": "开发者工具箱",
      "version": "1.0.0"
    },
    {
      "name": "doc-generator",
      "source": {
        "source": "github",
        "repo": "you/doc-generator-plugin"
      },
      "description": "文档生成工具"
    }
  ]
}

Types de sources de plugins

Le Marketplace prend en charge plusieurs types de sources :

Chemin relatif (plugins au sein du même dépôt) :

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Dépôt GitHub :

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

N'importe quel dépôt Git :

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Processus de publication

1. Créer un dépôt GitHub

2. Pousser votre code :

   git init
   git add .
   git commit -m "Initial release"
   git push origin main

3. Les utilisateurs ajoutent votre Marketplace :

   /plugin marketplace add your-username/your-repo

4. Les utilisateurs installent les plugins :

   /plugin install dev-toolkit@your-marketplace

Installer et gérer les Plugins

Via le menu interactif

/plugin

Cela ouvre une interface interactive dans laquelle vous pouvez parcourir, installer, activer et désactiver des plugins.

Via la ligne de commande

Ajouter un Marketplace :

/plugin marketplace add owner/repo           # GitHub
/plugin marketplace add https://example.com/marketplace.json  # URL
/plugin marketplace add ./local-marketplace  # 本地

Installer des plugins :

# 安装到用户范围（默认）
/plugin install formatter@my-marketplace

# 安装到项目范围（团队共享）
/plugin install formatter@my-marketplace --scope project

# 安装到本地范围（gitignored）
/plugin install formatter@my-marketplace --scope local

Autres commandes de gestion :

/plugin enable <plugin>      # 启用插件
/plugin disable <plugin>     # 禁用插件
/plugin uninstall <plugin>   # 卸载插件
/plugin update <plugin>      # 更新插件

Valider les plugins

Vérifiez que la configuration de votre plugin est correcte avant de publier :

claude plugin validate .

Ou dans Claude Code :

/plugin validate .

Configuration pour la collaboration d'équipe

Partager la configuration des plugins dans un projet

Validez la configuration des plugins dans le contrôle de version pour que les membres de l'équipe l'obtiennent automatiquement :

.claude/settings.json :

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Après le clonage du projet par les membres de l'équipe, ces plugins seront automatiquement disponibles.

Restrictions Marketplace pour les entreprises

Pour les environnements d'entreprise nécessitant un contrôle strict, vous pouvez restreindre les Marketplaces autorisés dans les paramètres administrés :

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "company/approved-plugins"
    }
  ]
}

Le définir comme un tableau vide [] désactive entièrement les plugins externes.

Référence des commandes CLI

Bonnes pratiques

Bonnes pratiques de développement

1. Gardez les Skills ciblés : Chaque Skill doit exceller dans une seule tâche ; évitez les conceptions fourre-tout
2. Rédigez des descriptions claires : Aidez Claude à comprendre quand utiliser vos composants
3. Testez d'abord avec votre équipe : Validez en interne avant de distribuer à la communauté
4. Documentez les changements de version : Consignez les modifications de chaque version dans CHANGELOG.md

Bonnes pratiques de structure de répertoires

• Placez commands/, agents/, skills/ dans le répertoire racine du plugin
• Ne mettez que plugin.json dans le répertoire .claude-plugin/
• Utilisez ${CLAUDE_PLUGIN_ROOT} pour référencer les fichiers au sein du plugin
• N'utilisez jamais ../ pour accéder à des fichiers en dehors du plugin

Bonnes pratiques pour les Hooks

1. Les scripts doivent être exécutables : chmod +x script.sh
2. Utilisez un shebang pour déclarer l'interpréteur : #!/bin/bash
3. Utilisez la variable ${CLAUDE_PLUGIN_ROOT} pour garantir l'exactitude des chemins
4. Testez les scripts indépendamment avant de les intégrer aux Hooks

Bonnes pratiques de gestion des versions

Suivez le Semantic Versioning :

• MAJOR (1.0.0 → 2.0.0) : Changements incompatibles
• MINOR (1.0.0 → 1.1.0) : Nouvelles fonctionnalités (rétrocompatible)
• PATCH (1.0.0 → 1.0.1) : Corrections de bugs (rétrocompatible)

Résolution des problèmes courants

Migrer depuis une configuration existante

Si vous disposez déjà de configurations dans le répertoire .claude/, suivez ces étapes pour les migrer vers un Plugin :

1. Créer la structure du Plugin :

   mkdir my-plugin/.claude-plugin

2. Créer plugin.json :

   {
     "name": "my-plugin",
     "description": "从现有配置迁移的插件",
     "version": "1.0.0"
   }

3. Copier les fichiers existants :

   cp -r .claude/commands my-plugin/
   cp -r .claude/agents my-plugin/
   cp -r .claude/skills my-plugin/

4. Migrer les Hooks : Copiez la configuration hooks de .claude/settings.json vers hooks/hooks.json

5. Tester :

   claude --plugin-dir ./my-plugin

Ressources d'apprentissage

Documentation officielle

Dépôts officiels

Ressources communautaires

Lectures recommandées

Perspectives d'avenir

Le système de Plugins représente un bond qualitatif dans les capacités d'extension de Claude Code. Avec la croissance de la communauté, nous pouvons nous attendre à :

• Un écosystème de plugins plus riche : Couvrant un large éventail de scénarios de développement et de workflows
• Des fonctionnalités de niveau entreprise : Une gestion des permissions et des capacités d'audit plus complètes
• Une compatibilité multiplateforme : Le standard ouvert Skills a déjà été adopté par plusieurs fournisseurs

C'est le moment idéal pour vous lancer. Vous pouvez commencer par de simples commandes, ajouter progressivement des Skills et des Hooks, et finalement construire une solution complète de workflow.

Si vous souhaitez en savoir plus sur le composant Subagent que les Plugins peuvent inclure, consultez Qu'est-ce que les Claude Code Subagents.