Creare e distribuire un marketplace di plugin

​

Panoramica

1. Creazione di plugin: crea uno o più plugin con comandi, agenti, hooks, MCP servers o LSP servers. Questa guida presuppone che tu abbia già plugin da distribuire; vedi Crea plugin per i dettagli su come crearli.
2. Creazione di un file marketplace: definisci un marketplace.json che elenca i tuoi plugin e dove trovarli (vedi Crea il file marketplace).
3. Ospita il marketplace: esegui il push su GitHub, GitLab o un altro host git (vedi Ospita e distribuisci marketplace).
4. Condividi con gli utenti: gli utenti aggiungono il tuo marketplace con /plugin marketplace add e installano singoli plugin (vedi Scopri e installa plugin).

​

Procedura dettagliata: creare un marketplace locale

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Rivedi il codice per bug, sicurezza e prestazioni
disable-model-invocation: true
---

Rivedi il codice che ho selezionato o i cambiamenti recenti per:
- Potenziali bug o casi limite
- Problemi di sicurezza
- Problemi di prestazioni
- Miglioramenti di leggibilità

Sii conciso e pratico.

{
  "name": "quality-review-plugin",
  "description": "Aggiunge una skill /quality-review per revisioni rapide del codice",
  "version": "1.0.0"
}

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Aggiunge una skill /quality-review per revisioni rapide del codice"
    }
  ]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review

​

Crea il file marketplace

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Formattazione automatica del codice al salvataggio",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Strumenti di automazione della distribuzione"
    }
  ]
}

​

Schema del marketplace

​

Campi obbligatori

​

Campi del proprietario

​

Metadati opzionali

​

Voci di plugin

​

Campi obbligatori

​

Campi di plugin opzionali

​

Plugin sources

​

Percorsi relativi

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

​

Repository GitHub

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

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

​

Repository Git

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

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

​

Sottodirectory Git

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

​

Pacchetti npm

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

​

Voci di plugin avanzate

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Strumenti di automazione del flusso di lavoro aziendale",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

• commands e agents: Puoi specificare più directory o singoli file. I percorsi sono relativi alla radice del plugin.
• ${CLAUDE_PLUGIN_ROOT}: Usa questa variabile nelle configurazioni degli hook e del server MCP per fare riferimento ai file all’interno della directory di installazione del plugin. Questo è necessario perché i plugin vengono copiati in una posizione cache quando installati. Per le dipendenze o lo stato che dovrebbe sopravvivere agli aggiornamenti dei plugin, usa ${CLAUDE_PLUGIN_DATA} invece.
• strict: false: Poiché è impostato su false, il plugin non ha bisogno del suo plugin.json. La voce del marketplace definisce tutto. Vedi Strict mode di seguito.

​

Strict mode

• strict: true: il plugin ha il suo plugin.json e gestisce i suoi componenti. La voce del marketplace può aggiungere comandi o hook extra in cima. Questo è il predefinito e funziona per la maggior parte dei plugin.
• strict: false: l’operatore del marketplace vuole il controllo completo. Il repository del plugin fornisce file grezzi e la voce del marketplace definisce quali di questi file sono esposti come comandi, agenti, hook, ecc. Utile quando il marketplace ristruttura o cura i componenti di un plugin diversamente da quanto previsto dall’autore del plugin.

​

Ospita e distribuisci marketplace

​

Ospita su GitHub (consigliato)

1. Crea un repository: Configura un nuovo repository per il tuo marketplace
2. Aggiungi il file marketplace: Crea .claude-plugin/marketplace.json con le tue definizioni di plugin
3. Condividi con i team: Gli utenti aggiungono il tuo marketplace con /plugin marketplace add owner/repo

​

Ospita su altri servizi git

/plugin marketplace add https://gitlab.com/company/plugins.git

​

Repository privati

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

​

Testa localmente prima della distribuzione

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

​

Richiedi marketplace per il tuo team

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

​

Pre-popola plugin per i container

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

• Sola lettura: la directory seed non viene mai scritta. Gli aggiornamenti automatici sono disabilitati per i marketplace seed poiché git pull fallirebbe su un filesystem di sola lettura.
• Le voci seed hanno precedenza: i marketplace dichiarati nel seed sovrascrivono qualsiasi voce corrispondente nella configurazione dell’utente ad ogni avvio. Per rinunciare a un plugin seed, usa /plugin disable piuttosto che rimuovere il marketplace.
• Risoluzione del percorso: Claude Code individua il contenuto del marketplace sondando $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ al runtime, non fidandosi dei percorsi archiviati all’interno del JSON del seed. Ciò significa che il seed funziona correttamente anche quando montato in un percorso diverso da dove è stato compilato.
• Compone con le impostazioni: se extraKnownMarketplaces o enabledPlugins dichiarano un marketplace che esiste già nel seed, Claude Code utilizza la copia del seed invece di clonare.

​

Restrizioni del marketplace gestito

​

Configurazioni comuni

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

​

Come funzionano le restrizioni

• Per le fonti GitHub: repo è obbligatorio e ref o path devono corrispondere anche se specificati nell’elenco di autorizzazione
• Per le fonti URL: l’URL completo deve corrispondere esattamente
• Per le fonti hostPattern: l’host del marketplace viene confrontato con il modello regex
• Per le fonti pathPattern: il percorso del filesystem del marketplace viene confrontato con il modello regex

​

Risoluzione della versione e canali di rilascio

​

Configura i canali di rilascio

Esempio

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Assegna i canali ai gruppi di utenti

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

​

Validazione e test

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Troubleshooting

​

Marketplace non carica

• Verifica che l’URL del marketplace sia accessibile
• Controlla che .claude-plugin/marketplace.json esista nel percorso specificato
• Assicurati che la sintassi JSON sia valida e che il frontmatter sia ben formato utilizzando claude plugin validate o /plugin validate
• Per i repository privati, conferma di avere i permessi di accesso

​

Errori di validazione del marketplace

• Marketplace has no plugins defined: aggiungi almeno un plugin all’array plugins
• No marketplace description provided: aggiungi metadata.description per aiutare gli utenti a comprendere il tuo marketplace
• Plugin name "x" is not kebab-case: il nome del plugin contiene lettere maiuscole, spazi o caratteri speciali. Rinomina in lettere minuscole, cifre e trattini solo (ad esempio, my-plugin). Claude Code accetta altre forme, ma la sincronizzazione del marketplace Claude.ai le rifiuta.

​

Errori di installazione del plugin

• Verifica che gli URL di fonte del plugin siano accessibili
• Controlla che le directory dei plugin contengano i file richiesti
• Per le fonti GitHub, assicurati che i repository siano pubblici o che tu abbia accesso
• Testa manualmente le fonti dei plugin clonando/scaricando

​

L’autenticazione del repository privato non riesce

• Verifica di essere autenticato con il tuo provider git (ad esempio, esegui gh auth status per GitHub)
• Controlla che il tuo helper di credenziali sia configurato correttamente: git config --global credential.helper
• Prova a clonare il repository manualmente per verificare che le tue credenziali funzionino

• Imposta il token appropriato nel tuo ambiente: echo $GITHUB_TOKEN
• Controlla che il token abbia i permessi richiesti (accesso in lettura al repository)
• Per GitHub, assicurati che il token abbia lo scope repo per i repository privati
• Per GitLab, assicurati che il token abbia almeno lo scope read_repository
• Verifica che il token non sia scaduto

​

Le operazioni Git scadono

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minuti

​

I plugin con percorsi relativi non riescono nei marketplace basati su URL

• Usa fonti esterne: Cambia le voci dei plugin per usare GitHub, npm o fonti URL git invece di percorsi relativi:
  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  
• Usa un marketplace basato su Git: Ospita il tuo marketplace in un repository Git e aggiungilo con l’URL git. I marketplace basati su Git clonano l’intero repository, rendendo i percorsi relativi funzionanti correttamente.

​

File non trovati dopo l’installazione

​

Vedi anche

• Scopri e installa plugin precostruiti - Installazione di plugin da marketplace esistenti
• Plugin - Creazione dei tuoi plugin
• Plugins reference - Specifiche tecniche complete e schemi
• Plugin settings - Opzioni di configurazione dei plugin
• strictKnownMarketplaces reference - Restrizioni del marketplace gestito