Plugin Creator

Guide la création de plugins Claude Code pour empaqueter et distribuer commands, agents, skills et hooks.

Table des matières

• Quand utiliser ce Skill
• Prérequis
• Structure d'un plugin
• Workflow de création
• Fichiers requis
• Commandes de gestion
• Test local et validation
• Distribution en équipe
• Exemples concrets
• Gestion erreurs
• Checklist avant publication
• En cas de doute

Quand utiliser ce Skill

• Quand l'utilisateur demande de "créer un plugin", "create a plugin"
• Empaqueter fonctionnalités réutilisables entre projets
• Distribuer commands/agents/skills à une équipe
• Partager des outils avec la communauté
• Transformer un projet existant en plugin

Prérequis

Claude Code installé et configuré

Vérifie : /help fonctionne et affiche les commands disponibles

Projet avec composants à empaqueter

Au moins un de :

• .claude/commands/*.md - Slash commands
• .claude/agents/*.md - Subagents
• .claude/skills/*/SKILL.md - Skills
• .claude/hooks/hooks.json - Event hooks

Structure d'un plugin

plugin-name/
├── .claude-plugin/
│   ├── plugin.json          # Manifest du plugin (REQUIS)
│   └── marketplace.json     # Manifest marketplace (optionnel, pour distribution)
├── commands/                 # Slash commands (copier depuis .claude/commands/)
│   ├── command1.md
│   └── command2.md
├── agents/                   # Subagents (copier depuis .claude/agents/)
│   ├── agent1.md
│   └── agent2.md
├── skills/                   # Skills (copier depuis .claude/skills/)
│   ├── skill1/
│   │   ├── SKILL.md
│   │   └── templates/
│   └── skill2/
│       └── SKILL.md
├── hooks/                    # Event hooks (copier depuis .claude/hooks/)
│   └── hooks.json
└── README.md                 # Documentation (FORTEMENT RECOMMANDÉ)

IMPORTANT : Les composants sont à la racine du plugin, pas dans .claude-plugin/ !

Workflow de création

1. Analyser le projet source

Identifie tous les composants à inclure dans le plugin :

• Liste commands : Examine .claude/commands/
• Liste agents : Examine .claude/agents/
• Liste skills : Examine .claude/skills/
• Liste hooks : Examine .claude/hooks/hooks.json

Décide quels composants empaqueter (tous ou sous-ensemble).

2. Créer la structure du plugin

# Créer dossier racine du plugin
mkdir plugin-name

# Créer sous-dossier .claude-plugin
mkdir plugin-name/.claude-plugin

# Créer dossiers pour composants (selon besoin)
mkdir -p plugin-name/commands
mkdir -p plugin-name/agents
mkdir -p plugin-name/skills
mkdir -p plugin-name/hooks

3. Copier les composants

Commands :

cp .claude/commands/*.md plugin-name/commands/

Agents :

cp .claude/agents/*.md plugin-name/agents/

Skills :

cp -r .claude/skills/* plugin-name/skills/

Hooks :

cp .claude/hooks/hooks.json plugin-name/hooks/

4. Créer plugin.json

Utilise le template templates/plugin.json.template :

{
  "name": "nom-du-plugin",
  "description": "Description claire et concise du plugin",
  "version": "1.0.0",
  "author": "Julien LE SAUX <contact@jls42.org>"
}

Sauvegarde dans plugin-name/.claude-plugin/plugin.json

Règles de nommage :

• name : kebab-case, descriptif
• description : Max 1024 caractères, décrit QUOI et QUAND utiliser
• version : Semantic versioning (MAJOR.MINOR.PATCH)
• author : Toujours Julien LE SAUX <contact@jls42.org> (contact officiel du projet)

5. Créer README.md

Structure recommandée :

# Nom du Plugin

Description détaillée du plugin et de son utilité.

## Installation

\`\`\`bash
/plugin marketplace add ./path/to/marketplace
/plugin install plugin-name@marketplace-name
\`\`\`

## Composants inclus

### Commands

- `/command1` - Description
- `/command2` - Description

### Agents

- `agent1` - Description et quand l'utiliser
- `agent2` - Description et quand l'utiliser

### Skills

- `skill1` - Description
- `skill2` - Description

## Usage

[Exemples d'utilisation concrets]

## Prérequis

[Dépendances, tools nécessaires]

## Troubleshooting

[Solutions aux erreurs courantes]

6. (Optionnel) Créer marketplace de test

Pour tester et distribuer :

# Créer dossier marketplace parent
mkdir mon-marketplace

# Déplacer le plugin dedans
mv plugin-name mon-marketplace/

# Créer marketplace.json à la racine

Contenu de mon-marketplace/marketplace.json :

{
  "name": "mon-marketplace",
  "owner": "organisation-ou-username",
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugin-name",
      "description": "Description du plugin"
    }
  ]
}

7. Tester localement

# Ajouter le marketplace
/plugin marketplace add ./mon-marketplace

# Installer le plugin
/plugin install plugin-name@mon-marketplace

# Vérifier installation
/help

Vérifie que :

• Commands apparaissent dans /help
• Agents sont disponibles
• Skills sont détectés automatiquement
• Hooks s'exécutent correctement

Workflow automatisé LeapMultix (CRITIQUE)

Ce repository dispose d'un pipeline de packaging automatique. Ne pas copier les fichiers à la main, utilise le script suivant :

1. Définir les profils dans leapmultix-marketplace/plugin-profiles.json
   • target → dossier plugin (ex. leapmultix-marketplace/leapmultix-dev-core)
   • commands / agents / skills → listes (ou "*")
   • description, category → affichage marketplace
2. Exécuter la synchro :

   npm run plugin:sync -- --profile=all,core,audit
   # Bundle personnalisé
   npm run plugin:sync -- --target=leapmultix-marketplace/custom-bundle \
     --agents=code-reviewer --skills=checking-code-quality --commands=audit-config
   

3. Résultat automatique :
   • Copie des composants depuis .claude/
   • Regénération des plugin.json
   • Création des plugins unitaires (leapmultix-agent-*, leapmultix-skill-*, leapmultix-command-*)
   • Mise à jour des manifests marketplaces (.claude-plugin/marketplace.json + leapmultix-marketplace/.claude-plugin/marketplace.json)

✅ À faire systématiquement : après toute modification d'un command/agent/skill, relancer npm run plugin:sync puis réinstaller le plugin concerné dans Claude pour tester la nouvelle version.

Fichiers requis

plugin.json (REQUIS)

Localisation : .claude-plugin/plugin.json

Champs obligatoires :

• name (string) : Identifiant unique du plugin
• description (string) : Description claire
• version (string) : Version semantic (ex: "1.0.0")
• author (string) : Toujours Julien LE SAUX <contact@jls42.org>

Champs optionnels :

• homepage (string) : URL du projet
• repository (string) : URL du repository git
• license (string) : Type de licence (MIT, Apache, etc.)

Exemple complet :

{
  "name": "mon-plugin-awesome",
  "description": "Plugin pour automatiser les workflows de développement avec Claude Code",
  "version": "1.2.3",
  "author": "Julien LE SAUX <contact@jls42.org>",
  "homepage": "https://github.com/jls42/leapmultix",
  "repository": "https://github.com/jls42/leapmultix.git",
  "license": "AGPL-3.0-or-later"
}

marketplace.json (Optionnel, pour distribution)

Localisation : Racine du marketplace (niveau parent des plugins)

Structure :

{
  "name": "marketplace-name",
  "owner": "organisation",
  "plugins": [
    {
      "name": "plugin1",
      "source": "./plugin1",
      "description": "Description courte"
    },
    {
      "name": "plugin2",
      "source": "./plugin2",
      "description": "Description courte"
    }
  ]
}

Notes :

• Un marketplace peut contenir plusieurs plugins
• source : chemin relatif depuis marketplace.json
• name dans marketplace doit matcher name dans plugin.json

Commandes de gestion

Installation et activation

# Ajouter un marketplace
/plugin marketplace add <path>
# Exemple : /plugin marketplace add ./mon-marketplace
# Exemple : /plugin marketplace add https://github.com/user/marketplace

# Lister marketplaces enregistrés
/plugin marketplace list

# Installer un plugin
/plugin install <name>@<marketplace>
# Exemple : /plugin install mon-plugin@mon-marketplace

# Activer un plugin désactivé (sans réinstaller)
/plugin enable <name>@<marketplace>

# Désactiver temporairement (sans supprimer)
/plugin disable <name>@<marketplace>

# Désinstaller complètement
/plugin uninstall <name>@<marketplace>

Gestion et debug

# Menu interactif de gestion
/plugin

# Lister commands installées
/help

# Vérifier version d'un plugin
# (lire .claude-plugin/plugin.json du plugin installé)

Test local et validation

Workflow de test itératif

1. Modifier plugin

   • Éditer composants (commands, agents, skills)
   • Mettre à jour version dans plugin.json

2. Réinstaller

   /plugin uninstall plugin-name@marketplace-name
   /plugin install plugin-name@marketplace-name
   

3. Valider

   • Vérifier avec /help que les commands apparaissent
   • Tester chaque command individuellement
   • Tester agents sur tâches réelles
   • Vérifier skills sont découverts automatiquement
   • Tester hooks (si applicable)

4. Valider compliance

   Utilise le skill checking-config-compliance pour valider :

   • Frontmatter des agents corrects
   • Noms en kebab-case
   • Descriptions complètes
   • Structure des skills conforme

Checklist de test

• Plugin installe sans erreur
• Toutes les commands apparaissent dans /help
• Commands s'exécutent correctement avec arguments
• Agents sont invoqués automatiquement quand approprié
• Skills sont découverts par contexte
• Hooks s'exécutent aux bons moments
• Pas de conflits avec autres plugins
• Documentation README claire et complète

Distribution en équipe

Configuration automatique via .claude/settings.json

Pour déploiement automatique quand équipe trust le repository :

{
  "marketplaces": [
    {
      "path": "./marketplaces/team-plugins"
    }
  ],
  "plugins": [
    {
      "name": "team-workflow",
      "marketplace": "team-marketplace",
      "enabled": true
    },
    {
      "name": "project-helpers",
      "marketplace": "team-marketplace",
      "enabled": true
    }
  ]
}

Workflow équipe :

1. Créer marketplace dans repository (ex: ./marketplaces/team-plugins/)
2. Ajouter plugins au marketplace
3. Configurer .claude/settings.json dans repository
4. Commiter et pusher
5. Membres équipe : trust le repository
6. Claude Code installe automatiquement les plugins

Versioning et updates

Semantic Versioning :

• MAJOR (1.0.0 → 2.0.0) : Breaking changes
• MINOR (1.0.0 → 1.1.0) : Nouvelles fonctionnalités rétro-compatibles
• PATCH (1.0.0 → 1.0.1) : Bug fixes

Workflow de mise à jour :

1. Modifier plugin et incrémenter version dans plugin.json
2. Documenter changements dans README/CHANGELOG
3. Si breaking changes : documenter migration dans README
4. Tester complètement
5. Notifier équipe des updates
6. Équipe désinstalle/réinstalle pour obtenir nouvelle version

Exemples concrets

Exemple 1 : Plugin simple (1 command)

code-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── review.md
└── README.md

plugin.json :

{
  "name": "code-review",
  "description": "Command pour reviews de code automatisées",
  "version": "1.0.0",
  "author": "Julien LE SAUX <contact@jls42.org>"
}

Exemple 2 : Plugin complet (commands + agents + skills)

dev-workflow-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── test.md
│   ├── deploy.md
│   └── lint.md
├── agents/
│   ├── code-reviewer.md
│   └── test-writer.md
├── skills/
│   ├── checking-code-quality/
│   │   └── SKILL.md
│   └── creating-pull-requests/
│       └── SKILL.md
└── README.md

Exemple 3 : Marketplace avec multiple plugins

company-marketplace/
├── marketplace.json
├── security-tools/
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── commands/
│   └── README.md
├── testing-tools/
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── agents/
│   └── README.md
└── documentation-tools/
    ├── .claude-plugin/
    │   └── plugin.json
    ├── skills/
    └── README.md

marketplace.json :

{
  "name": "company-tools",
  "owner": "MyCompany",
  "plugins": [
    {
      "name": "security-tools",
      "source": "./security-tools",
      "description": "Outils de sécurité et audit"
    },
    {
      "name": "testing-tools",
      "source": "./testing-tools",
      "description": "Agents et commands pour TDD"
    },
    {
      "name": "documentation-tools",
      "source": "./documentation-tools",
      "description": "Génération automatique de docs"
    }
  ]
}

Gestion erreurs

Erreur : Plugin not found

Cause : Nom plugin ou marketplace incorrect

Solution :

/plugin marketplace list  # Vérifier nom marketplace
# Vérifier que name dans plugin.json match la commande install

Erreur : Invalid plugin.json

Cause : JSON malformé ou champs manquants

Solution :

• Valider JSON avec un linter
• Vérifier champs requis : name, description, version, author
• Vérifier format semantic versioning pour version

Erreur : Commands not appearing in /help

Causes possibles :

• Plugin désactivé
• Commands dans mauvais dossier (doivent être dans plugin-name/commands/ pas .claude-plugin/commands/)
• Conflits de noms avec autres plugins

Solution :

/plugin enable plugin-name@marketplace-name
# Vérifier structure : commands/ à la racine du plugin
# Renommer commands si conflit

Erreur : Marketplace not accessible

Cause : Path incorrect ou permissions

Solution :

• Vérifier path est correct (relatif ou absolu)
• Vérifier permissions de lecture sur dossier
• Pour URLs : vérifier connectivité réseau

Erreur : Plugin installation fails silently

Cause : Composants invalides (agents avec mauvais frontmatter, etc.)

Solution :

• Valider chaque composant individuellement avant packaging
• Utiliser skill checking-config-compliance
• Vérifier logs Claude Code pour détails

Checklist avant publication

Structure et fichiers

• .claude-plugin/plugin.json existe et est valide
• plugin.json contient : name, description, version, author
• Version suit semantic versioning
• README.md complet avec installation et usage
• Composants dans bons dossiers (racine, pas dans .claude-plugin/)
• Pas de fichiers sensibles (secrets, .env, credentials)

Validation composants

• Commands testés individuellement
• Agents avec frontmatter valide (name, description, tools)
• Skills avec SKILL.md et structure correcte
• Hooks testés (si applicable)
• Compliance validée avec skill checking-config-compliance

Documentation

• README explique clairement utilité du plugin
• Instructions d'installation claires
• Exemples d'utilisation fournis
• Prérequis documentés (dependencies, tools)
• Troubleshooting pour erreurs communes
• Breaking changes documentés (si updates)

Testing

• Testé cycle complet : uninstall → install → test
• Testé sur projet réel
• Testé par au moins une autre personne
• Pas de conflits avec plugins courants
• Performance acceptable (pas de ralentissement)

Distribution (si applicable)

• marketplace.json créé et valide
• Plugin référencé dans marketplace.json
• Marketplace accessible (local ou remote)
• .claude/settings.json configuré pour équipe
• Équipe notifiée de la disponibilité

En cas de doute

Source : .claude/BEST_PRACTICES_AGENTS_SKILLS.md section Plugins

Templates disponibles :

• templates/plugin.json.template - Structure plugin.json
• templates/marketplace.json.template - Structure marketplace.json

Règles absolues :

1. TOUJOURS créer plugin.json dans .claude-plugin/
2. TOUJOURS placer composants à la racine (commands/, agents/, skills/)
3. JAMAIS commiter secrets ou credentials
4. TOUJOURS versionner avec semantic versioning
5. TOUJOURS tester avant distribution équipe

Workflow minimal :

# 1. Créer structure
mkdir plugin-name/.claude-plugin
mkdir plugin-name/commands

# 2. Créer plugin.json
# (utiliser template)

# 3. Copier composants
cp .claude/commands/*.md plugin-name/commands/

# 4. Créer README.md

# 5. Tester localement
mkdir marketplace && mv plugin-name marketplace/
# Créer marketplace.json
/plugin marketplace add ./marketplace
/plugin install plugin-name@marketplace
/help  # Vérifier commands

# 6. Valider compliance
# (utiliser skill checking-config-compliance)

Ressources :

• Documentation officielle : https://code.claude.com/docs/en/plugins
• BEST_PRACTICES section Plugins
• Exemples dans ce SKILL.md