commit ac37c32142000643bd3799b5b811dc74fc8ece12 Author: Zhongwei Li Date: Sun Nov 30 08:27:01 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9bb564c --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "leapmultix-skill-creating-plugins", + "description": "Skill creating-plugins from LeapMultix", + "version": "1.0.0", + "author": { + "name": "Julien LE SAUX", + "email": "contact@jls42.org" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..f86635d --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# leapmultix-skill-creating-plugins + +Skill creating-plugins from LeapMultix diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..dd16900 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,53 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jls42/leapmultix:leapmultix-marketplace/skills/creating-plugins", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "5416a1bbc6ae52fdd3ef6c281a78bac9f48dd24f", + "treeHash": "b36fa7d16533db124312a8688a9e470c04d0701c9503d26b09e40aee2a865d32", + "generatedAt": "2025-11-28T10:19:12.106292Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "leapmultix-skill-creating-plugins", + "description": "Skill creating-plugins from LeapMultix", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "42060f97c3b724419ab9fc24dd02005f5aec6bf2b769d02fa454ef0e73fff477" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "1d6071784d9ac390b73a73a973c5d52151df78de6d7b608b72cd84e1fbfaff19" + }, + { + "path": "skills/creating-plugins/SKILL.md", + "sha256": "67ef7d8ba50a586de9d1bc24072357b5cb98da90035198c37ccfc14a98a7fec2" + }, + { + "path": "skills/creating-plugins/templates/plugin.json.template", + "sha256": "d0c8738c329f09b6960330d3394d3bde989465585200aef430a43de13a46621d" + }, + { + "path": "skills/creating-plugins/templates/marketplace.json.template", + "sha256": "6720d62fe85bca77b583c9e71eddf3d453f4aaba14e72b1848311b7135342d8e" + } + ], + "dirSha256": "b36fa7d16533db124312a8688a9e470c04d0701c9503d26b09e40aee2a865d32" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/creating-plugins/SKILL.md b/skills/creating-plugins/SKILL.md new file mode 100644 index 0000000..1d2811a --- /dev/null +++ b/skills/creating-plugins/SKILL.md @@ -0,0 +1,713 @@ +--- +name: creating-plugins +description: Guides creation of Claude Code plugins with marketplace manifests for packaging and distributing commands, agents, skills and hooks. Use when user wants to create, package or share plugins +allowed-tools: Read, Write, Grep, Glob, Bash +--- + +# 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](#quand-utiliser-ce-skill) +- [Prérequis](#prérequis) +- [Structure d'un plugin](#structure-dun-plugin) +- [Workflow de création](#workflow-de-création) +- [Fichiers requis](#fichiers-requis) +- [Commandes de gestion](#commandes-de-gestion) +- [Test local et validation](#test-local-et-validation) +- [Distribution en équipe](#distribution-en-équipe) +- [Exemples concrets](#exemples-concrets) +- [Gestion erreurs](#gestion-erreurs) +- [Checklist avant publication](#checklist-avant-publication) +- [En cas de doute](#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 + +```bash +# 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 :** + +```bash +cp .claude/commands/*.md plugin-name/commands/ +``` + +**Agents :** + +```bash +cp .claude/agents/*.md plugin-name/agents/ +``` + +**Skills :** + +```bash +cp -r .claude/skills/* plugin-name/skills/ +``` + +**Hooks :** + +```bash +cp .claude/hooks/hooks.json plugin-name/hooks/ +``` + +### 4. Créer plugin.json + +Utilise le template `templates/plugin.json.template` : + +```json +{ + "name": "nom-du-plugin", + "description": "Description claire et concise du plugin", + "version": "1.0.0", + "author": "Julien LE SAUX " +} +``` + +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 officiel du projet) + +### 5. Créer README.md + +Structure recommandée : + +```markdown +# 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 : + +```bash +# 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` : + +```json +{ + "name": "mon-marketplace", + "owner": "organisation-ou-username", + "plugins": [ + { + "name": "plugin-name", + "source": "./plugin-name", + "description": "Description du plugin" + } + ] +} +``` + +### 7. Tester localement + +```bash +# 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** : + ```bash + 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 ` + +Champs optionnels : + +- `homepage` (string) : URL du projet +- `repository` (string) : URL du repository git +- `license` (string) : Type de licence (MIT, Apache, etc.) + +Exemple complet : + +```json +{ + "name": "mon-plugin-awesome", + "description": "Plugin pour automatiser les workflows de développement avec Claude Code", + "version": "1.2.3", + "author": "Julien LE SAUX ", + "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 : + +```json +{ + "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 + +```bash +# Ajouter un marketplace +/plugin marketplace add +# 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 @ +# Exemple : /plugin install mon-plugin@mon-marketplace + +# Activer un plugin désactivé (sans réinstaller) +/plugin enable @ + +# Désactiver temporairement (sans supprimer) +/plugin disable @ + +# Désinstaller complètement +/plugin uninstall @ +``` + +### Gestion et debug + +```bash +# 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** + + ```bash + /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 : + +```json +{ + "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` : + +```json +{ + "name": "code-review", + "description": "Command pour reviews de code automatisées", + "version": "1.0.0", + "author": "Julien LE SAUX " +} +``` + +### 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` : + +```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 :** + +```bash +/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 :** + +```bash +/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 :** + +```bash +# 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 diff --git a/skills/creating-plugins/templates/marketplace.json.template b/skills/creating-plugins/templates/marketplace.json.template new file mode 100644 index 0000000..397ca4a --- /dev/null +++ b/skills/creating-plugins/templates/marketplace.json.template @@ -0,0 +1,11 @@ +{ + "name": "{{MARKETPLACE_NAME}}", + "owner": "{{OWNER}}", + "plugins": [ + { + "name": "{{PLUGIN_NAME}}", + "source": "./{{PLUGIN_NAME}}", + "description": "{{PLUGIN_DESCRIPTION}}" + } + ] +} diff --git a/skills/creating-plugins/templates/plugin.json.template b/skills/creating-plugins/templates/plugin.json.template new file mode 100644 index 0000000..53a34f4 --- /dev/null +++ b/skills/creating-plugins/templates/plugin.json.template @@ -0,0 +1,9 @@ +{ + "name": "{{PLUGIN_NAME}}", + "description": "{{PLUGIN_DESCRIPTION}}", + "version": "{{VERSION}}", + "author": "{{AUTHOR}}", + "homepage": "{{HOMEPAGE_URL}}", + "repository": "{{REPOSITORY_URL}}", + "license": "{{LICENSE}}" +}