Contribuire a un Plugin

Questa guida spiega come creare un nuovo plugin e aggiungerlo al marketplace f5-sales-demo.

Struttura del Plugin

Ogni plugin risiede nella propria directory sotto plugins/ e segue questa struttura:

• Directoryplugins/

  • Directoryexample-plugin/

    • Directory.claude-plugin/

      • plugin.json
    • Directoryskills/

      • Directoryexample-skill/

        • SKILL.md
        • Directoryreferences/

          • reference-data.md
    • Directorycommands/

      • example-command.md
    • Directoryagents/

      • example-agent.md
    • README.md

Creazione di un Plugin

1. Creare la directory del plugin

   mkdir -p plugins/example-plugin/.claude-plugin
   mkdir -p plugins/example-plugin/skills
   mkdir -p plugins/example-plugin/commands

2. Scrivere plugin.json

   Creare plugins/example-plugin/.claude-plugin/plugin.json:

   {
     "name": "example-plugin",
     "description": "What this plugin does",
     "version": "1.0.0",
     "author": {
       "name": "f5-sales-demo"
     },
     "homepage": "https://github.com/f5-sales-demo/marketplace/tree/main/plugins/example-plugin",
     "keywords": ["relevant", "keywords"],
     "license": "Apache-2.0",
     "repository": "https://github.com/f5-sales-demo/marketplace"
   }

3. Aggiungere le skill

   Creare plugins/example-plugin/skills/example-skill/SKILL.md con il frontmatter:

   ---
   name: example-skill
   description: One-line description of what this skill does
   ---
   
   Detailed instructions for Claude when this skill activates.

   Inserire eventuali dati di riferimento in una sottodirectory references/ accanto a SKILL.md.

4. Aggiungere i comandi

   Creare plugins/example-plugin/commands/example-command.md:

   ---
   description: What this command does
   argument_hint: "[optional-args]"
   allowed_tools:
     - Read
     - Glob
     - Grep
   ---
   
   Instructions for Claude when the user invokes this command.

5. Aggiungere il plugin a marketplace.json

   Aggiungere una voce all’array plugins in .claude-plugin/marketplace.json:

   {
     "name": "example-plugin",
     "description": "What this plugin does",
     "version": "1.0.0",
     "author": { "name": "f5-sales-demo" },
     "source": "./plugins/example-plugin",
     "category": "productivity",
     "homepage": "https://github.com/f5-sales-demo/marketplace/tree/main/plugins/example-plugin",
     "license": "Apache-2.0",
     "keywords": ["relevant", "keywords"],
     "tags": ["searchable", "tags"],
     "repository": "https://github.com/f5-sales-demo/marketplace"
   }

6. Testare localmente

   Testare il plugin senza pubblicarlo puntando Claude Code alla directory locale:

   claude --plugin-dir ./plugins/example-plugin

   Verificare che le skill si attivino nel contesto corretto e che i comandi producano l’output atteso.

Invio del Plugin

Flusso di lavoro del repository

Questo repository applica un flusso di lavoro di governance rigoroso. Consultare CONTRIBUTING.md per il processo completo.

1. Creare una issue su GitHub che descriva il nuovo plugin
2. Creare un branch di funzionalità a partire da main
3. Aggiungere la directory del plugin e aggiornare marketplace.json
4. Aggiungere una pagina di documentazione in docs/plugins/example-plugin.mdx
5. Aprire una PR collegata alla issue con Closes #N
6. Correggere eventuali errori CI e fare il merge dopo il superamento dei controlli

Buone Pratiche

• Mantenere le skill mirate — ogni skill dovrebbe svolgere bene una sola funzione
• Usare i file di riferimento — inserire dataset di grandi dimensioni, schemi e tabelle di ricerca in references/ anziché inline in SKILL.md
• Definire lo scope in modo intelligente — verificare la presenza di modifiche non committate per restringere il working set quando possibile
• Raggruppare l’output per gravità — utilizzare i livelli ERROR, WARNING e INFO in modo che gli utenti possano dare priorità alle correzioni
• Scrivere un README — includere esempi d’uso e una descrizione di cosa fa ogni skill e comando