Un agente di coding IA appena uscito dalla scatola è come un nuovo assunto brillante al primo mattino. Sa ragionare, scrivere codice ed eseguire comandi, ma non sa come lavora il tuo team e non ha le chiavi dei tuoi sistemi. Le skill degli agenti e i server MCP colmano esattamente queste due lacune. Una skill è un playbook scritto che l’agente prende dallo scaffale quando un compito lo richiede. Un server MCP è un mazzo di chiavi: un piccolo programma che permette all’agente di usare qualcosa che prima non riusciva a raggiungere, come le tue issue di GitHub, un browser vero o la documentazione aggiornata.
Questa guida spiega entrambi in parole semplici, poi ti mostra come installarli, aggiornarli, rimuoverli e risolvere i problemi in OpenCode, Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot e Hermes Agent. Gran parte funziona allo stesso modo ovunque, perché ormai entrambi sono standard aperti. Sul fronte delle skill, un piccolo strumento da riga di comando tiene tutto insieme, npx skills, e lo percorro comando per comando.
Non sono un developer di formazione. Gestisco una piccola azienda IT in Germania e costruisco software con agenti IA, quindi ho imparato quasi tutto questo nel modo in cui probabilmente lo farai tu: rompendo le cose. La Parte 6 nasce dalle mie sessioni da terminale su un Mac e un Raspberry Pi, inclusa quella volta in cui lo strumento mi ha detto che tutte le mie skill erano aggiornate quando non era riuscito a controllarne nemmeno una.
Tutto quello che segue è stato verificato con la documentazione ufficiale di ogni agente e, per la competenze CLI, con il codice sorgente pubblicato delle versioni da 1.5.18 a 1.8.1, il 15 novembre 2026. Questi strumenti cambiano ogni settimana: la CLI ha pubblicato due release solo questa settimana, e OpenCode ha raggiunto la 2.3.0 il 13 novembre. I numeri di versione e i comportamenti sono segnalati dove è probabile che cambino. Controllali prima di fidarti.
Informativa: Nessuna azienda citata in questo articolo lo ha sponsorizzato, revisionato o approvato, e non contiene link affiliati. I prodotti sono nominati solo nel testo; le immagini usano i miei loghi.
TL;DR — Agent Skills e server MCP in dieci punti
- Una skill è una cartella con un
SKILL.mdfile: un nome e una descrizione in cima, le istruzioni sotto, e script o file di riferimento opzionali. Gli agenti leggono solo la descrizione finché un compito non richiede la skill, quindi una skill inutilizzata costa circa 100 token dell’attenzione dell’agente. - Un server MCP dà all’agente nuovi strumenti, come GitHub, un browser o la documentazione in tempo reale. Le descrizioni degli strumenti possono viaggiare con ogni richiesta, quindi collega solo i server che usi. Claude Code ora li rimanda al momento del bisogno, e OpenCode li raggruppa per server.
- La regola pratica: le regole di casa per ogni compito vanno in
AGENTS.md; il know-how necessario per alcuni compiti diventa una skill; l’accesso live a un sistema richiede un server MCP; e se esiste già un buon strumento da riga di comando, una skill che insegna all’agente quello strumento spesso costa meno di un server. - Entrambi sono standard aperti sotto la Agentic AI Foundation della Linux Foundation: MCP da dicembre 2025, Agent Skills dal 22 ottobre 2026. Una skill scritta per un agente di solito funziona anche negli altri.
.agents/skillsè la cartella condivisa. Codex, OpenCode, Cursor, Gemini CLI e GitHub Copilot leggono tutti.agents/skillsin un progetto e~/.agents/skillsnella tua cartella home. Claude Code legge solo.claude/skills, e Hermes Agent legge~/.hermes/skillspiù le cartelle che aggiungi.npx skillsè l'npm per le skill. la CLI open source di Vercel (versione 1.8.1) installa le skill in 79 agenti:npx skills add owner/repo,-gper ogni progetto,-a opencode -a claude-codeper scegliere gli agenti,npx skills lsper elencare enpx skills removeper disinstallare.- Per vedere se le tue skill sono aggiornate, esegui
npx skills@latest check. Dalla versione 1.7.5 (2 novembre 2026) si limita a segnalare;npx skills updateinstalla. Nelle versioni precedenti,checkeseguiva l'aggiornamento in silenzio. - Non fidarti mai della spunta verde da sola. Quando il limite di 60 richieste anonime all'ora di GitHub bloccava ogni controllo sul mio Mac, la CLI stampava comunque “All global skills are up to date”. Esegui
gh auth loginoppure impostaGITHUB_TOKEN, e leggi le righe ✗. - Non usare mai
sudocon skill o agenti, e non eseguire la CLI dalla tua cartella home. Root ha una home separata, quindisudocrea un secondo archivio di skill invisibile; e da~la CLI scambia la tua cartella home per un progetto. - Tratta le skill e i server MCP come software che installi. Un audit del febbraio 2026 su 3.984 skill pubbliche ha trovato falle di sicurezza nel 36,82% dei casi e confermato payload malevoli in 76. Leggi prima di installare, preferisci le skill dei produttori stessi dello strumento, fissa le versioni e tieni gli strumenti rischiosi su “ask”.
I quattro blocchi fondamentali in sintesi
| Blocco | Che cos'è, in una riga | Immaginalo come | Quando l'agente lo legge | Quanto costa | Esempio |
|---|---|---|---|---|---|
| AGENTS.md (CLAUDE.md in Claude Code) | Un file Markdown con le regole di casa per un progetto | Il manuale del personale | All'inizio di ogni sessione, per intero | Tutta la sua lunghezza, in ogni richiesta | “Usa l'ortografia britannica. Esegui i test prima di dire che hai finito.” |
| Skill | Una cartella con un SKILL.md file di ricetta, più script e riferimenti opzionali |
Una scheda ricetta in un raccoglitore | Nome e descrizione all'inizio; la ricetta completa solo quando un compito la richiede | Circa 100 token per skill finché non la usi | “Come scriviamo le note di rilascio” |
| Server MCP | Un piccolo programma che dà all'agente nuovi strumenti | Un set di chiavi e adattatori | L'elenco degli strumenti all'inizio (a meno che il tuo agente non lo rimandi); i singoli strumenti quando vengono chiamati | Le descrizioni degli strumenti, spesso in ogni richiesta | Le issue di GitHub, un browser reale, la documentazione aggiornata delle librerie |
| Plugin o estensione | Un pacchetto di skill, server MCP e a volte hook | Un kit di benvenuto | Dipende da cosa c’è dentro | La somma delle sue parti | Superpowers, il kit iniziale dell’azienda fornitrice |

Indice
- Parte 1 — Agent Skills e server MCP in parole semplici
- Parte 2 — Skill, server MCP o AGENTS.md? Il test delle cinque domande
- Parte 3 — Dove ogni agente cerca le skill
- Parte 4 — La
competenzeCLI: npm per le Agent Skills, passo dopo passo - Parte 5 — “Il mio pacchetto di skill è stato aggiornato due giorni fa. Come faccio a sapere se ce l'ho?”
- Parte 6 — Cinque problemi reali dal mio Mac e dal Raspberry Pi, e come risolverli
- Parte 7 — I server MCP senza gergo
- Parte 8 — Aggiungere un server MCP in sei agenti: ricette da copiare e incollare
- Parte 9 — Plugin: skill e server MCP in un unico pacchetto
- Parte 10 — Scrivi la tua prima skill in dieci minuti
- Parte 11 — Restare al sicuro: le skill e i server sono software
- Parte 12 — Una routine settimanale di due minuti
- Parte 13 — Quale configurazione scegliere? Cinque scenari
- Domande frequenti
- In sintesi
Parte 1 — Agent Skills e server MCP in parole semplici
Il paragone del nuovo assunto
Immagina di assumere una persona brillante. Il primo giorno le daresti tre cose: un breve manuale con le regole che tutti seguono, un raccoglitore di ricette per i lavori che il tuo team svolge a modo suo, e un set di chiavi e badge per accedere ai sistemi di cui ha bisogno. Ad alcune persone daresti anche un kit di benvenuto che raggruppa alcune ricette e chiavi.
Gli agenti IA hanno bisogno esattamente delle stesse cose, e ogni pezzo ora ha un nome standard:
- Il manuale è
AGENTS.md(Claude Code chiama la sua versioneCLAUDE.md). - Le ricette sono le skill.
- Le chiavi sono i server MCP.
- I kit di benvenuto sono plugin, chiamati estensioni in alcuni agenti.
Il resto di questa guida riguarda le ricette e le chiavi, perché è lì che si concentra la maggior parte della confusione.
Che cos’è una skill
Una skill è una cartella. All’interno c’è un file obbligatorio, SKILL.md, e facoltativamente tutto il resto che serve al lavoro:
release-notes/
├── SKILL.md ← obbligatorio: nome, descrizione, istruzioni
├── references/ ← facoltativo: documenti più lunghi, da leggere solo quando servono
├── scripts/ ← facoltativo: codice che l’agente può eseguire
└── assets/ ← facoltativo: modelli, immagini, file di dati
L’ SKILL.md il file ha una breve intestazione tra due --- righe (quell’intestazione si chiama front matter), seguita da istruzioni semplici:
---
name: release-notes
description: Scrive le note "What's New" dell’App Store a partire dai commit recenti. Usala quando ti servono note di rilascio, un changelog o un testo "what's new".
---
# Note di rilascio
1. Leggi i commit dall’ultimo tag git.
2. Mantieni solo le modifiche che un utente noterebbe.
3. Scrivi da tre a cinque brevi punti in inglese semplice, per un totale inferiore a 400 caratteri.
Lo standard aperto richiede due campi. Il nome può usare solo lettere minuscole, numeri e trattini, può essere lungo al massimo 64 caratteri e deve corrispondere al nome della cartella. La descrizione può arrivare a 1.024 caratteri e dovrebbe dire cosa fa la skill e quando usarla, perché è dalla descrizione che l’agente decide se aprire la skill o meno.
Perché puoi installare decine di skill: il trucco dei tre livelli
Le skill si caricano a strati, che lo standard chiama progressive disclosure. Pensale come una libreria:
- Le quarte di copertina. Quando inizia una sessione, l’agente legge solo il nome e la descrizione di ogni skill. La specifica prevede circa 100 token per questo, per ogni skill. (Un token è più o meno una parola breve o una sua parte; è l’unità in cui i modelli misurano la loro memoria di lavoro.)
- Il capitolo. Quando un compito corrisponde a una descrizione, l’agente legge l’intero
SKILL.md. Lo standard raccomanda di tenerlo sotto i 5.000 token e le 500 righe. - L’appendice. I file di riferimento e gli script si caricano solo se le istruzioni li indicano.
Ecco perché cento skill inutilizzate costano molto meno di un unico lungo manuale di regole. Non è gratis, però: le descrizioni si sommano, e gli agenti le limitano. Codex limita la sua lista iniziale di skill al 2% della memoria di lavoro del modello (8.000 caratteri se non riesce a capirne la dimensione), e Claude Code taglia a 1.536 caratteri il testo di elenco di ogni skill. Installa quello che userai.
Che cos’è un server MCP
MCP, il Model Context Protocol, è uno standard aperto per collegare gli agenti IA a strumenti e dati. Anthropic l’ha introdotto nel novembre 2024 e l’ha ceduto alla nuova Agentic AI Foundation della Linux Foundation nel dicembre 2025, insieme ad AGENTS.md di OpenAI e a goose di Block.
Un Server MCP è un piccolo programma che dice al tuo agente: “questi sono gli strumenti che offro”. Un server GitHub potrebbe offrire create_issue e search_code; un server browser offre navigate e take_screenshot; un server di documentazione offre query_docs. Il tuo agente è il client MCP: mostra al modello l'elenco e, quando il modello vuole usare uno strumento, l'agente controlla i tuoi permessi, chiede al server di eseguirlo e gli restituisce il risultato.
I server sono di due tipi:
- Server locali girano sul tuo computer. L'agente li avvia con un comando come
npx @playwright/mcp@lateste comunica con loro tramite l'input e l'output del programma (il nome tecnico è stdio). - Server remoti girano sui computer del fornitore. Ti connetti con un indirizzo web, come
https://mcp.context7.com/mcpe di solito accedi tramite il browser o incolli una chiave API. Il nome tecnico della connessione è Streamable HTTP.
Ed ecco il problema. Ogni strumento arriva con un nome, una descrizione e un elenco di parametri, scritti perché il modello li legga. A meno che il tuo agente non li rimandi, quelle descrizioni viaggiano con ogni richiesta, e venti server con dieci strumenti ciascuno rendono ogni risposta più lenta, più costosa e meno mirata. La Parte 7 mostra cosa fa ogni agente al riguardo.
AGENTS.md e plugin, in breve
AGENTS.md è un semplice file Markdown nella cartella principale del tuo progetto che l'agente legge all'inizio di ogni sessione: lo scopo del progetto, i suoi comandi, le sue regole inderogabili. OpenCode, Codex, Cursor e GitHub Copilot lo leggono direttamente. Claude Code legge CLAUDE.md al suo posto, e la sua documentazione suggerisce un CLAUDE.md che importa semplicemente l'altro file con una riga tipo @AGENTS.md. Dato che viene caricato ogni volta, tienilo breve e sposta tutto ciò che riguarda un compito specifico nelle skill.
Plugin raggruppano gli altri pezzi. Un plugin di Claude Code può contenere skill, subagenti, hook (script che vengono eseguiti su eventi) e server MCP e LSP. Anche Codex, Cursor, GitHub Copilot CLI e Hermes Agent hanno i plugin, e Gemini CLI li chiama estensioni. La Parte 9 li tratta.
Un piccolo glossario
| Termine | Cosa significa qui |
|---|---|
| Agente (o harness) | Il programma con cui parli: OpenCode, Claude Code, Codex e così via. Esegue il modello, legge i file e chiama gli strumenti |
| Modello | L'IA che pensa, come GLM, Claude o GPT |
| Finestra di contesto | La memoria di lavoro del modello per una singola richiesta. Tutto ciò che carichi se la contende |
| Token | L'unità con cui i modelli contano il testo; più o meno una parola breve o una sua parte |
| Skill | Una cartella con un SKILL.md file che insegna all'agente un singolo compito |
| Front matter | L'intestazione in cima a SKILL.md, tra due --- righe |
| Server MCP | Un programma che offre strumenti all'agente tramite il Model Context Protocol |
| Strumento | Una singola azione offerta da un server MCP, come create_issue |
| stdio / Streamable HTTP | Come l'agente comunica con un server locale e con un server remoto |
| OAuth | Il flusso “Accedi con…” nel browser che dà all'agente un token senza che tu debba incollare una password |
| Ambito di progetto / ambito globale | Installato solo per un progetto o per ogni progetto sul tuo computer |
| File di lock | Una ricevuta che elenca cosa hai installato, da dove e un'impronta di ogni skill |
| Symlink | Una scorciatoia verso una cartella. La skills CLI tiene una sola copia reale e collega gli agenti a quella |
Parte 2 — Skill, server MCP o AGENTS.md? Il test delle cinque domande
Quando vuoi che un agente faccia qualcosa meglio, poni queste domande in ordine e fermati al primo “sì”. La domanda 4 è l'unica che ha un seguito:
- Deve valere per ogni singolo compito di questo progetto? Mettilo in
AGENTS.md. “Usa l'ortografia britannica” e “esegui i test prima di dire che hai finito” vanno qui. - Deve essere imposto, non solo suggerito? Usa una regola di permessi o un hook. Le skill e
AGENTS.mdsono istruzioni, e un modello può ignorare le istruzioni. “Mai fare push su main” richiede unadenyregola. - È un know-how che conta solo per alcuni compiti? Scrivi o installa una skill. Routine di rilascio, checklist di revisione, la voce del tuo brand e il tuo flusso di lavoro test-first sono tutte skill.
- L'agente ha bisogno di accesso in tempo reale a un sistema esterno ai suoi file? I tuoi report di crash dietro un login, un browser che possa guidare, un'app di project management. Se è così, fai la domanda 5 prima di prendere un server.
- Esiste già un buon strumento da riga di comando per quel sistema? Se sì, una skill che insegna all'agente quello strumento di solito batte un server: l'agente sa già eseguire comandi, una CLI non costa nulla finché non viene usata, e il suo output può essere filtrato prima di arrivare al modello. Se non c'è una buona CLI, se il tuo agente non può eseguire comandi o se il lavoro è interattivo (come guidare un browser), aggiungi un server MCP.
Ecco il test applicato a dieci desideri quotidiani:
| Vuoi che l'agente… | Utilizzo | Perché |
|---|---|---|
| Usa sempre l'ortografia britannica | AGENTS.md |
Vale per ogni compito |
| Mai fare push sul branch main | Una regola di permessi | Deve essere imposto, non suggerito |
| Scrivi le note di rilascio come piace a te | Una skill | Know-how, serve ogni tanto |
| Segui un rigoroso flusso di lavoro test-first | Una skill (Superpowers ne ha una) | Una procedura per alcuni compiti |
| Leggi e apri issue su GitHub | Una skill che insegna gh, o il server MCP di GitHub |
gh costa meno; il server va bene per agenti che non possono eseguire comandi |
| Cerca la documentazione aggiornata di una libreria | Un server MCP (Context7) o la sua CLI con una skill (ctx7) |
Dati live in entrambi i casi |
| Naviga la tua web app e scatta screenshot | Un server MCP (Playwright) | Serve un browser in esecuzione che l’agente possa pilotare |
| Controlla i crash dell’ultima notte | Un server MCP (Sentry) | Dati live dietro un login |
| Crea un report PDF dal tuo modello | Una skill con uno script e il modello dentro assets/ |
Una procedura più uno strumento allegato |
Tienile lontane dai tuoi .env file |
Una regola di permessi | Deve essere fatto rispettare |
Skill e server MCP non sono rivali. Alcune delle migliori configurazioni li affiancano: una skill spiega quando e come come usare gli strumenti di un server, e il lavoro lo fa il server. Codex permette persino a una skill di dichiarare da quali server MCP dipende, in un file opzionale agents/openai.yaml file.

Parte 3 — Dove ogni agente cerca le skill
Ogni agente cerca in due tipi di posizione. Cartelle di progetto stanno dentro il tuo repository, così le skill viaggiano con il codice e anche i tuoi colleghi le ottengono. Cartelle personali stanno nella tua cartella home e valgono per ogni progetto sul tuo computer. La maggior parte degli strumenti chiama le installazioni personali globali.
Nel 2026 gli agenti sono convergiti su un’unica posizione condivisa: .agents/skills in un progetto e ~/.agents/skills nella tua cartella home. Se ci metti una skill, la maggior parte degli agenti la trova senza alcun lavoro extra.
| Agente | Cartelle di progetto | Cartelle personali | Chiama una skill da solo | Da sapere |
|---|---|---|---|---|
| OpenCode | .opencode/skills, .agents/skills, .claude/skills |
~/.config/opencode/skills, ~/.agents/skills, ~/.claude/skills |
Menziona @skill-id nel tuo prompt |
L'ID è il nome della cartella. Limita le skill con l’opzione skill permission |
| Claude Code | .claude/skills |
~/.claude/skills |
/skill-name |
Non legge .agents/skills. Le skill dei plugin appaiono come /plugin-name:skill-name |
| Codex | .agents/skills, in ogni cartella dal punto in cui avvii fino alla radice del repository |
~/.agents/skills, più /etc/codex/skills per gli amministratori |
$skill-name, o /skills |
Viene fornito con un $skill-installer |
| Gemini CLI | .agents/skills, .gemini/skills |
~/.agents/skills, ~/.gemini/skills |
/skills list; il modello chiede il tuo permesso prima di attivarla |
.agents/skills vince quando due skill condividono lo stesso nome |
| Cursor | .agents/skills, .cursor/skills (e legge .claude/skills e .codex/skills) |
~/.agents/skills, ~/.cursor/skills |
/skill-name |
A paths il campo limita una skill ai file corrispondenti |
| GitHub Copilot | .github/skills, .agents/skills, .claude/skills |
~/.copilot/skills, ~/.agents/skills |
Carica le skill quando sono pertinenti | Funziona in Copilot CLI, nell'agente cloud e nella modalità agente di VS Code e JetBrains |
| Hermes Agent | .hermes/skills, .agents/skills, dopo che esegui hermes skills trust |
~/.hermes/skills, più eventuali cartelle elencate in skills.external_dirs |
/skill-name, e fino a cinque di fila |
Scansiona ogni installazione dall'hub alla ricerca di contenuti malevoli |
Percorsi tratti dalla documentazione di ciascun agente al 15 novembre 2026. Gli agenti aggiungono posizioni regolarmente; controlla la pagina delle skill del tuo agente se qualcosa non compare.
Tre dettagli che evitano confusione
- Claude Code è l'eccezione. Legge solo
.claude/skillse~/.claude/skills. La CLI skills lo gestisce per te creando un collegamento dalla cartella di Claude Code alla copia condivisa. Se copi le skill a mano, dovrai metterle (o un symlink) nella cartella di Claude Code da solo. - Hermes Agent mantiene una propria libreria. La sua cartella principale è
~/.hermes/skills. Per fargli leggere anche la cartella condivisa, aggiungila in~/.hermes/config.yaml:
yaml
skills:
external_dirs:
- ~/.agents/skills
Oppure installa con la CLI skills e includi -a hermes-agent. Scegli un solo approccio, non entrambi, altrimenti avrai ogni skill due volte.
– I nomi duplicati causano sorprese silenziose. Ogni agente ha la sua regola su quale copia vince. OpenCode registra le sue cartelle in un ordine fisso e vince l'ultima, con .opencode/skills quella del tuo progetto per ultima. Claude Code fa il contrario: una skill personale batte una skill di progetto con lo stesso nome. Gemini CLI preferisce il workspace all'utente e .agenti rispetto a .gemini, e Codex le mostra semplicemente entrambe. La soluzione è noiosa e affidabile: non tenere due skill con lo stesso nome.
OpenCode ha due extra che vale la pena conoscere. Un singolo file Markdown in cima a una cartella di skill (come skills/review.md) conta anch'esso come skill, e un competenze array in opencode.jsonc può aggiungere cartelle extra o persino un catalogo web di skill. La mia guida a OpenCode tratta più in dettaglio le sue autorizzazioni per le skill.

Parte 4 — La competenze CLI: npm per le Agent Skills, passo dopo passo
Puoi installare le skill copiando cartelle qua e là, e per una o due va bene. Oltre a questo ti serve un gestore di pacchetti: qualcosa che sappia dove guarda ogni agente, che tenga una copia invece di cinque, che ricordi da dove viene ogni skill e che ti dica quando c’è una versione più recente. È quello che competenze fa. È uno strumento da riga di comando open source (MIT) di Vercel Labs, lo esegui con npx skills, e il suo elenco di skill pubbliche si trova su skills.sh.
I fatti che contano al 15 novembre 2026:
- Versione 1.8.1, pubblicata l'11 novembre. Va veloce: da 1.7.5 a 1.8.1 sono serviti nove giorni.
- Richiede Node.js 22.20 o una versione successiva.
- Supporta 79 agenti, tra cui OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot e Hermes Agent.
- Si installa da GitHub (
owner/repo), GitLab, Azure Repos, qualsiasi indirizzo Git, una cartella locale o un link diretto per scaricare unSKILL.mdo un archivio.
Passo 0 — Controlla Node.js e chiedi sempre la versione più recente
node --version # richiede v22.20.0 o successiva
Se stampa una versione più vecchia o “command not found”, installa la release LTS attuale da nodejs.org. Su un Mac con Homebrew, brew install node funziona altrettanto bene. Su un Raspberry Pi la versione presente nell’elenco dei pacchetti del sistema operativo è spesso troppo vecchia, quindi usa gli installer linkati da quella stessa pagina.
Poi rendi automatica un’abitudine: digita npx skills@latest invece del semplice npx skills per tutto ciò che controlla o aggiorna. Il semplice npx può riutilizzare una copia scaricata settimane fa, e con questo strumento la versione che esegui cambia ciò che fanno i comandi (la Parte 5 spiega l’esempio più importante).
Passo 1 — Guarda prima di installare
npx skills@latest add vercel-labs/agent-skills --list
--list mostra ogni skill presente nel repository con la sua descrizione e non installa nulla. Poi apri il repository nel browser e leggi il SKILL.md di tutto ciò che stai per installare, più gli eventuali script che lo accompagnano. Su skills.sh, la pagina di ogni skill mostra anche i risultati dell’audit di sicurezza (Parte 11).
Passo 2 — Installa una skill per gli agenti che usi
# Una skill, per OpenCode e Claude Code, nel progetto corrente
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a opencode -a claude-code
# La stessa skill per ogni progetto su questo computer
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a opencode -a claude-code
# Fissa un tag di release o un commit completo, così gli aggiornamenti sono voluti
npx skills add owner/[email protected] --skill my-skill
Ometti --skill e -a e la CLI ti chiede in modo interattivo: quali skill, quali agenti e se creare link o copiare. Ecco dove finisce tutto:
| Ambito di applicazione | L’unica copia reale | Link per gli agenti con una cartella propria | Il registro di ciò che hai installato |
|---|---|---|---|
| Progetto (il valore predefinito) | ./.agents/skills/<name> |
es. ./.claude/skills/<name> per Claude Code |
./skills-lock.json |
Globale (-g) |
~/.agents/skills/<name> |
es. ~/.claude/skills/<name>, ~/.hermes/skills/<name> |
~/.agents/.skill-lock.json |
La CLI conserva una sola copia reale in .agents/skills, che la maggior parte degli agenti legge direttamente, e crea link (symlink, in pratica delle scorciatoie) per gli agenti che cercano altrove. Una copia significa un solo aggiornamento. Se il tuo sistema non gestisce bene i symlink, cosa che può succedere su Windows, aggiungi --copy per ottenere invece copie indipendenti.
Passo 3 — Vedi cos’è installato
npx skills ls # gli skill di questo progetto
npx skills ls -g # i tuoi skill globali
npx skills ls -a opencode # solo quelli che riceve OpenCode
npx skills ls --json # leggibile dalla macchina, per gli script
Per le skill di progetto, le versioni attuali mostrano anche uno stato: tracciata (corrisponde al file di lock), modificata (modificata da te o dall’agente), non tracciata (nessuna voce nel file di lock, come una skill che hai scritto a mano) o mancante (nel file di lock ma non sul disco).
Passo 4 — Trova le skill
npx skills find # ricerca interattiva
npx skills find seo # ricerca per parola chiave
npx skills find react --owner vercel # solo i repository di una sola organizzazione
Oppure sfoglia skills.sh, che classifica le skill per numero di installazioni e le raggruppa per argomento. La skill più installata oggi è find-skills dall’repository di Vercel stesso, che insegna al tuo agente a cercare le skill da solo. I conteggi delle installazioni cambiano ogni giorno, quindi considera la classifica un indizio, non una recensione.
Passo 5 — Prova una skill senza installarla
npx skills use vercel-labs/agent-skills@web-design-guidelines
Questo stampa un prompt già pronto per quella skill, che puoi passare con una pipe o incollare in un agente sullo stesso computer. Aggiungi --agent claude-code e la CLI avvia Claude Code con la skill caricata. È un’ottima maniera per provare una skill prima che diventi parte della tua configurazione.
Passo 6 — Rimuovi le skill
npx skills remove web-design-guidelines # da questo progetto
npx skills rm --global web-design-guidelines # dai tuoi skill globali
npx skills remove --agent claude-code my-skill # solo da un agente
npx skills remove vercel-labs/agent-skills # tutto da quella fonte
npx skills remove # scegli da un elenco
npx skills remove --all rimuove ogni skill registrata nel file di lock e salta le cartelle che non ha installato, come le skill che hai scritto tu, così non cancellerà il tuo lavoro.
Passo 7 — Crea le tue
npx skills init my-skill crea my-skill/SKILL.md da un template. La Parte 10 illustra un esempio completo.
Tutto lo strumento su una sola scheda
| Voglio… | Comando |
|---|---|
| Vedere cosa offre un repository | npx skills@latest add owner/repo --list |
| Installa una skill in questo progetto | npx skills add owner/repo --skill name |
| Installa per ogni progetto | add -g |
| Scegli gli agenti | add -a opencode -a claude-code (oppure --agent '*' per tutti) |
| Installa senza domande | add -y |
| Fissa una versione | npx skills add owner/[email protected] --skill name |
| Elenca le skill installate | npx skills ls · npx skills ls -g |
| Ricerca | npx skills find keyword |
| Controlla gli aggiornamenti (sola lettura) | npx skills@latest check · add -g o -p |
| Installa gli aggiornamenti | npx skills update · -g · -p · -y · oppure indica le skill |
| Rimuovi | npx skills remove name · add -g per l’ambito globale |
| Ripristina le skill di un progetto dal suo lock file | npx skills install |
| Crea una nuova skill | npx skills init name |
Comandi per skills 1.8.1. npx skills install (un alias di experimental_install) e il experimental_sync comando per le skill incluse nei pacchetti npm sono contrassegnati come sperimentali e possono cambiare.

--list prima di installare, e @latest ogni volta che controlli o aggiorni.Cos’è un lock file e devo includerlo nel commit?
Un lock file è una ricevuta. Per ogni skill registra da dove proviene e una impronta della sua cartella (tecnicamente un hash: un breve codice che cambia ogni volta che cambia un file qualsiasi nella cartella). La CLI ne tiene due tipi:
skills-lock.jsonin un progetto. Salvalo nel commit su Git. Su un altro computer, o per un collega,npx skills installripristina esattamente le stesse skill, e--frozen-lockfile(l’impostazione predefinita in CI) rifiuta di continuare se qualcosa è diverso. Questo rende le skill di un progetto riproducibili, comepackage-lock.jsonfa per il codice.~/.agents/.skill-lock.jsonper le tue skill globali. Appartiene al tuo account utente (o si trova in$XDG_STATE_HOME/skills/.skill-lock.jsonse hai impostato quella variabile). Non modificarlo a mano, e nota che ogni utente su un computer ha il suo, cosa che conta nella Parte 6.
Telemetria, in breve
La CLI invia dati d'uso anonimi. Secondo la sua documentazione, i nomi dei repository GitHub e delle skill sono inclusi solo quando GitHub conferma che il repository è pubblico; anche altri tipi di fonte possono essere nominati. Per disattivarlo, aggiungi export DISABLE_TELEMETRY=1 (oppure DO_NOT_TRACK=1) al tuo profilo shell. Questo disattiva anche i controlli di sicurezza che la CLI esegue per le skill pubbliche, quindi decidi cosa conta di più per te.
Altri installer che incontrerai
La CLI skills non è l'unico modo per entrare. Diversi agenti e strumenti hanno i propri installer, e seguono tutti lo stesso standard aperto:
| Strumento | Esempio | Da sapere |
|---|---|---|
GitHub CLI (gh skill, versione 2.90 o successiva, in anteprima) |
gh skill install owner/repo skill-name --agent claude-code |
gh skill preview mostra una skill prima di installarla; --pin blocca una versione |
| Hermes Agent | hermes skills install <identifier> |
Il suo hub include skills.sh, e ogni installazione viene scansionata per la sicurezza |
| Gemini CLI | gemini skills install <git-url> |
--scope workspace per un solo progetto; chiede il consenso a meno che tu non passi --consent |
| Codex | $skill-installer <name> |
Una skill di sistema integrata |
| Claude Code | /plugin install name@marketplace |
I plugin raggruppano skill con server MCP e hook (Parte 9) |
Una regola evita la maggior parte dei grattacapi: aggiorna una skill con lo stesso strumento con cui l'hai installata. Ogni installer tiene i propri registri, e nessuno di loro sa cosa hanno fatto gli altri.
Parte 5 — “Il mio pacchetto di skill è stato aggiornato due giorni fa. Come faccio a sapere se ce l'ho?”
È stata esattamente la mia domanda quando Superpowers, la popolare libreria di skill di Jesse Vincent, ha annunciato un aggiornamento. npx skills ls elenca nomi, non versioni, quindi non può dirtelo. Ecco come fa la CLI a saperlo davvero.
Come funziona il controllo
Quando installi una skill, la CLI salva l'impronta della sua cartella nel file di lock. Quando controlli, chiede alla fonte (di solito GitHub) l'impronta della stessa cartella oggi. Stessa impronta: aggiornata. Diversa: c'è un aggiornamento. Non confronta numeri di versione né date, ed è per questo che funziona anche per le skill che non hanno né gli uni né le altre.
cd /tmp # oppure una cartella di progetto, ma mai la tua home
npx skills@latest check -g # le tue skill globali
cd ~/code/my-app
npx skills@latest check -p # le skill di questo progetto
Un risultato tipico nella 1.8.1 è questo:
↑ brainstorming ha un aggiornamento
↑ writing-plans ha un aggiornamento
2 skill possono essere aggiornate; esegui npx skills update per installarle
check segnala anche le skill di progetto i cui file non corrispondono più al file di lock (ha modifiche locali), ed esce con un codice di errore ogni volta che qualcosa è obsoleto o modificato, così puoi usarlo per fermare una build CI che si è scostata.
check è cambiato a novembre, quindi esegui la versione più recente
Dalla versione 1.7.5 (2 novembre 2026), check si limita a segnalare. Nelle versioni precedenti, almeno dalla 1.5.18 fino alla 1.7.4, check era semplicemente un altro nome per update: chiedeva “Update scope?” e installava gli aggiornamenti man mano. Se hai usato npx skills check prima di novembre e ti sei chiesto perché “aggiornasse” le cose, ecco il motivo. Usa npx skills@latest check e otterrai il comportamento in sola lettura.
Altri due dettagli che mettono in difficoltà:
checksceglie da solo un ambito. Se la cartella in cui ti trovi contiene unskills-lock.jsonfile, o una.agents/skillscartella con dentro una skill, controlla le progetto skill; altrimenti controlla quelle globali globali. Aggiungi-go-pper indicare quale intendi.- Non esiste un’opzione “aggiorna tutto da un unico repository”. O aggiorni tutto in un ambito, oppure indichi il nome delle skill.
Poi aggiorna
npx skills update # chiede: progetto, globale o entrambi
npx skills update -g # tutti gli skill globali
npx skills update -p # tutti gli skill di progetto
npx skills update brainstorming writing-plans -g # solo questi
npx skills update -y # nessuna domanda: progetto se sei in uno, altrimenti globale
Leggi le modifiche prima di aggiornare qualcosa di importante. Apri la cronologia dei commit del repository su GitHub e guarda cosa è cambiato nelle cartelle delle skill: un aggiornamento sono nuove istruzioni che il tuo agente seguirà con i tuoi permessi.
Se l’hai installato come plugin, aggiornalo come plugin
Molti pacchetti di skill ora vengono distribuiti come plugin, e Superpowers ne è un buon esempio. Il suo README elenca un percorso di installazione diverso per quasi ogni agente:
| Agente | Installazione di Superpowers, secondo il suo README | Come si aggiorna |
|---|---|---|
| Claude Code | /plugin install superpowers@claude-plugins-official |
Automaticamente, dal marketplace ufficiale di Anthropic |
| Codex CLI | /plugins, cerca “superpowers”, Installa plugin |
Tramite il gestore di plugin |
| Cursor | /add-plugin superpowers nella chat dell’agente |
Tramite il gestore di plugin |
| Gemini CLI | gemini extensions install https://github.com/obra/superpowers |
gemini extensions update superpowers |
| GitHub Copilot CLI | copilot plugin marketplace add obra/superpowers-marketplace, allora copilot plugin install superpowers@superpowers-marketplace |
Tramite il gestore di plugin |
| Hermes Agent | hermes plugins install obra/superpowers --enable |
Tramite il gestore di plugin |
| OpenCode | Aggiungi "superpowers@git+https://github.com/obra/superpowers.git" all'elenco dei plugin in opencode.json, come descrive la sua guida all'installazione per OpenCode |
Al riavvio; svuota la cache dei pacchetti di OpenCode se una nuova versione non compare, oppure aggiungi #v5.0.3-style tag per fissare la versione |
Dal README di Superpowers e dalla sua guida all'installazione per OpenCode, verificato il 15 novembre 2026.
Ho installato Superpowers sul mio Mac con npx skills -g, quindi il mio si aggiorna tramite la CLI skills. Va bene. Quello che non va bene è installare lo stesso pacchetto attraverso due canali: ti ritrovi con due copie di ogni skill con nomi identici, e nessun modo per capire quale sceglierà l'agente.

check confronta le impronte, non i numeri di versione. Dalla 1.7.5 si limita a segnalare; update è il comando che cambia qualcosa.Parte 6 — Cinque problemi reali dal mio Mac e dal Raspberry Pi, e come risolverli
Tutto quello che c'è in questa parte mi è successo nell'estate del 2026, con la versione 1.5 della CLI. Ogni problema è stato poi verificato sul codice sorgente della release attuale, la 1.8.1, così saprai quali sono risolti e quali mordono ancora. L'output del terminale è reale; l'ho accorciato e ho rimosso i nomi delle macchine.
Problema 1: “Tutte le skill globali sono aggiornate”, quando non era stato controllato nulla
Sul mio Mac, npx skills check ha prodotto questo:
graham@mac my-app % npx skills check
◇ Update scope
│ Both
Checking for skill updates…
Global Skills
Checking skills from source: anthropics/skills
│ GitHub API request limit reached; checking existing gh authentication…
✗ Failed to fetch tree for anthropics/skills
Checking skills from source: vercel-labs/skills
✗ Failed to fetch tree for vercel-labs/skills
… (six more sources, every one ✗)
Checking skills from source: obra/superpowers
✗ Failed to fetch tree for obra/superpowers
✓ All global skills are up to date
Cosa è successo. Per controllare un repository, la CLI chiede all'API di GitHub l'elenco dei file del repository. GitHub consente 60 richieste anonime all'ora per indirizzo internet, e la mia quota per quell'ora era già esaurita (lo strumento lo dice alla prima riga), quindi ogni ricerca è fallita. La riga finale conta solo gli aggiornamenti che lo strumento ha trovato, e non ne aveva trovato nessuno, così ha stampato una spunta verde. La vecchia versione provava anche a prendere in prestito un login della GitHub CLI dietro le quinte (è la riga “checking existing gh authentication”); dato che ogni richiesta falliva comunque, evidentemente non c'era alcun login da prendere in prestito.
È risolto? In parte. La versione 1.8.1 si impegna di più prima di arrendersi: prima in modo anonimo, poi un token dal tuo ambiente, poi il login della GitHub CLI stessa tramite gh api, e per i controlli di aggiornamento un semplice download Git come ultima risorsa. Ma il codice sorgente della 1.8.1 mostra che quando una fonte non può ancora essere controllata, la riga di riepilogo conta comunque solo gli aggiornamenti trovati. Una spunta verde sotto croci rosse è ancora possibile, quindi leggi le righe ✗.
La soluzione. Dai alla CLI un login, che alza il limite a 5.000 richieste all'ora:
- Il modo più semplice: installa la GitHub CLI ed esegui
gh auth login. Le versioni attuali della CLI skills chiedono aghdi fare la chiamata API e non vedono mai le tue credenziali. - Oppure usa un token: crea un token di accesso personale a grana fine con accesso in sola lettura ai repository pubblici, poi aggiungilo al tuo profilo della shell (
~/.zshrcsu un Mac,~/.bashrcsu un Raspberry Pi):
bash
export GITHUB_TOKEN="github_pat_…" # read-only, public repositories
Dopo apri un nuovo terminale. Tratta il token come una password: non incollarlo mai in una chat, in una skill o in un file che committi.
3. Aggiorna e ricontrolla: npx skills@latest check -g.
Problema 2: sudo mi ha creato due archivi di skill e un errore npm
Sul mio Raspberry Pi avevo preso l’abitudine di digitare sudo su per primo. Questo è quello che ha prodotto:
graham@pi:~ $ sudo su
root@pi:/home/graham# npx skills update
npm error config prefix cannot be changed from project config: /home/graham/.npmrc.
◇ Update scope
│ Both
Checking for skill updates…
Global Skills
…
Found 6 global update(s)
…
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…
E poco dopo, di nuovo come utente normale:
graham@pi:~ $ ls ~/.agents/skills | wc -l
7
graham@pi:~ $ sudo ls /root/.agents/skills | wc -l
37
Cosa è successo. sudo su ti trasforma in root, e root ha la sua cartella home, /root. Le skill sono archiviate per utente, quindi le skill globali dell’utente root stanno in /root/.agents/skills e le mie in /home/graham/.agents/skills. Ogni installazione globale che avessi mai fatto come root era finita nell’archivio di root: 37 skill lì, 7 nel mio. Se i tuoi agenti girano come utente normale, che è l’impostazione usuale, tutto quello che sta nell’archivio di root è invisibile a loro.
L’errore npm ha la stessa causa. Come root, il file delle impostazioni personali di npm è /root/.npmrc, quindi il /home/graham/.npmrc che si trova nella cartella in cui mi trovavo viene letto come un progetto file di impostazioni. Il codice di npm non permette a un file di progetto di cambiare l’impostazione prefix e registra esattamente quell’errore. C’è un terzo rischio che non vedi subito: qualunque cosa root scriva dentro la tua cartella home finisce di proprietà dell’utente root, e il tuo utente normale non può aggiornarla dopo.
La soluzione.
- Esci da root: tipo
exit. Da ora in poi, esegui la CLI e i tuoi agenti come te stesso. - Scopri quale utente usano i tuoi agenti. Qualunque cartella home contenga le loro impostazioni è quella che conta:
bash
ls -d ~/.claude ~/.config/opencode ~/.hermes 2>/dev/null
sudo ls -d /root/.claude /root/.config/opencode /root/.hermes 2>/dev/null
- Reinstalla come te stesso le skill dell’utente root, dalle loro fonti originali. Copiare i file si porterebbe dietro la proprietà dell’utente root e record obsoleti. Reinstallare scrive un lock file pulito. Prima elenca le fonti che root ha usato:
bash
sudo grep '"source"' /root/.agents/.skill-lock.json | sort -u
Poi, da una cartella di progetto o /tmp, esegui npx skills add <owner/repo> -g -a <your agents> per ognuna che ti serve ancora.
4. Riprenditi le tue cartelle, nel caso root ci abbia scritto dentro:
bash
sudo chown -R "$(id -un)":"$(id -gn)" ~/.agents ~/.claude ~/.hermes ~/.config/opencode 2>/dev/null
- Solo quando tutto funziona con il tuo utente, cancella la copia di root con
sudo rm -rf /root/.agents.
Se usi sudo perché le installazioni globali di npm falliscono senza, systema quello invece: punta il prefix di npm su una cartella che è tua (npm config set prefix ~/.npm-global, poi aggiungi ~/.npm-global/bin al tuo PATH). È quasi certamente quello che la prefix riga nel mio .npmrc faceva.
Problema 3: eseguilo dalla tua home e diventa un “progetto”
Di nuovo come me stesso, nella mia home:
graham@pi:~ $ npx skills check
Need to install the following packages:
[email protected]
Ok to proceed? (y) y
…
Global Skills
No global skills tracked in lock file.
Install skills with npx skills add <package> -g
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…
Cosa è successo. La CLI considera una cartella un progetto se contiene un skills-lock.json file o una .agents/skills cartella con dentro una skill. La tua home contiene ~/.agents/skills, perché è lì che vivono le skill globali, quindi da ~ la CLI vede un progetto. E se hai mai eseguito npx skills add nella tua home senza -g, hai creato lì una vera installazione di progetto, con il suo ~/skills-lock.json, la cui cartella delle skill è esattamente la stessa che usa l’installazione globale. È quello che era successo sul mio Pi: sette skill tracciate come “progetto” nella mia home e nulla di nulla nel mio file di lock globale.
“Nessuna skill globale tracciata nel file di lock” ha tre cause comuni: non hai mai installato con -g, hai installato con -g come utente diverso (root, tramite sudo), oppure il file di lock è stato cancellato. Se hai letto altrove che un generate-lock comando lo ricostruisce, sappi che non esiste: quel comando non c’è nelle versioni 1.5 e 1.8.
La soluzione.
- Esegui la CLI da una cartella di progetto o
/tmp, mai da~, e passa-go-pcosì non può tirare a indovinare. - Per districare un “progetto” nella home, reinstalla le skill che vuoi con
-gda un’altra cartella (finiscono nello stesso posto, ora registrate nel tuo file di lock globale), poi cancella~/skills-lock.json. Non eseguirenpx skills removeda~per questo: nella tua home, la cartella del progetto e quella globale sono la stessa cartella.
Problema 4: “Nessuna skill corrispondente trovata” per colpa dei due punti
graham@pi:~ $ npx skills remove ckm:banner-design ckm:brand ckm:design \
ckm:design-system ckm:slides ckm:ui-styling
◇ Trovate 7 skill installate uniche
■ Nessuna skill corrispondente trovata per: ckm:banner-design, ckm:brand, ckm:design, ckm:design-system, ckm:slides, ckm:ui-styling
Cosa è successo. Quelle skill compaiono come ckm:banner-design, ma i due punti sono un carattere rischioso in un nome di cartella, quindi la CLI le ha salvate come ckm-banner-design: converte il nome in minuscolo e trasforma in un trattino tutto ciò che non è una lettera, una cifra, un punto o un underscore. La versione 1.5.18 confrontava quello che digitavo esattamente con i nomi delle cartelle, quindi non trovava nulla.
È risolto? Sì. Le versioni attuali convertono il tuo input allo stesso modo prima del confronto, quindi ckm:brand e ckm-brand funzionano entrambi, e quando non c’è corrispondenza la 1.8.1 stampa i nomi che sono sono installati.
La soluzione. Esegui npx skills ls (oppure ls ~/.agents/skills) per vedere i nomi reali, oppure esegui npx skills remove senza argomenti e scegli dalla lista. Controlla anche lo scope: da una cartella di progetto, rimuovere una skill registrata nel tuo lock globale ora ti dice di aggiungere -g.
Problema 5: sei skill falliscono, una dello stesso repository funziona
Aggiornamento di 7 skill…
✗ Controllo delle skill eliminate da nextlevelbuilder/ui-ux-pro-max-skill non riuscito
Aggiornamento di ckm:banner-design…
✗ Aggiornamento di ckm:banner-design non riuscito
… (altre cinque ✗)
Aggiornamento di ui-ux-pro-max…
✓ ui-ux-pro-max aggiornata
Cosa è successo. Per aggiornare una skill, la CLI la cerca di nuovo nel repository di origine. Sei delle mie sette skill di quel repository non sono state trovate, mentre la settima si è aggiornata senza problemi. Quando la maggior parte delle skill di una sola fonte fallisce e una riesce, di solito quelle mancanti sono state rinominate, spostate o rimosse a monte. Il README di quel repository oggi descrive una sola skill, ui-ux-pro-max, e menziona banner, identità di marca e slide solo come funzioni di un piano a pagamento, il che quadra con il fatto che le sei abbiano lasciato il repository gratuito.
La soluzione. Guarda cosa offre ora la fonte, poi rimuovi ciò che non c’è più:
npx skills add nextlevelbuilder/ui-ux-pro-max-skill --list
npx skills remove ckm-banner-design ckm-brand ckm-design ckm-design-system ckm-slides ckm-ui-styling
Le versioni attuali della CLI notano le skill eliminate a monte e propongono di ripulirle durante un aggiornamento, e rimuovono le skill mancanti dal file di lock quando disinstalli. Già che ci sei, cerca i duplicati: se hai anche una semplice brand skill accanto a ckm-brand, tienine una. Due skill con descrizioni quasi identiche confondono la scelta dell’agente e sprecano il budget del suo elenco.
Bonus: Claude Code non vede una skill installata dalla CLI
- Controlla il link. Claude Code legge solo le proprie cartelle, quindi
ls -la ~/.claude/skills(oppure.claude/skillsnel progetto) dovrebbe mostrare la skill, di solito come link verso.agents/skills. Diverse release 1.5 hanno corretto bug sui link di Claude Code (1.5.16 e 1.5.20), quindi se manca, reinstalla connpx skills@latest add … -a claude-code. - Controlla che il file inizi correttamente. L’apertura
---del front matter deve essere la primissima riga diSKILL.md, altrimenti Claude Code tratta tutto il file come testo semplice. - Ricarica. Claude Code recepisce al volo le skill modificate, ma una cartella skills creata dopo l’avvio della sessione richiede
/reload-skills. Poi/skillselenca ciò che è caricato.

Parte 7 — I server MCP senza gergo
Cosa succede quando colleghi un server
- Aggiungi il server alle impostazioni del tuo agente: un comando per un server locale, un indirizzo web per uno remoto.
- Quando inizia una sessione, l’agente avvia il server locale o si collega a quello remoto, ed effettua l’accesso se il server lo richiede.
- Il server elenca i suoi strumenti, e l’agente passa le loro descrizioni al modello.
- Quando un’attività richiede uno strumento, il modello lo richiede, il tuo agente controlla le tue regole di autorizzazione (e potrebbe chiedertelo), il server fa il lavoro e il risultato torna nella conversazione.
Locale o remoto?
| Server locale (stdio) | Server remoto (Streamable HTTP) | |
|---|---|---|
| Esecuzione | Sul tuo computer, avviato dall’agente | Sui computer del provider |
| Aggiungi | Un comando, come npx @playwright/mcp@latest |
Un indirizzo, come https://mcp.context7.com/mcp |
| Accesso | Di solito una chiave API in una variabile d’ambiente | Di solito OAuth nel browser, o una chiave in un header |
| Richiede | Node.js, Python o Docker, a seconda del server | Una connessione a internet |
| Ideale per | Cose sulla tua macchina: un browser, file, un database locale | Servizi cloud: GitHub, Sentry, documentazione, strumenti di progetto |
| Attenzione a | Gira con tutti i permessi del tuo utente | I tuoi dati vanno a quel provider |
Potresti ancora vedere un terzo tipo, SSE, nelle guide più vecchie. La documentazione di Claude Code lo segna come deprecato; usa l’indirizzo HTTP quando un server offre entrambi.
Una parola sulle versioni
La specifica MCP attuale, pubblicata il 28 luglio 2026, è la revisione più grande da quando il protocollo è stato lanciato: il suo nucleo ora è stateless, il che permette ai server remoti di girare dietro normali load balancer. Raramente devi preoccupartene, perché client e server si accordano su quale revisione parlare e i server più vecchi continuano a funzionare. OpenCode è l’unico punto in cui potresti vederlo: ogni server ha un protocollo impostazione (legacy per impostazione predefinita, auto, o 2026-07-28), e il connection pooling funziona solo con la revisione più recente.
Il conto del contesto, e come tenerlo basso
Ogni strumento che un server offre arriva con una descrizione scritta per il modello. Per usare l’espressione di OpenCode stesso, “Gli strumenti MCP consumano contesto del modello, quindi aggiungi solo i server che ti servono.” Due agenti ora attenuano il costo per impostazione predefinita:
- Claude Code usa la ricerca degli strumenti. All’inizio di una sessione carica solo i nomi degli strumenti e le istruzioni di ogni server, e recupera l’intera definizione di uno strumento quando Claude la cerca davvero.
- OpenCode usa Code Mode, che raggruppa gli strumenti di ogni server dietro un’unica voce invece di elencare ogn’uno di essi. È attivo a meno che tu non imposti
"codemode": falseper un server.
In tutto il resto, e in aggiunta a queste impostazioni predefinite, questi sono i tuoi controlli:
| Agente | Disattivare un server | Nascondere gli strumenti che non vuoi |
|---|---|---|
| OpenCode | "disabled": true, o /mcps per una sola sessione |
A deny regola su <server>_<tool> nei permessi |
| Claude Code | claude mcp remove <name> (/mcp mostra lo stato) |
A deny regola di permesso su mcp__<server>__<tool>; ENABLE_TOOL_SEARCH decide quanto si carica in anticipo |
| Codex | enabled = false |
enabled_tools e disabled_tools |
| Gemini CLI | gemini mcp disable <name> (aggiungi --session per una sola sessione) |
includeTools e excludeTools |
| Cursor | L’interruttore del server in Personalizza | (Gli amministratori possono impostare elenchi di strumenti consentiti) |
| Hermes Agent | enabled: false |
tools.include e tools.exclude |
La mia regola: da due a cinque server che usi ogni settimana battono venti che potresti usare un giorno. Rimuovi gli altri; puoi rimetterli in un minuto.
Quattro server da provare per primi
| Server | Cosa dà al tuo agente | Tipo | Indirizzo o comando | Accesso |
|---|---|---|---|---|
| Context7 | Documentazione aggiornata e specifica per versione delle librerie e dei framework più diffusi | Remoto | https://mcp.context7.com/mcp |
Nessuna necessaria; una chiave API gratuita alza i limiti |
| GitHub (ufficiali) | Issue, pull request, ricerca nel codice, Actions | Remoto | https://api.githubcopilot.com/mcp/ |
OAuth dove il tuo agente lo supporta, oppure un token di accesso personale |
| Playwright | Un browser reale che l’agente può aprire, in cui può cliccare e fare screenshot | Locale | npx @playwright/mcp@latest |
Nessuno |
| Sentry | I tuoi errori e crash reali | Remoto | https://mcp.sentry.dev/mcp |
OAuth |
Dove trovarne altri:
- Il registro ufficiale MCP Registry, mantenuto dai contributori del protocollo, elenca i server pubblicati.
- La documentazione dei tuoi strumenti. Oggi la maggior parte dei servizi pubblica un server ufficiale; cerca “MCP” nella loro documentazione.
- Il catalogo del tuo agente. Hermes Agent ha
hermes mcp catalog, e molti plugin di Claude Code portano i propri server.
Preferisci i server pubblicati dall’azienda che gestisce il servizio. Un server qualsiasi chiamato “github-mcp-pro” merita la stessa diffidenza di un’estensione per browser qualsiasi.
L’opzione più leggera: uno strumento da riga di comando più una skill
Prima di aggiungere un server, controlla se uno strumento da riga di comando fa il lavoro. Context7 stesso offre entrambe le strade: il server MCP qui sopra, oppure una piccola CLI con una skill (npx ctx7 setup --opencode, che richiede Node.js 22.13 o successivo). Lo strumento di GitHub gh con una breve skill copre gran parte di ciò che fa il suo server.
Un server ha senso quando il tuo agente non può eseguire comandi (un’app di chat desktop, per esempio), il servizio non ha una buona CLI, oppure il lavoro è interattivo, come guidare un browser. Una CLI più una skill ha senso quando lo strumento esiste già: non costa nulla finché non lo usi, e il suo output può essere ridotto prima di arrivare al modello. Il mio guida a OpenCode sostiene la stessa tesi per lo sviluppo di app.
Parte 8 — Aggiungere un server MCP in sei agenti: ricette da copiare e incollare
Ogni ricetta aggiunge gli stessi due server: Context7 (remoto) e Playwright (locale). Sostituisci con qualsiasi altro server allo stesso modo. Quando un agente ha sia un comando sia un file di impostazioni, il comando scrive semplicemente il file per te.
OpenCode
opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp add playwright -- npx @playwright/mcp@latest
opencode mcp list
Aggiungi --global per rendere un server disponibile in ogni progetto. In opencode.jsonc la stessa configurazione si presenta così:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"oauth": false
// With a free API key, add:
// "headers": { "Authorization": "Bearer {env:CONTEXT7_API_KEY}" }
},
"playwright": {
"type": "local",
"command": ["npx", "@playwright/mcp@latest"]
}
}
}
}
- I segreti si inseriscono come
{env:NAME}; OpenCode non espande una semplice$NAME. - I server remoti provano OAuth automaticamente;
oauth: falseserve per i server che usano una chiave o nessuna. Accedi conopencode mcp auth <name>, e via SSH incolla nel prompt l'URL di callback della pagina del browser che ha fallito. - All'interno di una sessione,
/mcpscollega, scollega o effettua l'accesso ai server. - Ogni strumento diventa un'azione di autorizzazione chiamata
<server>_<tool>, quindi{ "action": "playwright_*", "resource": "*", "effect": "ask" }fa chiedere conferma prima di ogni azione del browser.
Claude Code
claude mcp add --transport http context7 https://mcp.context7.com/mcp
claude mcp add playwright -- npx @playwright/mcp@latest
claude mcp list
L’ -- separa le opzioni di Claude Code dal comando del server stesso. I server usano per impostazione predefinita l'ambito locale (tu, in questo progetto). Aggiungi --scope user per tutti i tuoi progetti, oppure --scope project per scrivere un .mcp.json file che puoi committare per il tuo team:
{
"mcpServers": {
"context7": {
"type": "http",
"url": "https://mcp.context7.com/mcp"
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
.mcp.jsonespande${VAR}e${VAR:-default}, così le chiavi restano nel tuo ambiente e non in Git./mcpall'interno di una sessione mostra lo stato di ogni server e gestisce l'accesso OAuth.- Claude Code chiede prima di usare i server da un
.mcp.json, così un repository clonato non può aggiungerne di propri di nascosto.
Codex
Codex tiene i server in ~/.codex/config.toml, oppure in .codex/config.toml all'interno di un progetto che hai contrassegnato come affidabile:
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
- I server remoti possono anche essere aggiunti con
codex mcp add context7 --url https://mcp.context7.com/mcp, ecodex mcp login <name>esegue un accesso OAuth. - Per una chiave,
bearer_token_env_var = "CONTEXT7_API_KEY"la legge dal tuo ambiente. - Regola un server con
enabled_toolsedisabled_tools;startup_timeout_sec(10 secondi per impostazione predefinita) aiuta i server lenti ad avviarsi.
Gemini CLI
gemini mcp add -t http context7 https://mcp.context7.com/mcp
gemini mcp add playwright npx @playwright/mcp@latest
gemini mcp list
gemini mcp add scrive nelle impostazioni del progetto per impostazione predefinita; aggiungi -s user per ogni progetto. In settings.json:
{
"mcpServers": {
"context7": { "httpUrl": "https://mcp.context7.com/mcp" },
"playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
}
}
httpUrlserve per Streamable HTTP;urlindica il tipo SSE più vecchio.- Lascia
trustdisattivato. Impostandolo suvero, salta ogni conferma per quel server. - Gemini CLI rimuove le variabili che sembrano segreti (nomi che contengono TOKEN, SECRET, PASSWORD o KEY) dall’ambiente di un server, a meno che tu non le elenchi nel suo
envblocco. - OAuth richiede un browser sulla stessa macchina. In una cartella non attendibile, i server locali restano disconnessi finché non esegui
gemini trust.
Cursor
Cursor legge .cursor/mcp.json in un progetto e ~/.cursor/mcp.json per tutto:
{
"mcpServers": {
"context7": { "url": "https://mcp.context7.com/mcp" },
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
- I server locali richiedono
"type": "stdio". - I segreti si inseriscono come
${env:NAME}. - Attiva e disattiva i server con i loro interruttori in Personalizza.
Hermes Agent
Hermes legge mcp_servers in ~/.hermes/config.yaml:
mcp_servers:
context7:
url: "https://mcp.context7.com/mcp"
playwright:
command: "npx"
args: ["@playwright/mcp@latest"]
- Esegui
/reload-mcpdopo aver modificato, ehermes mcp test context7per vedere esattamente cosa ha risposto un server. - Per i servizi OAuth, aggiungi
auth: oautha una voce HTTP. Su una macchina headless, Hermes offre il paste-back, il port forwarding SSH o un flusso di accesso tramite dispositivo. - Hermes passa ai server locali solo le variabili che elenchi in
envpiù una base sicura, non l’intero ambiente della tua shell. - Gli strumenti appaiono come
mcp_<server>_<tool>; filtra contools.includeotools.exclude.
Verifica che funzioni, in qualsiasi agente
Fai una domanda a cui solo il server può rispondere: “Usa Context7 per cercare come definire una route nella versione attuale di Next.js, e dimmi quale strumento hai chiamato.” Poi chiedi qualcosa di visibile: “Apri example.com con Playwright e descrivi la pagina.” Se l’agente dice di non avere questi strumenti, elenca i server (opencode mcp list, claude mcp list, gemini mcp list, hermes mcp test) e cerca una connessione fallita o un accesso che non è mai terminato.

Parte 9 — Plugin: skill e server MCP in un unico pacchetto
Installare dieci skill e tre server uno alla volta stanca. I plugin li raggruppano, e ormai quasi tutti gli agenti hanno un qualche sistema di plugin.
Plugin di Claude Code
Un plugin di Claude Code può contenere skill, subagenti, hook, server MCP e server linguistici. I plugin provengono da marketplace, che sono semplicemente cataloghi ospitati in un repository Git:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
In una sessione, /plugin install apre prima i dettagli del plugin, così vedi esattamente cosa aggiunge prima di scegliere un ambito: tu (ogni progetto), questo repository per tutti, o questo repository solo per te. Dalla tua shell, claude plugin install <name>@<marketplace> fa lo stesso senza una sessione.
Tre funzionalità che vale la pena conoscere:
- Il costo in contesto è visibile. Per i plugin nel marketplace ufficiale di Anthropic, il pannello dei dettagli stima quanto il plugin aggiunge a ogni messaggio e quanto aggiunge quando viene usato.
claude plugin details <name>mostra il valore per sessione di tutto ciò che è installato. - Aggiornamenti. Il marketplace ufficiale di Anthropic aggiorna i plugin automaticamente; quelli di terze parti no, a meno che tu non lo attivi.
claude plugin update <name>@<marketplace>aggiorna a mano un singolo plugin. - I plugin inutilizzati sono segnalati. La scheda Installati raggruppa i plugin che non usi di recente, il che rende facile fare pulizia.
Plugin altrove
- Codex distribuisce skill riutilizzabili tramite plugin (
/pluginsnella CLI), e un plugin può anche trasportare connessioni a server MCP. - Gemini CLI li chiama estensioni:
gemini extensions install <git-url>egemini extensions update <name>. - GitHub Copilot CLI (
copilot plugin install) e Hermes Agent (hermes plugins install) hanno comandi plugin, e Cursor ha/add-pluginnella chat dell’agente. - OpenCode i plugin sono pacchetti JavaScript o TypeScript elencati nella
dei pluginimpostazione della sua configurazione, che può registrare skill e strumenti. Superpowers si installa così.
Le due regole che tengono in ordine un’installazione a plugin
- Un canale per pacchetto. Se un pacchetto di skill esiste sia come plugin sia come skill semplici, scegline uno. Due copie significano nomi duplicati e un agente che sceglie quella che vede per prima.
- Aggiorna dove hai installato. La CLI skills non conosce i plugin, e i gestori di plugin non conoscono
~/.agents/skills.
Parte 10 — Scrivi la tua prima skill in dieci minuti
La prima skill migliore risolve un lavoro che ripeti. Eccone una costruita dalla Parte 6: una skill che permette a qualsiasi agente di controllare se le tue skill hanno aggiornamenti in sicurezza, senza mai usare sudo né fidarti ciecamente di una spunta verde.
Passo 1 — Crea la cartella
mkdir -p ~/skills-drafts && cd ~/skills-drafts
npx skills init skills-housekeeping
Questo crea skills-housekeeping/SKILL.md da un template. Sostituisci il contenuto con questo:
---
name: skills-housekeeping
description: Controlla se le skill degli agenti installate hanno aggiornamenti e problemi con la CLI npx skills, e spiega i risultati in parole semplici. Usala quando ti viene chiesto se le skill sono aggiornate, per aggiornare le skill, o quando una skill installata sembra mancare.
metadata:
author: graham-miranda
version: "1.0"
---
# Manutenzione delle skill
## Regole
- Non eseguire mai comandi con sudo.
- Non eseguire mai `npx skills update` o `npx skills remove` senza prima chiedere.
- Esegui i comandi da /tmp o da una cartella di progetto, mai dalla cartella home.
## Controllo
1. Esegui `cd /tmp && npx skills@latest check -g` per le skill globali.
2. Se il progetto attuale ha un file skills-lock.json, esegui anche `npx skills@latest check -p` nella cartella del progetto.
3. Considera ogni riga che inizia con ✗ come "non controllata", anche se una riga successiva dice che è tutto aggiornato.
## Resoconto
- Elenca le skill con aggiornamenti, le skill con modifiche locali e tutto ciò che non è stato possibile controllare.
- Se un controllo è fallito, suggerisci `gh auth login`, oppure un GITHUB_TOKEN con accesso in sola lettura ai repository pubblici.
- Chiedi prima di aggiornare. Poi esegui `npx skills update -g` (o `-p`) e riporta cosa è cambiato.
Passo 2 — Verificala rispetto allo standard
- Nome:
skills-housekeepingusa solo lettere minuscole e trattini, resta sotto i 64 caratteri e corrisponde al nome della cartella. Tutti e tre i requisiti sono obbligatori. - Descrizione: dice cosa cosa fa la skill e quando quando usarla, e contiene le parole che le persone digitano davvero (“aggiornato”, “aggiorna le skill”, “mancante”). La descrizione è l’unica parte che l’agente vede prima di decidere, quindi fa la maggior parte del lavoro. Lo standard consente fino a 1.024 caratteri; punta a una o due frasi.
- Lunghezza: ben sotto le 500 righe consigliate. Quando una skill cresce, sposta i dettagli in
references/e puntaci dalle istruzioni.
Il progetto Agent Skills pubblica un validatore di riferimento, skills-ref, che controlla il front matter e le regole di denominazione: skills-ref validate ./skills-housekeeping.
Passo 3 — Installala per tutti gli agenti in una volta
La CLI skills installa anche da una cartella locale:
npx skills add ./skills-housekeeping -g -a opencode -a claude-code -a codex
Questo mette la copia reale in ~/.agents/skills/skills-housekeeping (letta direttamente da OpenCode e Codex) e aggiunge un link in ~/.claude/skills per Claude Code.
Passo 4 — Provala
Chiedi con parole semplici: “Le mie skill sono aggiornate?” Una skill ben descritta viene rilevata automaticamente. Se non succede, chiamala per nome per escludere un problema di caricamento: @skills-housekeeping in OpenCode, /skills-housekeeping in Claude Code, $skills-housekeeping in Codex. Se si carica per nome ma mai da sola, il problema è la descrizione: aggiungi le frasi che usi davvero.
Passo 5 — Condividila
Carica la cartella in un repository GitHub, idealmente dentro una skills/ cartella (skills/skills-housekeeping/SKILL.md). Chiunque può poi installarla con npx skills add your-name/your-repo. La CLI trova le skill in skills/ e nelle cartelle comuni degli agenti, fino a tre livelli di profondità.
Extra specifici per agente, e quando evitarli
Diversi agenti comprendono campi front matter aggiuntivi. Claude Code ha disable-model-invocation (solo tu puoi attivare la skill) e context: fork (eseguirla in un subagent); Cursor ha paths (solo per i file corrispondenti); OpenCode può nascondere una skill al modello con metadata impostato su opencode/autoinvoke: false. Sono utili, ma sono i campi standard quelli che viaggiano. La documentazione di Claude Code stessa nota che fuori da Claude Code, nei caricamenti su claude.ai o nella Skills API, vengono accettati solo i campi standard e qualsiasi altra cosa è un errore. Per le skill che condividi, attieniti a nome, descrizione, license, compatibility, metadata e lo sperimentale allowed-tools.

Parte 11 — Restare al sicuro: le skill e i server sono software
È facile pensare a una skill come “solo un file Markdown”. In realtà non lo è. Sono istruzioni che il tuo agente seguirà con i tuoi permessi, spesso con script che eseguirà sulla tua macchina. E un server MCP locale è un programma che gira con i tuoi privilegi.
I numeri di quest’anno fanno riflettere. Lo studio ToxicSkills di Snyk, pubblicato a febbraio 2026, ha analizzato 3.984 skill pubbliche per agenti: il 36,82% aveva almeno una falla di sicurezza, il 13,4% ne aveva una critica e 76 contenevano payload malevoli confermati. Il problema si è concentrato su ClawHub, il marketplace della community per OpenClaw, dove un audit precedente di 2.857 skill, anch’esso riportato da Snyk, aveva trovato 341 malevole, circa il 12% del registro all’epoca. Al contrario, le 100 skill più popolari su skills.sh non hanno attivato nessuno dei controlli di Snyk su prompt injection o codice malevolo. La popolarità non è una prova, ma aiuta.
MCP ha la sua versione del rischio. La documentazione di Claude Code avverte che i server che recuperano contenuti esterni possono esporti a prompt injection: una pagina web, un commento in un issue o un crash report che contengono testo rivolto al tuo agent invece che a te.
Dieci abitudini che ti tengono al sicuro
- Leggi prima di installare. Utilizzo
npx skills add owner/repo --list,gh skill preview, oppure apri semplicemente ilSKILL.mde i suoi script su GitHub. - Preferisci i produttori e gli autori noti. Le skill di Expo per Expo, quelle di Vercel per Next.js, il server MCP ufficiale di un fornitore per il proprio servizio.
- Controlla gli audit. Ogni skill su skills.sh mostra i risultati di tre scanner: Gen Agent Trust Hub, Socket e Snyk. “In attesa” significa che nessuno l’ha ancora esaminata.
- Fissa la versione di tutto ciò che conta.
npx skills add owner/[email protected], ogh skill install … --pin v1.2.3, così gli aggiornamenti avvengono quando decidi tu. - Esamina gli aggiornamenti come il codice.
npx skills check, poi leggi le modifiche su GitHub, poinpx skills update. - Metti un controllo sulle skill di terze parti. In OpenCode, le regole usano l’azione
skille vince l’ultima corrispondenza:
jsonc
"permissions": [
{ "action": "skill", "resource": "*", "effect": "ask" },
{ "action": "skill", "resource": "skills-housekeeping", "effect": "allow" },
{ "action": "playwright_*", "resource": "*", "effect": "ask" }
]
Hermes Agent analizza ogni installazione dall’hub, e --force non può ignorare un verdetto “pericoloso”. Gemini CLI chiede il tuo consenso prima di attivare una skill.
7. Dai ai server il minimo accesso che funziona. Token in sola lettura e con permessi granulari; token separati per ogni server; strumenti di scrittura ed eliminazione su “chiedi” o esclusi.
8. Tieni i segreti fuori dalle skill e dalla configurazione versionata. Usa variabili d’ambiente ({env:NAME} in OpenCode, ${VAR} in Claude Code il file .mcp.json, ${env:NAME} in Cursor), mai chiavi incollate.
9. Fai attenzione alle impostazioni di progetto di altri. Un repository clonato può portarsi dietro i propri .mcp.json o le skill. Claude Code chiede prima di usare i server di progetto, Gemini CLI tiene i server locali disconnessi nelle cartelle non attendibili, e Hermes Agent carica le skill di progetto solo dopo hermes skills trust. Non confermare quei prompt in automatico.
10. Disinstalla ciò che non usi. Ogni skill e ogni server inutilizzato è superficie d’attacco che paghi in termini di contesto.

Parte 12 — Una routine settimanale di due minuti
Le skill e i server cambiano nel tempo. Una piccola routine li tiene in riga:
# Skill globali, da una cartella neutra
cd /tmp && npx skills@latest check -g
# Ogni progetto su cui stai lavorando
cd ~/code/my-app && npx skills@latest check -p
# Dopo aver letto cosa è cambiato a monte:
npx skills update -g
Una volta al mese, prenditi altri cinque minuti:
- Fai pulizia.
npx skills ls -ge rimuovi ciò che non hai usato. In Claude Code, il pannello dei plugin elenca i plugin che non usi da tempo. - Elenca i tuoi server.
opencode mcp list,claude mcp list,gemini mcp listohermes mcp testper ciascuno. Rimuovi tutto ciò che hai dimenticato di aggiungere. - Ruota i token che hai dato ai server, soprattutto quelli con permessi di scrittura.
Due macchine, una configurazione
Uso gli agenti su un Mac e su un Raspberry Pi, e tre abitudini li tengono allineati:
- Stesso approccio su entrambe: il tuo utente normale, mai
sudo, e la CLI eseguita da una cartella di progetto o/tmp. - Le skill di progetto viaggiano con Git. Commit
.agents/skillseskills-lock.json; sull’altra macchina,npx skills installripristina esattamente le stesse versioni. - Le skill globali arrivano da uno script. Mantieni il tuo
npx skills add … -gi comandi in un piccolo file shell ed eseguilo su ogni macchina. Funge anche da documentazione di ciò su cui fai affidamento.
Su una macchina headless come un Pi, imposta GITHUB_TOKEN in ~/.bashrc così i controlli degli aggiornamenti non toccano il limite anonimo. Gli accessi via browser richiedono attenzione: OpenCode ti permette di incollare l’URL di callback nel suo prompt, Hermes Agent offre paste-back, port forwarding SSH o un device flow, mentre il flusso OAuth di Gemini CLI richiede un browser sulla stessa macchina.
Parte 13 — Quale configurazione scegliere? Cinque scenari
1. “Ho appena iniziato con OpenCode.”
Installa al massimo tre skill e un server MCP. Context7 è un buon primo server, e una skill di rilascio o di revisione che corrisponde a come lavori è una buona prima skill. Tieni le skill di terze parti su ask nelle autorizzazioni di OpenCode finché non ti fidi. La mia guida a OpenCode copre il resto della configurazione.
2. “Uso OpenCode e Claude Code fianco a fianco, magari anche Hermes Agent.”
Installa le skill a livello globale con la CLI e nomina ogni agente: npx skills add owner/repo -g -a opencode -a claude-code -a hermes-agent. Una copia, tre agenti. I server MCP non condividono un file di configurazione comune, quindi aggiungi ognuno a ogni agente e tieni la lista da qualche parte dove la ritroverai. Il mio confronto tra OpenCode, Hermes Agent e OpenClaw spiega in cosa eccelle ogni agente, e la mia confronto tra harness di coding IA ne copre 28 fianco a fianco.
3. “Il mio team condivide un repository.”
Utilizzo ambito di progetto: fai il commit di .agents/skills, skills-lock.json, e le impostazioni MCP (opencode.jsonc, .mcp.json o .cursor/mcp.json) senza segreti all’interno. Ognuno tiene le chiavi nel proprio ambiente. In CI, npx skills install --frozen-lockfile fallisce se le skill di qualcuno divergono, e npx skills check -p fallisce quando ci sono aggiornamenti in attesa.
4. “I miei agenti girano su un Raspberry Pi o su un server.”
Un solo utente normale, niente sudo, mai. Set GITHUB_TOKEN, preferisci i server remoti che accettano un token in un header (o offrono un accesso da dispositivo), e lancia il controllo settimanale da /tmp. La parte 6 è la tua checklist.
5. “Il mio codice non deve uscire dalla mia macchina.”
Utilizzo solo server MCP locali, e salta i server remoti di documentazione e ricerca nel codice. Disattiva la telemetria della CLI (DISABLE_TELEMETRY=1), leggi ogni skill che installi e ricorda che il modello stesso può restare un modello cloud: la privacy dipende da dove modello viene eseguito anche. La mia guida per eseguire LLM su un MacBook spiega quanto costa davvero la strada completamente locale.
Domande frequenti
Le skill degli agenti sono cartelle che insegnano a un agente IA come svolgere un compito specifico. Ognuna contiene un SKILL.md file con un nome, una descrizione e istruzioni passo dopo passo, più script e file di riferimento opzionali. All’inizio di una sessione l’agente legge solo le descrizioni e carica le istruzioni complete di una skill quando un compito corrisponde. Le skill seguono uno standard aperto, quindi la maggior parte funziona allo stesso modo in OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot e Hermes Agent.
Un server MCP è un piccolo programma che dà a un agente IA nuovi strumenti tramite il Model Context Protocol, uno standard aperto ora ospitato dalla Agentic AI Foundation della Linux Foundation. I server locali girano sul tuo computer e vengono avviati dall’agente; i server remoti girano sui computer di un fornitore e si raggiungono con un indirizzo web, di solito con un accesso dal browser. Gli esempi includono il server ufficiale di GitHub, Context7 per la documentazione aggiornata e Playwright per controllare un browser.
Una skill dà all’agente il know-how: istruzioni scritte su come svolgere un lavoro, caricate solo quando servono. Un server MCP dà all’agente capacità: strumenti che raggiungono sistemi fuori dal terminale, come GitHub, un browser o un crash tracker. Usa una skill per procedure e convenzioni, un server MCP per l’accesso in tempo reale a un sistema e AGENTS.md per le regole valide per ogni compito. Se esiste già un buon strumento da riga di comando, una skill che lo insegna è spesso più economica di un server.
In gran parte sì, perché tutti e tre seguono lo standard Agent Skills. La differenza sta in dove guardano. Codex e OpenCode leggono le .agents/skills e ~/.agents/skills cartelle condivise; OpenCode legge anche .opencode/skills e le cartelle di Claude Code. Claude Code legge solo .claude/skills e ~/.claude/skills. Alcuni campi extra del front matter, come quelli di Claude Code context: fork, funzionano in un solo agente, quindi le skill condivise dovrebbero attenersi ai campi standard.
Esegui npx skills add owner/repo --list per vedere le skill offerte da un repository, poi npx skills add owner/repo --skill skill-name -a opencode -a claude-code per installarne una per gli agenti che usi. Aggiungi -g per renderla disponibile in ogni progetto. Serve Node.js 22.20 o successivo. Senza flag, la CLI chiede quali skill e quali agenti vuoi e se collegare o copiare i file.
Le installazioni nel progetto mettono la copia reale in .agents/skills/<name> dentro il tuo progetto e la registrano in skills-lock.json. Le installazioni globali (-g) la mettono in ~/.agents/skills/<name> e la registrano in ~/.agents/.skill-lock.json. Gli agenti che leggono .agents/skills usano quella copia direttamente; per gli agenti con una cartella propria, come Claude Code (.claude/skills) o Hermes Agent (~/.hermes/skills), la CLI crea un collegamento ad essa.
Esegui npx skills@latest check -g per le skill globali, oppure npx skills@latest check -p dentro un progetto. La CLI confronta l’impronta di ogni cartella di skill nel tuo lock file con la stessa cartella a monte ed elenca ogni skill che ha un aggiornamento, senza installare nulla. Dalla versione 1.7.5 (2 novembre 2026), check si limita a segnalare; npx skills update installa. Eseguilo da una cartella di progetto o /tmp, non dalla tua cartella home.
Perché il riepilogo conta solo gli aggiornamenti che ha trovato. Se il limite di GitHub di 60 richieste API anonime all’ora blocca ogni ricerca, la CLI stampa una riga ✗ per ogni sorgente e può comunque chiudere con “Tutte le skill globali sono aggiornate”. Accedi con gh auth login oppure imposta come sola lettura un GITHUB_TOKEN per portare il limite a 5.000 richieste all'ora, esegui l'upgrade con npx skills@latest, e leggi sempre le righe ✗.
No. Le skill sono memorizzate per utente, e root ha la propria cartella home, quindi sudo installa le skill in /root/.agents/skills, dove gli agenti eseguiti con il tuo utente normale non le vedranno mai. Può anche lasciare file di proprietà di root nelle tue cartelle e generare errori npm come “prefix cannot be changed from project config”. Esegui la CLI e i tuoi agenti con il tuo utente normale.
Esegui opencode mcp add <name> --url <address> per un server remoto, oppure opencode mcp add <name> -- <command> per uno locale, poi verificalo con opencode mcp list. Aggiungi --global per usarlo in ogni progetto. Le stesse impostazioni possono stare sotto mcp.servers in opencode.jsonc, con i segreti scritti come {env:NAME}. Usa opencode mcp auth <name> per accedere, e /mcps all'interno di una sessione per connettere o disconnettere i server.
Il minor numero possibile, solo quelli che usi davvero, di solito da due a cinque. Gli strumenti di ogni server arrivano con descrizioni che il modello deve leggere, il che consuma contesto e può rendere le risposte più lente e meno concentrate. Claude Code rimanda le definizioni degli strumenti finché non servono e OpenCode le raggruppa per server, il che aiuta, ma i server inutilizzati aggiungono comunque rischio e confusione. Rimuovi tutto ciò che non hai usato per un mese.
Sicure solo quanto la loro fonte. Una skill è un insieme di istruzioni che il tuo agente segue con i tuoi permessi, spesso con script che esegue. Lo studio di Snyk di febbraio 2026 su 3.984 skill pubbliche ha rilevato difetti di sicurezza nel 36,82% e ha confermato payload malevoli in 76. Leggi una skill e i suoi script prima di installarla, preferisci le skill degli autori dello strumento, controlla i risultati degli audit su skills.sh, blocca le versioni e tieni le skill di terze parti su “ask” nei permessi del tuo agente.
È il file di lock del progetto che la CLI skills scrive quando installi skill in un progetto. Registra da dove viene ogni skill e un'impronta dei suoi file. Fai il commit su Git: su un altro computer, npx skills install ripristina esattamente le stesse skill, e --frozen-lockfile fallisce se qualcosa differisce. Le skill globali hanno un file di lock separato in ~/.agents/.skill-lock.json, uno per account utente.
skills.sh è la directory pubblica di Vercel per le skill degli agenti. Classifica le skill per numero di installazioni, le raggruppa per argomento e mostra per ognuna i risultati degli audit di sicurezza di Gen Agent Trust Hub, Socket e Snyk. Installi le skill da lì con il npx skills add owner/repo comando che mostra. Il comando della stessa CLI npx skills find cerca nella directory dal tuo terminale.
In sintesi
Le skill degli agenti e i server MCP rispondono a due domande diverse. Le skill rispondono a “come si fa questo, qui?”: sono schede ricetta economiche e portatili che si caricano solo quando servono. I server MCP rispondono a “riesci a raggiungere quel sistema?”: sono chiavi potenti che consumano contesto e meritano la stessa cura di qualsiasi software tu installi. AGENTS.md contiene le poche regole valide per tutto, e i permessi impongono ciò che non deve mai accadere.
Se devi portarti a casa cinque cose da questa guida, sono queste:
- Metti le skill condivise in
.agents/skillse lascia chenpx skillsle colleghi negli agenti che cercano altrove. - Esegui
npx skills@latest checkda una cartella di progetto o/tmp, leggi le righe ✗ e aggiorna con criterio. - Accedi a GitHub (
gh auth login) su ogni macchina che controlla gli aggiornamenti. - Non usare mai
sudocon skill o agenti. - Inizia con tre skill e un server, e aggiungine altre solo quando un compito reale lo richiede.
Le skill e i server trasformano un brillante generalista in un collega che conosce il tuo modo di lavorare e sa arrivare ai tuoi strumenti. Il trucco è dargli esattamente quello che gli serve, e niente di più.
Usi skill o server MCP che non ho citato? Mi piacerebbe sapere quali si sono guadagnati un posto fisso nella tua configurazione e quali messaggi di errore ti hanno mandato alla ricerca. Le correzioni sono benvenute: questo articolo viene aggiornato quando gli strumenti cambiano, e a giudicare da quest’anno succederà spesso.
Informativa: Nessuna azienda citata in questo articolo lo ha sponsorizzato, revisionato o approvato, e non contiene link affiliati. I prodotti sono nominati solo nel testo; le immagini usano i miei loghi.
Ultimo aggiornamento: 15 novembre 2026.



