Agent Skills 101: trovare, gestire e organizzare le skills del tuo ambiente agent

Testato il: 2026-09-12 Ambiente: Node.js 24.15.0 · skills CLI 1.5.18 · opencode (plugin @hueyexe/opencode-ensemble 0.16.0)

Prerequisiti

• Node.js versione 18 o superiore, con npx incluso (verificato su Node 24.15.0)
• Un ambiente agent che supporti le skills. Questa guida usa opencode, ma il formato SKILL.md è uno standard aperto (nato in Anthropic, poi rilasciato come standard open) e funziona allo stesso modo su Claude Code, Codex, Cursor e altri
• Git se vuoi installare skills da repository GitHub locali
• Accesso a internet per i comandi che interrogano skills.sh

La CLI skills si esegue con npx, senza installazione globale. Al primo uso scarica il pacchetto, poi lo mette in cache: la prima esecuzione è più lenta delle successive.

1. Inventario: capire dove vivono le skills

Le skills non sono un unico elenco: il loro posto dipende dallo scope. I livelli sono due, e un ambiente reale li usa entrambi.

Parti dall'inventario. Nella directory del tuo progetto:

npx skills list

Risultato atteso: l'elenco delle skills installate a livello progetto, con la directory in cui vivono e gli agent a cui sono collegate. In un ambiente opencode con ghost-lexical e opencode-ensemble installate in .agents/skills/, l'output è:

Project Skills

ghost-lexical    ./.agents/skills/ghost-lexical    Agents: Codex, GitHub Copilot, OpenCode
opencode-ensemble ./.agents/skills/opencode-ensemble Agents: Codex, GitHub Copilot, OpenCode

Poi le skills globali:

npx skills ls -g

Risultato atteso: le skills installate a livello utente. Nell'ambiente di test c'è solo find-skills, la skill che guida la scoperta di altre skills:

Global Skills

find-skills    ~/.agents/skills/find-skills    Agents: Codex, GitHub Copilot, OpenCode

Ora guarda il filesystem con gli occhi dell'agente. Un ambiente opencode tipico dichiara tre posizioni:

ls .opencode/skills/
ls .agents/skills/
ls ~/.agents/skills/

Risultato atteso: tre elenchi, ciascuno con una o più directory. Ogni directory che contiene un file SKILL.md è una skill. In questo repo, .opencode/skills/ contiene le skill editoriali (content-writing, seo-metadata, firefly-prompts), .agents/skills/ le skill operative (ghost-lexical, opencode-ensemble) e ~/.agents/skills/ la skill find-skills.

2. Trovare una skill

Prima di cercare, fai una domanda precisa: non “una skill per il web” ma “una skill per il performance tuning di React”. La ricerca per parole chiave:

npx skills find typescript

Risultato atteso: una lista di skills con nome, autore, numero di installazioni e link alla pagina skills.sh. Ecco l'output reale della ricerca per typescript:

wshobson/agents@typescript-advanced-types    74.1K installs
└ https://skills.sh/wshobson/agents/typescript-advanced-types

github/awesome-copilot@javascript-typescript-jest    12.7K installs
└ https://skills.sh/github/awesome-copilot/javascript-typescript-jest

github/awesome-copilot@typescript-mcp-server-generator    12K installs
└ https://skills.sh/github/awesome-copilot/typescript-mcp-server-generator

sickn33/agentic-awesome-skills@typescript-expert    12K installs
└ https://skills.sh/sickn33/agentic-awesome-skills/typescript-expert

jeffallan/claude-skills@typescript-pro    8.4K installs
└ https://skills.sh/jeffallan/claude-skills/typescript-pro

Senza argomento, npx skills find avvia una ricerca interattiva in stile fzf.

Verifica la qualità prima di installare. Il numero di installazioni non basta. Guarda tre cose:

1. Install count: preferisci skill con oltre 1.000 installazioni, diffida di quelle sotto le 100
2. Fonte: i repository ufficiali (anthropics/skills, vercel-labs/agent-skills, microsoft/skills) sono più affidabili degli autori sconosciuti
3. Stelle GitHub del repository sorgente: sotto le 100 stelle, tratta la skill con sospetto

Il leaderboard su skills.sh mostra le skill più installate per dominio: è il primo posto da guardare quando non sai da dove partire.

3. Installare una skill

Prima di installare, guarda cosa contiene un repository senza toccare nulla:

npx skills add vercel-labs/agent-skills --list

Risultato atteso: l'elenco delle skills disponibili in quel repository (vercel-labs/agent-skills ne contiene 9, tra cui vercel-composition-patterns e web-design-guidelines). Nessun file viene scritto: è una lista, non un'installazione.

Per installare una singola skill di un repository su un agente preciso:

npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a opencode

Risultato atteso: la CLI scarica la skill e crea il collegamento per l'agente indicato. In modalità interattiva chiede conferma e ti fa scegliere tra due metodi di installazione:

Per saltare i prompt (utile nei CI/CD):

npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a opencode -y

I flag importanti:

Dopo l'installazione, il lockfile. La CLI tiene traccia della provenienza delle skills in un file skills-lock.json alla radice del progetto, con l'hash di ogni skill installata. In questo repo:

{
  "version": 1,
  "skills": {
    "ghost-lexical": {
      "source": "perezd/ghost-writer",
      "sourceType": "github",
      "skillPath": "skills/ghost-lexical/SKILL.md",
      "computedHash": "061b01e809b024d108f31298d26ea85f3c2706011a1393682c243ca971b0ab04"
    },
    "opencode-ensemble": {
      "source": "hueyexe/opencode-ensemble",
      "sourceType": "github",
      "skillPath": "skills/opencode-ensemble/SKILL.md",
      "computedHash": "00a4f12864f4156c8fd3edd36ef6d97a04a702ff2c1b49e37c363d768ee6e227"
    }
  }
}

Questo file va committato: è ciò che permette di tracciare le versioni e aggiornarle in modo riproducibile.

4. Ispezionare e capire un SKILL.md

Ogni skill è una directory con un file SKILL.md obbligatorio e, opzionalmente, script e documentazione di supporto. Leggine una per capire la struttura:

cat ~/.agents/skills/find-skills/SKILL.md

Risultato atteso: un file che inizia con frontmatter YAML delimitato da --- e continua con istruzioni in markdown. Il frontmatter ha due campi, ed è la parte più importante dell'intero file:

---
name: find-skills
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
---

Il meccanismo è la progressive disclosure, in due livelli:

1. Frontmatter (name + description): caricato nel contesto all'avvio della sessione. Serve all'agente per sapere che la skill esiste e quando usarla
2. Corpo markdown: caricato solo quando l'agente decide che la skill è rilevante per il task corrente

Il corpo può referenziare file aggiuntivi (references/, scripts/) che vengono letti solo al bisogno: così una skill con decine di file di riferimento costa zero token finché non serve.

La struttura canonica di una skill è:

my-skill/
├── SKILL.md          (obbligatorio: frontmatter + istruzioni)
├── references/       (opzionale: documentazione caricata su richiesta)
└── scripts/          (opzionale: script eseguiti, non caricati nel contesto)

5. Aggiornare e rimuovere

Le skills cambiano. Controlla se ce ne sono di più recenti:

npx skills check

Risultato atteso: la CLI verifica le sorgenti registrate nel lockfile e aggiorna le skills. Attenzione a un dettaglio della versione 1.5.18: check non solo verifica, ma aggiorna. Se una sorgente non risponde, lo segnala senza bloccare il resto:

Checking for skill updates…

Updating for: Universal, Claude Code
Refreshing 2 skill(s)…

✗ Failed to check for deleted skills from perezd/ghost-writer
Updating ghost-lexical…
  ✓ Updated ghost-lexical
✗ Failed to check for deleted skills from hueyexe/opencode-ensemble
Updating opencode-ensemble…
  ✓ Updated opencode-ensemble

✓ Updated 2 skill(s)

Per aggiornare in modo esplicito, con controllo sullo scope:

npx skills update          # aggiorna tutto, con prompt sullo scope
npx skills update -g       # solo le skills globali
npx skills update -p       # solo le skills di progetto
npx skills update -y       # non interattivo (auto-detects scope)

Per togliere una skill:

npx skills remove web-design-guidelines

Risultato atteso: la skill viene rimossa dagli agent indicati e scompare da npx skills list. Il file skills-lock.json viene aggiornato di conseguenza.

6. Scrivere la tua prima skill

Se la ricerca non trova nulla di adatto, scrivi la tua. La CLI genera il template:

npx skills init my-test-skill

Risultato atteso:

Initialized skill: my-test-skill

Created:
  my-test-skill/SKILL.md

Next steps:
  1. Edit my-test-skill/SKILL.md to define your skill instructions

Il template generato è questo:

---
name: my-test-skill
description: A brief description of what this skill does
---

# my-test-skill

Instructions for the agent to follow when this skill is activated.

## When to use

Describe when this skill should be used.

## Instructions

1. First step
2. Second step
3. Additional steps as needed

Le regole per una skill che funziona davvero:

1. description al primo posto: metti il caso d'uso chiave all'inizio della frase, perché molti ambienti troncano le descrizioni lunghe nel listing
2. Skill focalizzata: due o tre istruzioni precise battono una documentazione enciclopedica. I benchmark sulle skills (SkillsBench) mostrano che le skills “comprehensive” peggiorano le prestazioni rispetto a quelle compatte
3. Mantieni SKILL.md sotto le 500 righe: la documentazione dettagliata va in references/, caricata solo al bisogno
4. Dai voce a un parere: “quando NON usare questa skill” è informazione tanto preziosa quanto il “quando usarla”

Verifica

Esegui la checklist finale per confermare che l'ambiente è a posto:

npx skills --version
npx skills list
npx skills ls -g
cat skills-lock.json

Risultato atteso:

1. npx skills --version stampa la versione della CLI (nell'ambiente di test: 1.5.18)
2. npx skills list mostra le skills di progetto, con directory e agent collegati
3. npx skills ls -g mostra le skills globali
4. skills-lock.json esiste, è valido come JSON e contiene una voce per ogni skill installata, con source, sourceType, skillPath e computedHash

Se tutti e quattro i punti tornano, il tuo ambiente agent è configurato: le skills sono nel posto giusto, tracciabili e aggiornabili. Il test finale è comportamentale: chiedi al tuo agente di fare qualcosa che richiede una delle skill installate (per esempio “trova una skill per X”) e verifica che la carichi.

Limiti noti

• La CLI skills è in evoluzione rapida: i flag documentati qui sono quelli verificati sulla 1.5.18, ma l'ecosistema (vercel-labs/skills) rilascia spesso versioni nuove. Verifica con npx skills --version prima di usare comandi non coperti da questa guida
• La discovery delle skills dipende dalla piattaforma: npx skills list non mostra le skills che l'agente scopre da directory proprietarie come .opencode/skills/. L'inventario completo richiede sempre uno sguardo al filesystem, non solo alla CLI
• Installare una skill significa dare istruzioni eseguibili al tuo agente: installa solo da fonti che controlli o di cui ti fidi. Una skill malevola può indirizzare il comportamento dell'agente quanto un prompt injection
• Le skills non sono la memoria dell'agente: sono procedure. Per fatti e conoscenze di dominio serve altro (AGENTS.md, documentazione di progetto, tool), non una skill gonfiata