Creare e distribuire un marketplace di plugin

​

Panoramica

1. Creazione di plugin: crea uno o più plugin con skills, agenti, hooks, server MCP o server LSP. 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
---

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-plugin:quality-review

​

Crea il file marketplace

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

​

Schema del marketplace

​

Campi obbligatori

​

Campi del proprietario

​

Campi 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": "enterprise@example.com"
  },
  "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.
  • Vedi la tabella di sostituzione per quali campi di configurazione la sostituiscono per tipo di server
  • 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.

"skills": ["./skills/", "./extra-skills/"]

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

​

Strict mode

• strict: true: il plugin ha il suo plugin.json e gestisce i suoi componenti. La voce del marketplace può aggiungere skills o hooks 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 skills, agenti, hooks, 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

• Imposta CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 per mantenere il clone esistente quando il pull in background non riesce, invece di eliminare e ri-clonare. I tuoi plugin continuano a funzionare dallo stato sincronizzato più recente, e gli aggiornamenti manuali con /plugin marketplace update continuano a eseguire il pull con le tue credenziali.
• Configura un helper di credenziali git, ad esempio con gh auth setup-git per GitHub, in modo che il fallback di ri-clone possa autenticarsi senza richiedere.

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

​

Testa localmente prima della distribuzione

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

​

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>/...

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

• 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.
• La mutazione è bloccata: l’esecuzione di /plugin marketplace remove o /plugin marketplace update su un marketplace gestito da seed non riesce con una guida per chiedere al tuo amministratore di aggiornare l’immagine seed.
• 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

1. version nel plugin.json del plugin
2. version nella voce del marketplace del plugin
3. Lo SHA del commit git della fonte del plugin

​

Configura i canali di rilascio

{
  "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"
      }
    }
  ]
}

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

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

​

Fissa le versioni delle dipendenze

​

Rinomina o rimuovi un plugin

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• Se la voce punta a un nuovo nome, Claude Code carica il plugin con il suo nuovo nome e mostra un avviso di una riga come Renamed to "code-formatter" in the "acme-tools" marketplace. Quindi riscrive la vecchia chiave alla nuova chiave negli ambiti di impostazioni utente, progetto e locale sia per enabledPlugins che per pluginConfigs, in modo che l’avviso appaia una volta.
• Per una voce null, Claude Code elimina la vecchia chiave e l’avviso segnala che il plugin è stato rimosso dal marketplace.
• Se il plugin rinominato utilizza una fonte remota come github o npm, Claude Code segnala plugin-cache-miss dopo il rinomina e l’utente deve eseguire /plugin install una volta per recuperarlo con il nuovo nome.

​

Validazione e test

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Gestisci marketplace dalla CLI

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

• <source>: Scorciatoia GitHub owner/repo, URL git, URL remoto a un file marketplace.json o percorso di directory locale. Per fissare a un branch o tag, aggiungi @ref alla scorciatoia GitHub o #ref a un URL git

claude plugin marketplace add acme-corp/claude-plugins

claude plugin marketplace add acme-corp/claude-plugins@v2.0

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

claude plugin marketplace add https://example.com/marketplace.json

claude plugin marketplace add ./my-marketplace

claude plugin marketplace add acme-corp/claude-plugins --scope project

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

• <name>: nome del marketplace da rimuovere, come mostrato da claude plugin marketplace list. Questo è il name da marketplace.json, non la fonte che hai passato a add

​

Plugin marketplace update

claude plugin marketplace update [name]

• [name]: nome del marketplace da aggiornare, come mostrato da claude plugin marketplace list. Aggiorna tutti i marketplace se omesso

​

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 utilizzando claude plugin validate o /plugin validate. Per verificare il frontmatter di skill, agente e comando, esegui il comando su ogni directory di plugin
• Per i repository privati, conferma di avere i permessi di accesso

​

Errori di validazione del marketplace

• plugin il cui source è .
• esecuzione quando marketplace.json è al di fuori di una directory .claude-plugin, risolvendo le origini rispetto alla directory del file stesso
• segnalazione dei problemi di ogni voce anche quando un’altra parte del file ha errori di schema

• Marketplace has no plugins defined: aggiungi almeno un plugin all’array plugins
• No marketplace description provided: aggiungi una description di livello superiore 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 origine del plugin siano accessibili
• Controlla che le directory dei plugin contengano i file richiesti
• Per le origini GitHub, assicurati che i repository siano pubblici o che tu abbia accesso
• Testa manualmente le origini dei plugin clonando/scaricando
• Se l’origine fissa sia ref che sha, un ramo o un tag upstream eliminato non blocca l’installazione sulla maggior parte degli host git, inclusi GitHub, GitLab e Bitbucket. Su server che non supportano il recupero dei commit per SHA, come AWS CodeCommit, il ref deve ancora esistere e il commit fissato deve essere raggiungibile da esso. Se l’installazione continua a non riuscire, conferma che il commit fissato esiste ancora nel repository

​

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

• Per impostazione predefinita, gli aggiornamenti in background disabilitano gli helper di credenziali git per il pull, quindi il pull non può autenticarsi su HTTPS. I remote SSH con una chiave caricata in ssh-agent si autenticano ancora. Un pull non riuscito attiva una ri-clonazione da zero, che utilizza le tue credenziali archiviate ma potrebbe scadere su repository di grandi dimensioni
• Imposta CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 per mantenere il clone esistente quando il pull in background non riesce
• Configura un helper di credenziali git, ad esempio gh auth setup-git, in modo che il fallback di ri-clonazione possa autenticarsi
• Se la ri-clonazione scade su un repository di grandi dimensioni, aumenta il limite con CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Configura una riscrittura dell’URL git limitata al repository del marketplace in modo che il pull in background si autentichi direttamente
• Oppure aggiorna i marketplace privati manualmente con /plugin marketplace update <name>, che utilizza le tue credenziali

​

Gli aggiornamenti del marketplace non riescono in ambienti offline

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

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 origini esterne: Cambia le voci dei plugin per usare GitHub, npm o origini 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
• Plugins - Creazione dei tuoi plugin
• Plugins reference - Specifiche tecniche complete e schemi
• Plugin settings - Opzioni di configurazione dei plugin
• strictKnownMarketplaces reference - Restrizioni del marketplace gestito