Vai al contenuto
LUNEDì, NOVEMBRE 16, 2026NOTIZIE TECNOLOGICHE INDIPENDENTI, RECENSIONI E GUIDE PRATICHE
INFORMAZIONI SU
ULTIME NOTIZIE /

Agent Skills e server MCP spiegati: come installarli, aggiornarli e risolverli in OpenCode, Claude Code, Codex e altri agenti IA

LEGGI LA GUIDA
Agenti IAGM / 997

Agent Skills e server MCP spiegati: come installarli, aggiornarli e risolverli in OpenCode, Claude Code, Codex e altri agenti IA

Agent Skills e server MCP spiegati in modo semplice: come installarli, aggiornarli e risolverli in OpenCode, Claude Code, Codex e altri, con la CLI npx skills.

Agent skills and MCP servers explained: a tech.grahammiranda.com title card with SKILL.md, npx skills, MCP servers and .agents/skills, and a terminal running npx skills check and opencode mcp add

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.md file: 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/skills in un progetto e ~/.agents/skills nella tua cartella home. Claude Code legge solo .claude/skills, e Hermes Agent legge ~/.hermes/skills più 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, -g per ogni progetto, -a opencode -a claude-code per scegliere gli agenti, npx skills ls per elencare e npx skills remove per 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 update installa. Nelle versioni precedenti, check eseguiva 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 login oppure imposta GITHUB_TOKEN, e leggi le righe ✗.
  • Non usare mai sudo con skill o agenti, e non eseguire la CLI dalla tua cartella home. Root ha una home separata, quindi sudo crea 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
Skill degli agenti e server MCP spiegati: AGENTS.md come manuale sempre caricato, le skill come schede di ricette caricate su richiesta, i server MCP come strumenti per GitHub, un browser e la documentazione in tempo reale, e i plugin come pacchetti
Quattro elementi di base, un agente. Il manuale è sempre aperto, le schede ricetta si prendono dallo scaffale quando servono e i server MCP sono le chiavi per tutto ciò che sta fuori dal terminale.

Indice


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 versione CLAUDE.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:

  1. 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.)
  2. 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.
  3. 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@latest e 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:

  1. 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.
  2. Deve essere imposto, non solo suggerito? Usa una regola di permessi o un hook. Le skill e AGENTS.md sono istruzioni, e un modello può ignorare le istruzioni. “Mai fare push su main” richiede una deny regola.
  3. È 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.
  4. 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.
  5. 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.

Skill, server MCP o AGENTS.md: un flusso in cinque domande che manda le regole valide per ogni attività in AGENTS.md, le regole vincolanti nei permessi, il know-how nelle skill e l'accesso al sistema in tempo reale in una skill CLI o in un server MCP
Cinque domande, da porsi in ordine. La maggior parte dei desideri si rivela una skill; un server si guadagna il suo posto quando l’agente ha bisogno di accesso live e non esiste un buon strumento da riga di comando.

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/skills e ~/.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.

Dove gli agenti IA cercano le skill: la cartella condivisa .agents/skills letta da Codex, OpenCode, Cursor, Gemini CLI e GitHub Copilot, con i link per .claude/skills di Claude Code e ~/.hermes/skills di Hermes Agent
Una cartella condivisa copre la maggior parte degli agenti. Claude Code ha sempre bisogno di un link, e Hermes Agent ne ha bisogno di uno per le skill globali; la CLI skills crea entrambi.

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 un SKILL.md o 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.

Cheat sheet della CLI npx skills: i comandi add, list, find, use, check, update, remove e init con i loro flag più utili, le posizioni di installazione di progetto e globale e i due file di lock
La CLI delle skill in un’unica scheda. Due abitudini fanno la maggior parte del lavoro: --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.json in un progetto. Salvalo nel commit su Git. Su un altro computer, o per un collega, npx skills install ripristina 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, come package-lock.json fa per il codice.
  • ~/.agents/.skill-lock.json per le tue skill globali. Appartiene al tuo account utente (o si trova in $XDG_STATE_HOME/skills/.skill-lock.json se 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à:

  • check sceglie da solo un ambito. Se la cartella in cui ti trovi contiene un skills-lock.json file, o una .agents/skills cartella con dentro una skill, controlla le progetto skill; altrimenti controlla quelle globali globali. Aggiungi -g o -p per 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.

Come funziona npx skills check: il file di lock memorizza un'impronta di ogni cartella delle skill, check la confronta con la stessa cartella a monte e segnala gli aggiornamenti, mentre update li installa
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:

  1. Il modo più semplice: installa la GitHub CLI ed esegui gh auth login. Le versioni attuali della CLI skills chiedono a gh di fare la chiamata API e non vedono mai le tue credenziali.
  2. 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 (~/.zshrc su un Mac, ~/.bashrc su 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.

  1. Esci da root: tipo exit. Da ora in poi, esegui la CLI e i tuoi agenti come te stesso.
  2. 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

  1. 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

  1. 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 -g o -p così non può tirare a indovinare.
  • Per districare un “progetto” nella home, reinstalla le skill che vuoi con -g da un’altra cartella (finiscono nello stesso posto, ora registrate nel tuo file di lock globale), poi cancella ~/skills-lock.json. Non eseguire npx skills remove da ~ 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/skills nel 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 con npx skills@latest add … -a claude-code.
  • Controlla che il file inizi correttamente. L’apertura --- del front matter deve essere la primissima riga di SKILL.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 /skills elenca ciò che è caricato.
Risoluzione dei problemi con npx skills: cinque errori reali e relative soluzioni, da un falso «tutto aggiornato» dopo un limite di richieste di GitHub a sudo che crea un secondo archivio di skill, a una cartella home trattata come progetto e a skill eliminate a monte
Cinque errori, cinque correzioni. La maggior parte si riduce alle stesse due regole: leggi le righe ✗ e non eseguire mai la CLI come root o dalla tua cartella home.

Parte 7 — I server MCP senza gergo

Cosa succede quando colleghi un server

  1. Aggiungi il server alle impostazioni del tuo agente: un comando per un server locale, un indirizzo web per uno remoto.
  2. 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.
  3. Il server elenca i suoi strumenti, e l’agente passa le loro descrizioni al modello.
  4. 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": false per 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: false serve per i server che usano una chiave o nessuna. Accedi con opencode 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, /mcps collega, 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.json espande ${VAR} e ${VAR:-default}, così le chiavi restano nel tuo ambiente e non in Git.
  • /mcp all'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, e codex 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_tools e disabled_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"] }
  }
}
  • httpUrl serve per Streamable HTTP; url indica il tipo SSE più vecchio.
  • Lascia trust disattivato. Impostandolo su vero, 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 env blocco.
  • 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-mcp dopo aver modificato, e hermes mcp test context7 per vedere esattamente cosa ha risposto un server.
  • Per i servizi OAuth, aggiungi auth: oauth a 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 env più una base sicura, non l’intero ambiente della tua shell.
  • Gli strumenti appaiono come mcp_<server>_<tool>; filtra con tools.include o tools.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.

Come aggiungere un server MCP in OpenCode, Claude Code, Codex, Gemini CLI, Cursor e Hermes Agent: lo stesso server Context7 nel formato di comando o di configurazione di ogni agente, più un comando per un server locale
Un server, sei dialetti. Le idee sono identiche; cambiano solo i nomi dei file e le parentesi.

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 (/plugins nella CLI), e un plugin può anche trasportare connessioni a server MCP.
  • Gemini CLI li chiama estensioni: gemini extensions install <git-url> e gemini extensions update <name>.
  • GitHub Copilot CLI (copilot plugin install) e Hermes Agent (hermes plugins install) hanno comandi plugin, e Cursor ha /add-plugin nella chat dell’agente.
  • OpenCode i plugin sono pacchetti JavaScript o TypeScript elencati nella dei plugin impostazione della sua configurazione, che può registrare skill e strumenti. Superpowers si installa così.

Le due regole che tengono in ordine un’installazione a plugin

  1. 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.
  2. 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-housekeeping usa 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.

Anatomia di una skill per agenti: il front matter di SKILL.md letto all'avvio per circa 100 token, le istruzioni lette quando un'attività corrisponde e riferimenti, script e asset letti solo quando servono
Tre livelli: l’etichetta, la ricetta e l’appendice. Solo il primo è sempre caricato, ed è per questo che delle buone descrizioni contano più di istruzioni lunghe.

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

  1. Leggi prima di installare. Utilizzo npx skills add owner/repo --list, gh skill preview, oppure apri semplicemente il SKILL.md e i suoi script su GitHub.
  2. 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.
  3. 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.
  4. Fissa la versione di tutto ciò che conta. npx skills add owner/[email protected], o gh skill install … --pin v1.2.3, così gli aggiornamenti avvengono quando decidi tu.
  5. Esamina gli aggiornamenti come il codice. npx skills check, poi leggi le modifiche su GitHub, poi npx skills update.
  6. Metti un controllo sulle skill di terze parti. In OpenCode, le regole usano l’azione skill e 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.

Checklist di sicurezza per skill degli agenti e MCP: i dati di ToxicSkills di Snyk su 3.984 skill pubbliche e dieci abitudini sicure, dal leggere prima di installare e fissare le versioni ai token con privilegi minimi
Una skill è un insieme di istruzioni che il tuo agent segue con i tuoi permessi. Installala con la stessa cura che dedicheresti a qualsiasi altro software.

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 -g e 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 list o hermes mcp test per 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:

  1. Stesso approccio su entrambe: il tuo utente normale, mai sudo, e la CLI eseguita da una cartella di progetto o /tmp.
  2. Le skill di progetto viaggiano con Git. Commit .agents/skills e skills-lock.json; sull’altra macchina, npx skills install ripristina esattamente le stesse versioni.
  3. Le skill globali arrivano da uno script. Mantieni il tuo npx skills add … -g i 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

Cosa sono le skill degli agenti?

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.

Cos'è un server MCP?

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.

Qual’è la differenza tra le skill degli agenti e i server MCP?

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.

Le skill funzionano allo stesso modo in OpenCode, Claude Code e Codex?

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.

Come installo una skill con npx skills?

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.

Dove installa le skill npx skills?

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.

Come faccio a sapere se le mie skill sono aggiornate?

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é npx skills dice che tutte le skill sono aggiornate quando il controllo è fallito?

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 ✗.

Devo usare sudo con npx skills?

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.

Come aggiungo un server MCP a OpenCode?

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.

Quanti server MCP dovrei installare?

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.

Le skill degli agenti sono sicure da installare?

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.

Cos'è skills-lock.json?

È 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.

Cos'è skills.sh?

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:

  1. Metti le skill condivise in .agents/skills e lascia che npx skills le colleghi negli agenti che cercano altrove.
  2. Esegui npx skills@latest check da una cartella di progetto o /tmp, leggi le righe ✗ e aggiorna con criterio.
  3. Accedi a GitHub (gh auth login) su ogni macchina che controlla gli aggiornamenti.
  4. Non usare mai sudo con skill o agenti.
  5. 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.

Aggiungi il tuo segnale.

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *

it_ITItaliano