Riferimento

Schema marketplace.json

Il manifesto del marketplace si trova in .claude-plugin/marketplace.json nella radice del repository.

Campi di primo livello

Campo	Obbligatorio	Descrizione
$schema	No	URL dello schema JSON per la validazione
name	Sì	Identificatore univoco del marketplace
version	No	Versione dello schema del marketplace (semver)
metadata.description	Sì	Descrizione leggibile del marketplace
owner.name	Sì	Organizzazione o utente proprietario del marketplace
owner.url	No	URL al profilo o al sito web del proprietario
owner.email	No	E-mail di contatto
plugins	Sì	Array delle voci dei plugin

Campi delle voci dei plugin

Campo	Obbligatorio	Descrizione
name	Sì	Identificatore del plugin (deve corrispondere a plugin.json)
description	Sì	Breve descrizione del plugin
version	Sì	Stringa della versione semantica
author.name	Sì	Autore del plugin
source	Sì	Percorso o URL del plugin (vedere Tipi di sorgente)
category	Sì	Categoria del plugin (ad es. productivity)
homepage	No	URL alla documentazione o alla homepage del plugin
license	No	Identificatore di licenza SPDX
keywords	No	Array di parole chiave per la ricerca
tags	No	Array di tag per il filtraggio
repository	No	URL del repository

Tipi di sorgente per i plugin

Il campo source in marketplace.json supporta più formati:

Tipo	Esempio	Descrizione
Percorso relativo	./plugins/example-plugin	Plugin nello stesso repository
Abbreviazione GitHub	owner/repo	Plugin nella radice del repository
GitHub con percorso	owner/repo/path/to/plugin	Plugin in una sottodirectory
URL Git	https://github.com/owner/repo.git	Repository Git
Pacchetto npm	npm:@scope/package	Pacchetto npm pubblicato

Schema plugin.json

Ogni plugin dispone di un manifesto in .claude-plugin/plugin.json all’interno della sua directory.

Campo	Obbligatorio	Descrizione
name	Sì	Identificatore del plugin
description	Sì	Funzione del plugin
version	Sì	Versione semantica
author.name	Sì	Autore del plugin
author.url	No	URL al profilo o al sito web dell’autore
homepage	No	URL della documentazione
keywords	No	Parole chiave per la ricerca
license	No	Identificatore di licenza SPDX
repository	No	URL del repository

Struttura della directory del plugin

plugins/example-plugin/
  .claude-plugin/
    plugin.json          # Manifesto del plugin (obbligatorio)
  skills/
    skill-name/
      SKILL.md           # Definizione della skill (obbligatoria per ogni skill)
      references/        # File di dati di riferimento (opzionale)
  commands/
    command-name.md      # Definizione del comando (uno per comando)
  agents/
    agent-name.md        # Definizione dell'agente (uno per agente)
  README.md              # Documentazione del plugin (consigliata)

Variabili d’ambiente

I plugin possono utilizzare queste variabili nei propri file di skill e comando:

Variabile	Descrizione
$\{CLAUDE_PLUGIN_ROOT\}	Percorso assoluto alla directory radice del plugin

Validazione

Validare i manifesti del marketplace e del plugin in locale:

claude plugin validate .

Questo verifica:

• Conformità allo schema di marketplace.json
• Esistenza di tutte le directory dei plugin referenziate
• Presenza di un plugin.json valido per ogni plugin
• Corretta formattazione del frontmatter di SKILL.md nelle skill
• Presenza dei campi obbligatori nel frontmatter dei comandi

Configurazione del team

Pre-configurazione dei marketplace

Aggiungere a .claude/settings.json in qualsiasi repository:

{
  "extraKnownMarketplaces": [
    "f5-sales-demo/marketplace"
  ]
}

Pre-abilitazione dei plugin

{
  "enabledPlugins": [
    "f5xc-docs-tools@f5-sales-demo-marketplace"
  ]
}

Consiglio

Il commit di queste impostazioni nel repository garantisce che ogni membro del team ottenga automaticamente la stessa configurazione di marketplace e plugin.

Risoluzione dei problemi

Marketplace non trovato

Verificare che il marketplace sia stato aggiunto:

/plugin marketplace list

Se mancante, aggiungerlo nuovamente:

/plugin marketplace add f5-sales-demo/marketplace

Plugin non attivo

• Confermare che il plugin sia installato: /plugin list
• Verificare che la versione di Claude Code supporti i plugin (v1.0.33+)
• Verificare che le condizioni di attivazione della skill corrispondano al contesto attuale

Skill che non si attivano automaticamente

Le skill si attivano in base al campo description nel frontmatter di SKILL.md. Se una skill non si attiva come previsto:

• Verificare che la descrizione descriva accuratamente il contesto di attivazione
• Utilizzare direttamente il comando (ad es. /f5xc-docs-tools:review-mdx) come soluzione alternativa

Errori di build dopo la revisione

Il plugin segnala i problemi ma non li corregge automaticamente. Applicare manualmente le correzioni suggerite, quindi eseguire nuovamente la revisione per confermarne la risoluzione.