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 sito web del proprietario
owner.email	No	Email di contatto
plugins	Sì	Array di voci di plugin

Campi delle voci di 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 (es. productivity)
homepage	No	URL alla documentazione o 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 del 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 ha un manifesto in .claude-plugin/plugin.json all’interno della propria 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 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          # Plugin manifest (required)
  skills/
    skill-name/
      SKILL.md           # Skill definition (required per skill)
      references/        # Reference data files (optional)
  commands/
    command-name.md      # Command definition (one per command)
  agents/
    agent-name.md        # Agent definition (one per agent)
  README.md              # Plugin documentation (recommended)

Variabili d’ambiente

I plugin possono utilizzare queste variabili nei propri file di competenze e comandi:

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

Validazione

Convalidare 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 di plugin referenziate
• Presenza di un plugin.json valido per ogni plugin
• Frontmatter correttamente formattato in SKILL.md per le competenze
• Presenza dei campi frontmatter obbligatori per i 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 riceva 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 in uso supporti i plugin (v1.0.33+)
• Verificare che le condizioni di attivazione della competenza corrispondano al contesto corrente

Competenze non attivate automaticamente

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

• Verificare che la descrizione descriva accuratamente il contesto di attivazione
• Utilizzare il comando direttamente (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 le correzioni suggerite manualmente, quindi eseguire nuovamente la revisione per confermare la risoluzione.