Il marketplace di plugin: dalle esigenze alle skill condivise

Una skill non è un comando da terminale — non è git merge. È un comportamento atteso. La sua description dichiara quando va usata, e Claude la richiama da solo quando la situazione combacia. Non la invochi per nome: la descrivi bene e lei si attiva al momento giusto. L'interfaccia con l'utente è il linguaggio naturale, non un vocabolario di comandi da imparare.

---
name: commenti-codice
description: Come scrivere i commenti del codice in questo progetto.
             Usare QUANDO Claude sta per scrivere o modificare codice sorgente.   // <- il "quando" è la parte che conta
---
  ... corpo della skill: le istruzioni vere e proprie ...

Ogni skill è una cartella con un SKILL.md (l'entry point: trigger, invocabilità, istruzioni) più eventuali file di supporto: script deterministici, checklist, template. Regola d'oro: self-contained — tutto ciò che serve sta dentro la cartella, niente dipendenze implicite dall'esterno.

Una skill non nasce nel marketplace. Nasce da un'esigenza concreta mentre si lavora a un progetto: un compito ripetibile che richiede giudizio e che vorresti non dover rispiegare ogni volta. Il marketplace è l'ultimo passo, non il primo — e non è automatico.

1. Nasce da un'esigenza. Lavori alla commessa 141414 e ti accorgi di ripetere lo stesso ragionamento — «tradurre le stringhe HMI rispettando le chiavi del DB», «diagnosticare un device muto in rete». La skill nasce lì, in .claude/skills/ del progetto.
2. Si crea e si valida. Non a mano: con skill-creator (§4), che struttura lo SKILL.md, affina la description per lo scatenamento corretto, e la mette alla prova con degli eval.
3. Passa il filtro. Prima di proporla, la si mette contro le tre domande del marketplace (§3, §5): esiste già un tool deterministico? è comportamento nativo travestito? Claude farebbe peggio senza?
4. Si condivide via PR. Il marketplace espone solo main, protetto: niente commit diretti. La skill viene de-coupled dal workspace privato di chi l'ha scritta (path assoluti → relativi o $env:CLAUDE_PLUGIN_ROOT) e proposta con una pull request al maintainer.
5. Si installa ovunque. Approvata e mergiata, è disponibile a tutto il team con un install. Una sola versione canonica, sempre passata da revisione.

La domanda più importante viene prima di scrivere una riga: quel lavoro lo fa già qualcosa? Due controlli, in quest'ordine.

3.1 Esiste già un tool deterministico?

Git, un linter, un analyzer, docker compose, uno script PowerShell. Se per quel compito esiste già un tool deterministico che dà risposte certe, un'approssimazione LLM ha valore negativo: aggiunge non-determinismo, consuma contesto, e azzera il vantaggio di uno strumento che produce lo stesso risultato ogni volta.

3.2 Esiste già una skill?

Esistono skill universalmente note, riusabili, mantenute da altri. Prima di reinventarle, cercale — nel marketplace Sistec e in quelli pubblici:

• caveman — comunicazione ultra-compressa per risparmiare token (sito · github).
• openspec — pattern spec-first per documentare le decisioni prima del codice (sito · github).
• graphify — qualunque input → knowledge graph (sito · github).
• ponytail, e in generale il catalogo del marketplace interno.

Esempio di skill fatta bene da studiare: karpathy-guidelines.

Le skill si scrivono bene con una skill: skill-creator. Non è un template statico — è un assistente che crea una skill da zero, modifica e migliora quelle esistenti, e soprattutto ne misura le prestazioni.

4.1 Il punto critico — la description

Una skill perfetta nel corpo ma con una description vaga è inutile: non scatta mai, o scatta a sproposito. Il valore di skill-creator è proprio qui — trasformare la description da «cosa fa la skill» a «quando Claude deve usarla», e verificarlo con gli eval invece di indovinare.

Fin qui il marketplace è stato «il posto dove vivono le skill condivise». Concretamente è una cosa precisa: un catalogo — un repository git (o una directory) che contiene un file manifesto .claude-plugin/marketplace.json. Quel file elenca i plugin; ogni plugin impacchetta le skill (e altro). Claude Code non installa skill sciolte: installa plugin da un marketplace registrato.

5.1 Struttura del repository

Un plugin non impacchetta solo skill: può portare agent, hook, MCP server, output-style, tema. La skill è il componente più comune, ma il plugin è il contenitore.

// repo del marketplace
marketplace-sistec/
├── .claude-plugin/
│   └── marketplace.json          // IL CATALOGO: name, owner, plugins[]
└── plugins/
    └── hmi-developer/            // un plugin
        ├── .claude-plugin/
        │   └── plugin.json       // manifesto del plugin (solo name obbligatorio)
        ├── skills/
        │   ├── translate/
        │   │   └── SKILL.md       // una skill = una cartella con SKILL.md
        │   └── dpi-anchor-fix/
        │       ├── SKILL.md
        │       └── assets/probe.ps1   // engine deterministico bundlato
        ├── agents/               // subagent (opzionale)
        └── hooks/hooks.json       // hook (opzionale)

Il marketplace.json elenca i plugin e da dove prenderli — path relativo nello stesso repo, oppure un altro repo GitHub/git, un sottoalbero di monorepo, un pacchetto npm:

{
  "name": "marketplace-sistec",
  "owner": { "name": "Sistec", "email": "..." },
  "plugins": [
    { "name": "hmi-developer",   "source": "./plugins/hmi-developer" },
    { "name": "technical-writer","source": "./plugins/technical-writer" }
  ]
}

5.2 Registrare e installare

Due verbi distinti: si registra il marketplace una volta, poi si installa il plugin che serve. Le skill del plugin diventano subito disponibili — namespaciate col nome del plugin (/hmi-developer:translate), ma nell'uso normale scattano da sole via description.

# 1. registra il marketplace (una volta) — GitHub, git URL, path locale
/plugin marketplace add sistec/marketplace-sistec
/plugin marketplace add ./marketplace-sistec          # path locale

# 2. installa un plugin dal marketplace
/plugin install hmi-developer@marketplace-sistec

# gestione
/plugin marketplace list          # marketplace registrati
/plugin list --enabled            # plugin installati
/plugin uninstall hmi-developer@marketplace-sistec
/plugin                           # manager interattivo (Discover/Installed/Marketplaces/Errors)

Registrare e installare è meccanica (§5). La domanda vera è cosa merita di entrare nel catalogo. Il marketplace Sistec espone solo main protetto: si entra solo via pull request revisionata — una sola versione canonica, niente copie a mano che divergono.

6.1 Il filtro a tre domande

Una skill merita il marketplace solo se passa tutte e tre. Se anche una risposta è «no» o «forse», si scarta.

6.2 I due pattern che vincono

Il punto comune: l'LLM non sostituisce un tool — fa ciò che il tool non può fare.

6.3 Requisiti di forma

• Self-contained. Tutto nella cartella; gli engine deterministici (.ps1, .py) bundlati come assets/.
• De-coupled dal workspace. Niente path assoluti (C:\Users\Sistec 23\…): relativi o $env:CLAUDE_PLUGIN_ROOT.
• Direttive chiare. Le regole proprietarie riscritte in istruzioni esplicite, non appunti privati.
• Validata. Passata da eval e benchmark di skill-creator (§4).

L'analisi completa — 6 skill integrate, 14 scartate, con la motivazione di ciascuna — è nel documento audit e criteri di integrazione.

Una skill non serve solo a chi scrive codice. Il criterio è sempre lo stesso — giudizio semantico riusabile — ma il dominio cambia. Ecco esempi reali (e plausibili) su entrambi i fronti.

7.1 Sviluppo software

6.2 Non solo codice

• Adozione Claude & Claude Code in Sistec — il documento principale: ciclo agentico, contesto, prompt, skill, CLAUDE.md, condivisione (§9 è la panoramica di questo documento).
• Marketplace Sistec — audit e criteri di integrazione — le 6 skill integrate, le 14 scartate, il filtro a tre domande e i pattern ricorrenti.
• sistec-llm-wiki — l'altro canale di condivisione: la conoscenza.
• Documentazione ufficiale Claude Code — la directory .claude, skill e plugin.
• Plugin marketplaces · Plugins reference · Discover plugins — schema marketplace.json/plugin.json, comandi /plugin, sorgenti git.
• karpathy-guidelines — esempio di skill fatta bene.
• skill-creator — la skill per creare, modificare e validare skill (eval, benchmark, variance).
• caveman (sito) · openspec (sito) · graphify (sito) — skill note e riusabili.