Plugin Claude Code: Skills e MCP condivisi in tutto il team

Le Skills di Claude sono la cosa più facile del mondo da scrivere. Un file di testo, quattro righe di istruzioni, e Claude sa fare una cosa che prima non sapeva fare.

E la parte bella qual è? Che manco la scrivi tu! C'è una Skill che serve a scrivere le Skills: le dici cosa ti serve, quella ti fa due domande ed è già pronta da usare, stupendo vero? Claude che si scrive le istruzioni da solo.

Ne trovi a migliaia da scaricare. Curate, gratuite, pronte.

Poi ne scrivi una tu. Una che funziona davvero, sul tuo lavoro, sui tuoi clienti. E ti viene la voglia più naturale del mondo: condividerla con il tuo team.

Lì cominciano i guai.

Cosa ti serve per iniziare

Prima di dirti come si fa, rispondiamo alla domanda che blocca tutto il resto: quanto costa mettersi in condizione di farlo.

• Un account Cloudflare. Gratuito. Ci gira il server e ci vivono le credenziali.
• Un account GitHub. Gratuito. È il canale di distribuzione — ed è anche il canale con cui fai login, quindi è quello che permette di identificare l'utente.
• Un abbonamento a Claude (o a un altro assistente di coding) per scrivere il codice del server. Quello dovresti già averlo, se sei arrivato a leggere fin qui.

Nessuna infrastruttura da comprare. Nessun piano enterprise da attivare. Nessun fornitore da chiamare.

Per un team di tre persone la fattura è zero euro al mese. Il costo vero è un pomeriggio di lavoro.

Come siamo finiti in questo casino

Ti racconto come è nata, così capirai subito il problema.

Apri la tua impresa. Sei carico come una mina. Lavori per un cliente, poi per un altro, poi passi due giorni a sistemare il sito web. I tuoi soci fanno più o meno lo stesso.

A fine giornata apri Kimai — il tool con cui attribuiamo le ore ai progetti — crei un timesheet e scrivi che hai passato due ore su Pinco e quattro su Pallino.

Lo fai una volta. Lo fai due… alla terza ti senti un troglodita.

Lavori con l'IA per ore tutti i giorni, e la sera fai data entry come nel 2010?

Inaccettabile!

Allora apri la doc delle API di Kimai e in mezz'ora ti fai il tuo tool: da qui in avanti le ore le detti all'agente e ci pensa lui ad inserirle.

Che soddisfazione.

Poi lo dai ai soci. E qui fai la prima cosa storta senza accorgertene: scrivi lo stesso identico codice tre volte, una per ciascuno, perché ogni copia deve avere dentro l'id utente giusto — altrimenti le ore di Otoni finiscono a nome mio.

Passa un mese. Aggiungi Matomo per guardare le visite al sito. Ti fai il tool per le statistiche, lo colleghi a Claude, funziona a meraviglia!

Poi provi a schedulare un task che te le manda ogni lunedì mattina.

E non funziona più.

Perché? Perché i task schedulati girano nella sandbox di Cowork. E la sandbox quel tool non lo vede. E, già che ci siamo, non lo vede nemmeno Claude Code. Stesso computer, stessa persona, tre scatole separate che non si parlano.

Nel frattempo il token di Matomo dov'è? In chiaro, in un file sul tuo portatile.

Allora che fai? Ti scrivi una Skill con il token dentro e la passi ai soci. Bello, ora tutti possono chiedere a Claude come vanno le visite al sito.

Peccato che quel token adesso sia in chiaro su tre computer diversi.

Cybersecurity: scansate proprio!

E la tua testa malata di developer intanto non si ferma. Il tool per il SEO. Quello che genera i PDF con il brand Arkad. Quello che scansiona i siti dei clienti. Uno dietro l'altro.

Dopo qualche settimana ti guardi indietro e trovi questo: un casino di Skills, con dentro token in chiaro, che funzionano in un ambiente e nell'altro no, in versioni diverse tra te e i tuoi soci.

Mi segui? Ecco, lì ho capito che era il momento di fermarsi e ragionare su una soluzione.

Sul tavolo abbiamo ora cinque ostacoli:

1. Distribuzione — come faccio arrivare le mie Skills ai soci.
2. Aggiornamento — come fanno a sapere se è l'ultima revisione.
3. Segreti — dove metto un token senza spargerlo in giro.
4. Portabilità — come lo faccio funzionare in tre ambienti che non si parlano.
5. Identità — come fa il server a sapere chi dei tre lo sta usando.

Affrontiamoli uno per uno.

Cosa sono le Claude Skills (e perché non sono un MCP)

Serve una distinzione. È quella che sblocca tutto il resto.

Una Skill è un file di testo con delle istruzioni. Dice a Claude come si fa una cosa: quale procedura seguire, in che ordine, con quali accortezze, cosa non fare mai. Non esegue niente. È sapere, non braccia.

Un connettore MCP (Model Context Protocol) è l'opposto. È un servizio che espone funzioni eseguibili. Non spiega niente: fa. Interroga un database, chiama un'API, scrive su un CRM.

Le Skills istruiscono. I connettori agiscono.

Sembra una sottigliezza da manuale. È invece la chiave di tutto: le due cose viaggiano insieme ma vanno tenute separate — e più avanti vedrai che è proprio da questa separazione che nasce il risparmio di contesto.

Sopra le due c'è il contenitore. Un plugin è un pacchetto che tiene insieme Skills e connettori in un'unica unità versionata: una persona la installa con un comando e la aggiorna con un altro.

Skills e connettori sono i pezzi. Il plugin è la scatola con cui li spedisci.

Lo stesso plugin su Claude Desktop, Claude Code e Cowork

Comincio dal problema più doloroso, la portabilità, perché la soluzione è quasi imbarazzante da quanto è semplice.

Un connettore MCP remoto non vive sul tuo computer. Vive su un server — nel nostro caso un Worker su Cloudflare, gratis fino a volumi che tre persone non raggiungono nemmeno per sbaglio.

E siccome vive su internet e non nella tua cartella utente, lo vedono tutti gli ambienti allo stesso modo.

Lo colleghi a Cowork e lo ritrovi identico in Claude Code. Lo apri sul desktop e c'è. Le attività pianificate lo trovano. E dato che il protocollo è aperto, quello stesso identico server lo può usare qualunque altro client che parli MCP, come ChatGPT ad esempio.

Il problema non l'ho risolto configurando meglio i tre ambienti. L'ho risolto spostando fuori da tutti e tre la cosa da configurare.

Primo ostacolo abbattuto. ✊

Segreti e OAuth: dove finiscono davvero i token

Il secondo cade quasi per conseguenza. Ma vale la pena guardarlo da vicino, perché è quello che convince i clienti più prudenti.

Se il server sta su Cloudflare, il token di Matomo lo carichi una volta sola, come secret del Worker. Da quel momento vive lì: cifrato, fuori dai portatili, fuori dalle chat, fuori dalle mail. Nessuno dei miei soci lo ha mai visto. E non gli serve vederlo.

Quando lo ruoto, lo aggiorno in un punto. Non ci sono altri posti da cui toglierlo, perché non è mai stato altrove.

E i soci come entrano, se il token non ce l'hanno?

Con OAuth. Il server chiede a chi si collega di identificarsi e in cambio gli dà un accesso proprio, tracciabile, revocabile singolarmente. È lo stesso meccanismo con cui entri in un'app usando l'account Google.

La differenza la riassumerei così: il segreto non si conserva in tre copie, lo si scrive una volta per tutte sul server.

Secondo ostacolo abbattuto. Batti cinque 🖐️!

Ehi server, sono Fabrizio: il problema dell'identità

Adesso il pezzo che nessuno racconta, e che secondo me è il vero motivo per costruirsi un MCP proprio.

Oggi ogni fornitore ha il suo connettore. Google Drive ha il suo. Gmail ha il suo. Notion ha il suo. Ne esce uno nuovo ogni settimana. E allora perché scriverne uno?

Perché il connettore ufficiale risolve il caso facile: il suo servizio, il tuo account, uno alla volta. Fuori da lì restano scoperti tre casi, e sono quelli in cui mi sono imbattuto.

Il connettore non esiste. Il tuo tool interno, lo script che ti sei scritto sulle API di un gestionale, il database di casa: nessun fornitore scriverà mai il connettore per il tuo tool personale.

Ti servono due account dello stesso servizio. Oggi ogni connettore ne tiene uno solo: colleghi la tua Gmail e la casella contact@ dell'azienda resta fuori.

A monte c'è una chiave sola per tutti. L'accesso funziona benissimo, ma il sistema dall'altra parte vede un utente unico per tutta la squadra. L'accesso è risolto. Chi sei, no.

Prendi Kimai, il sistema con cui tracciamo le ore sui progetti dei clienti. Il server ha un token amministratore: uno solo, potentissimo, che può scrivere le ore di chiunque. Comodo per il server. Inutile per noi.

Perché se io registro tre ore su un progetto, quelle tre ore devono comparire a nome mio. Non a nome del socio che ha configurato il token per primo. Non a nome di un utente generico "Arkad".

Si chiama tracciabilità. Senza, il registro delle ore è carta straccia: non sai chi ha fatto cosa, non fatturi con precisione, non capisci dove sta finendo il tempo del team.

Come si risolve, di solito? Male. Tre chiavi API diverse, una per socio, ognuna da custodire, ognuna da ruotare, ognuna da riconfigurare in tre ambienti. Siamo tornati al punto di partenza, moltiplicato per tre.

La strada pulita che abbiamo scelto: ognuno si autentica con il proprio account GitHub, dentro un'organizzazione specifica di GitHub a cui solo noi soci abbiamo accesso.

Due cose ne derivano:

1. Il muro. Solo i membri dell'organizzazione possono usare il connettore. Chi non è dentro, non entra — e il giorno che qualcuno esce dal team, lo togli dall'organizzazione e ha perso l'accesso a tutto. Un gesto solo, non una caccia alle chiavi sparse.
2. Il nome. Il server sa chi sei a ogni chiamata. Quindi quando registro le ore non devo dirgli che sono Fabrizio: lo sa già, e mette il mio nome al posto giusto da solo.

Nessuno di noi tre ha una chiave API di Kimai. Non ci serve avercela. Ci autentichiamo una volta con GitHub e il resto lo fa il server, sapendo esattamente chi ha chiesto cosa.

E già che il server te lo scrivi tu, ti prendi un secondo vantaggio. Il connettore ufficiale di un fornitore ti porta in casa quaranta strumenti e permessi larghi: li carichi tutti, sempre, anche quando ne usi due. Il tuo ne espone sei, in sola lettura, con le regole scritte lato server. Meno contesto occupato — ci torno più avanti — e una superficie molto più piccola da difendere. Per un cliente prudente non è un dettaglio tecnico: è un argomento di vendita.

Terzo ostacolo abbattuto.

Ecco, più o meno, come si schematizza il nostro sistema di autenticazione MCP.

Come si installa il plugin da un marketplace GitHub

Restano distribuzione e aggiornamento, che poi sono lo stesso problema visto in due momenti diversi.

La risposta è un repository GitHub configurato come marketplace: un registro che elenca i plugin disponibili. Dentro ci sta tutto: il catalogo, un plugin per famiglia di strumenti, e — da quando abbiamo unito i due repository — anche il codice del Worker. Skill e strumento cambiano nello stesso commit.

arkad-marketplace/
├── .claude-plugin/
│   └── marketplace.json      # il catalogo: nome, owner, elenco dei plugin
├── plugins/
│   ├── arkad-documents/      # plugin di sole Skills: niente MCP, niente segreti
│   │   └── skills/arkad-documents/
│   │       ├── SKILL.md
│   │       └── assets/       # template e logo viaggiano dentro la Skill
│   └── arkad-tools/          # plugin con connettore: un MCP, dieci Skills
│       ├── .claude-plugin/
│       │   └── plugin.json   # nome e versione — la versione è l'interruttore di rilascio
│       ├── .mcp.json         # quattro righe: tipo http e URL. Nessun token.
│       └── skills/           # arkad-connect, arkad-seo, arkad-kimai…
├── arkad-tools.plugin        # lo zip del plugin: è così che lo installa Cowork
└── gateway/                  # il Worker Cloudflare, che sta nello stesso repo
    ├── src/index.js          # l'OAuth che avvolge l'handler MCP
    ├── src/github-auth.js    # login GitHub e allowlist dell'organizzazione
    ├── src/mcp.js            # JSON-RPC: initialize, tools/list, tools/call
    ├── src/tools/            # un file per famiglia: matomo, seo, kimai…
    └── wrangler.toml         # il binding KV e la lista dei segreti

Nota arkad-documents: nessun .mcp.json. Sono solo istruzioni e template, non tocca nessun sistema — e infatti non costa niente in contesto finché non lo invochi.

Un socio aggiunge il marketplace una volta e installa il plugin. Da quel momento il ciclo è questo: io modifico una Skill, correggo il codice e faccio push su GitHub. Lui lancia l'aggiornamento e ha l'ultima versione. Tutte le Skills, il connettore, tutto insieme. Senza che io gli mandi niente.

Il numero di versione non è un'etichetta decorativa: è ciò da cui Claude Code capisce che c'è qualcosa di nuovo da scaricare.

E siccome è tutto su Git, resta la storia delle modifiche. Si vede chi ha cambiato cosa.

Ultimi due ostacoli abbattuti insieme.

Dopo qualche mese di uso vero, l'effetto composto è questo: nessuno chiede più tu come l'hai configurato?. La domanda ha smesso di avere senso.

E ci siamo tolti anche l'altra abitudine: mandarci i file su WhatsApp, perché è lì che ci parliamo. Uno lo scaricava, l'altro no. Tre settimane dopo, quello che non l'aveva scaricato ti scriveva che il download era scaduto e gli serviva di nuovo — e intanto tu eri già alla versione sei.

Il plugin è uno, la versione è una, le credenziali sono di ciascuno, le Skills sono scritte una volta sola e l'agente sa usare i tool in modo corretto senza che nessuno gli spieghi nulla.

Gli MCP non sono morti: il costo di contesto reale

A questo punto arriva l'obiezione. E arriva sempre con una certa sicurezza: gli MCP sono morti, consumano contesto, ormai si usano le Skills.

C'è un fondo di vero. Un connettore carica le descrizioni dei suoi strumenti nella finestra di contesto all'avvio. Sempre, che tu li usi o no. Una Skill invece viene caricata solo quando serve. Su questo chi lo dice ha ragione.

Ma da lì a dire che sono morti, ce ne passa.

Il consumo del contesto è una conseguenza di come scrivi le descrizioni. E il trucco è tutto lì.

Tieni le descrizioni degli strumenti MCP al minimo indispensabile: cosa fa la funzione, quali parametri vuole, punto. Tutto il resto — quando conviene usarla, in che ordine, come si legge il risultato, quali errori sono normali — lo sposti in una Skill dello stesso plugin, che viene caricata solo nel momento in cui serve davvero.

Fatto così, sui miei plugin il peso in contesto sta intorno all'1%. Puoi misurartelo da solo con un banale /context in Claude Code.

L'1% per avere accesso diretto ai miei sistemi da qualunque ambiente non è un prezzo. È un arrotondamento.

Quello che vale per noi tre, e cosa cambierà

Un'ultima cosa, perché non voglio vendere questa architettura per più di quello che è.

GitHub non è la risposta. È la nostra risposta.

L'abbiamo scelto per un motivo banale: siamo tre e abbiamo tutti già un account GitHub ed un'organizzazione nostra in GitHub in cui mettiamo i nostri progetti, quindi non c'era niente da creare e niente da spiegare. Ma il server su Cloudflare lo si configura allo stesso identico modo con Google, o con qualunque altro fornitore di identità che l'azienda usi già.

Il pattern non è "usate GitHub". Il pattern è: appoggiatevi all'anagrafica che avete già, qualunque sia. Il giorno che entra in gioco una persona che non scrive codice, o che questa architettura la mettiamo in casa di un cliente non tecnico, GitHub è la scelta sbagliata e Google Workspace è quella giusta. Cambia il fornitore, non cambia il disegno.

E poi c'è un limite onesto da dichiarare.

Oggi abbiamo tutti permessi identici: chiunque di noi può usare qualunque strumento. Quindi il server deve sapere una cosa sola, chi sei, e la sa. Basta e avanza.

Il giorno che daremo accesso a un dipendente, non basterà più. Servirà definire dei ruoli sul server, associare ogni ruolo a un insieme di strumenti, e attribuire un ruolo a chi si connette in base alla sua posizione nell'organizzazione. Chi ha il ruolo giusto vede quello strumento, gli altri no.

Le cose si complicheranno. Non lo nascondo.

Ma è un problema che avremo quando lo avremo. Intanto questa soluzione ci ha cambiato la vita per davvero, e in questo campo tutto si muove così in fretta che l'unica promessa sensata è quella: quando servirà cambiare, cambieremo.

In breve

• Le Skills sono facili da scrivere e impossibili da tenere sincronizzate a mano in tre copie.
• Skills e connettori MCP non sono la stessa cosa: le prime istruiscono, i secondi agiscono. Tenerli separati è ciò che fa respirare il contesto.
• Un connettore remoto è visibile allo stesso modo da Claude Code, da Cowork e dalle attività pianificate, perché non vive su nessuno dei tre.
• I segreti stanno cifrati sul server, in un punto solo. Ciascuno si autentica per conto proprio.
• Con l'autenticazione via organizzazione GitHub ottieni due cose insieme: fuori chi non è del team, e il server che sa il nome di chi sta chiamando. Niente più chiavi API una per socio.
• Un marketplace GitHub porta ogni aggiornamento a tutto il team con un comando, e tiene la storia di chi ha cambiato cosa.
• Gli MCP non sono morti. In un plugin curato costano circa l'1% della finestra di contesto, e comprano l'unica cosa che le Skills da sole non danno: la capacità di agire.
• GitHub è la nostra istanza del pattern, non il pattern: al suo posto va bene Google o qualunque anagrafica aziendale già esistente. E finché i permessi sono identici per tutti basta l'identità; con un dipendente serviranno i ruoli.

Serve un pomeriggio. Servono due account gratuiti.

E poi non si torna più indietro.

Buon pomeriggio, allora. A presto 👋