Crea il tuo marketplace di plugin per Claude Code su GitHub

🧩 Marketplace, plugin, comandi: i tre pezzi

Tre concetti, dal contenitore al contenuto. Il marketplace è il catalogo: un repo con .claude-plugin/marketplace.json che elenca cosa offri. Il plugin è il pacchetto vero e proprio: comandi, hook, skill, agent. Il comando è ciò che digiti, tipo /salva-session. Un marketplace può contenere più plugin, un plugin più comandi.

Perché un repo GitHub e non una cartella locale? Perché da remoto installo la stessa versione su ogni macchina — la mia, quella di un collega, il portatile nuovo — con un solo comando, e aggiorno tutti allo stesso modo. La cartella locale resta comoda solo mentre sviluppo. Partiamo dal repo.

1️⃣ Il repo e il file marketplace.json

Creo un repository — lo chiamo claude-marketplace — e lo tengo privato. L'unico file obbligatorio è .claude-plugin/marketplace.json: dà un nome al catalogo, indica il proprietario ed elenca i plugin con il loro percorso dentro il repo.

Qui dichiaro un solo plugin, salva-session, che vive nella cartella ./plugins/salva-session. La description è quella che vedrò sfogliando il marketplace. Tutto qui: questo file è il marketplace.

{
  "name": "my-marketplace",
  "owner": { "name": "your-username" },
  "plugins": [
    {
      "name": "salva-session",
      "source": "./plugins/salva-session",
      "description": "Salva e compatta la sessione in Obsidian"
    }
  ]
}

2️⃣ La struttura del plugin

Dentro plugins/salva-session metto un altro .claude-plugin/plugin.json (nome, versione, descrizione, autore) e una cartella commands/ con un file Markdown per comando. La struttura completa è questa.

La cosa importante è il nome del plugin, salva-session: i comandi di un plugin vivono sempre sotto il suo namespace, nella forma /nome-plugin:comando. Per questo commands/compact.md si invoca come /salva-session:compact, e il comando principale di salvataggio lo richiamo come /salva-session. È il nome del plugin a evitare le collisioni tra plugin diversi.

3️⃣ I due comandi: /salva-session e /salva-session:compact

Un comando è un file Markdown: un piccolo frontmatter con la descrizione e, sotto, le istruzioni in linguaggio naturale che Claude eseguirà. /salva-session fa una cosa sola: riassume la conversazione e la salva come nota nel vault Obsidian, in sessions/AAAA-MM-GG.md.

/salva-session:compact fa un passo in più: prima lancia /compact per comprimere il contesto, poi salva. Lo uso quando la sessione è lunga e voglio chiudere in ordine senza trascinare token inutili. Due file, due comandi, zero codice da compilare.

// commands/salva-session.md   → /salva-session
---
description: Salva la sessione corrente in Obsidian
---
Riassumi la sessione e salvala come nota Markdown
nel vault, in sessions/AAAA-MM-GG.md.

// commands/compact.md          → /salva-session:compact
---
description: Compatta e poi salva la sessione
---
Esegui prima /compact per comprimere il contesto,
poi salva la sessione come sopra.

🚀 Cosa succede alla fine della sessione

Qui si chiude il cerchio con l'articolo sul settings.json. Posso lanciare /salva-session a mano, oppure lasciare che sia l'hook Stop a farlo in automatico a ogni fine turno, richiamando lo stesso script. Il risultato è identico: la sessione viene compattata e salvata senza che io ci pensi.

Nella pratica vedo proprio questo: la conversazione viene compattata (con tanto di token risparmiati), partono le skill di fine sessione e la nota atterra nel vault. È l'automazione che preferisco — invisibile finché funziona.

📄 Il risultato nel vault Obsidian

Il prodotto finale è una nota Markdown ordinata: cosa abbiamo fatto, le decisioni prese, cosa resta aperto per la prossima volta. Ritrovo lo storico delle sessioni come un diario di bordo del progetto, cercabile e collegabile.

Niente di sensibile in chiaro se imposti bene lo script: nomi di progetto, percorsi e segreti restano fuori o vengono ridotti all'essenziale. Qui sotto un esempio con contenuti generici.

🐙 Installare da remoto (non da locale)

Ecco il pezzo che conta, e che molti sbagliano facendo tutto in locale. Per usare il plugin su qualsiasi macchina, aggiungo il marketplace dal repo GitHub e poi installo il plugin dal marketplace. Due comandi.

In alternativa li registro in settings.json con extraKnownMarketplaces e enabledPlugins, così una macchina nuova è pronta solo sincronizzando la configurazione. La variante locale (/plugin marketplace add ./percorso) la tengo solo mentre sviluppo il plugin.

# 1) aggiungi il marketplace dal repo GitHub
/plugin marketplace add your-username/claude-marketplace

# 2) installa il plugin dal marketplace
/plugin install salva-session@my-marketplace

// in alternativa, dentro settings.json:
"extraKnownMarketplaces": { "my-marketplace": { "source": {
  "source": "github", "repo": "your-username/claude-marketplace" } } },
"enabledPlugins": { "salva-session@my-marketplace": true }

⚖️ Remoto o locale: quando usare cosa

Riassumo la scelta che faccio sempre. Da remoto quando il plugin è pronto e lo voglio ovunque, condiviso e aggiornabile con un comando. Da locale solo nel ciclo di sviluppo, quando modifico i file e voglio provarli senza fare push a ogni cambiamento.

Altri articoli del blog