> ## Content Index
> Fetch the complete content index at: https://adrianoamalfi.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Agent Skills 101: trovare, gestire e organizzare le skills del tuo ambiente agent
- URL: https://adrianoamalfi.com/tech-scratchpad/agent-skills-101/
- Published: 2026-09-12T18:43:37.000Z
- Updated: 2026-09-28T12:12:10.000Z
- Description: Skills come pacchetti di istruzioni per agenti AI: come trovarle, installarle, organizzarle e scriverle con la CLI npx skills.
- Author: Adriano Amalfi
- Tags: AI Agentica, Scratchpad, AI Tools, OpenCode, #Tech Scratchpad: Appunti avanzati e esperimenti per esperti e amatoriali

**Testato il:** 2026-09-12 **Ambiente:** Node.js 24.15.0 · skills CLI 1.5.18 · opencode (plugin [@hueyexe/opencode-ensemble](https://adrianoamalfi.com/opencode-ensemble-guida/) 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.

| Scope    | Flag      | Directory tipica                         | Uso                                             |
| -------- | --------- | ---------------------------------------- | ----------------------------------------------- |
| Progetto | (default) | .opencode/skills/ oppure .agents/skills/ | Committata nel repo, condivisa col team         |
| Globale  | \-g       | \~/.agents/skills/                       | Disponibile su tutti i progetti dell'utente |

Parti dall'inventario. Nella directory del tuo progetto:

```bash
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 è:

```text
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:

```bash
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:

```text
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:

```bash
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`.

Gotcha: la CLI non vede tutte le posizioni — \`npx skills list\` ha mostrato solo le skills in \`.agents/skills/\`, non quelle in \`.opencode/skills/\`: alcune piattaforme (come opencode) scoprono le skills da directory proprietarie all'avvio, e la CLI le vede solo se l'installazione è passata da \`npx skills add\`.

## 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:

```bash
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`:

```text
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](https://skills.sh/?ref=adrianoamalfi.com) 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:

```bash
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:

```bash
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:

| Metodo                    | Comportamento                                        | Quando usarlo                                  |
| ------------------------- | ---------------------------------------------------- | ---------------------------------------------- |
| **Symlink** (consigliato) | Crea collegamenti simbolici verso una copia canonica | Una sola fonte di verità, aggiornamenti facili |
| **Copy**                  | Copie indipendenti per ogni agente                   | Quando l'agente non supporta i symlink     |

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

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

I flag importanti:

| Flag          | Effetto                                                            |
| ------------- | ------------------------------------------------------------------ |
| \-g, --global | Installa nella directory utente invece che nel progetto            |
| \-a, --agent  | Indica l'agente di destinazione (es. opencode, claude-code)    |
| \-s, --skill  | Installa una skill specifica per nome (usa '\*' per tutte) |
| \-l, --list   | Elenca le skill del repository senza installare                    |
| \-y, --yes    | Salta tutte le conferme                                            |
| \--copy       | Copia i file invece di creare symlink                              |

**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:

```json
{
  "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:

```bash
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:

```markdown
---
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

La description è il trigger — Se la \`description\` non dice con precisione \*quando\* usare la skill, l'agente non la caricherà mai.

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 è:

```text
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:

```bash
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:

```text
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)
```

Gotcha: il warning sulle sorgenti non è un errore — “Failed to check for deleted skills” non è un errore dell'installazione locale. Significa solo che il repository sorgente non ha risposto alla richiesta di confronto con l'elenco remoto: l'aggiornamento della skill avviene comunque.

Per aggiornare in modo esplicito, con controllo sullo scope:

```bash
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:

```bash
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:

```bash
npx skills init my-test-skill
```

**Risultato atteso:**

```text
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:

```markdown
---
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](https://adrianoamalfi.com/skills-vs-agents-md/)
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:

```bash
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](https://adrianoamalfi.com/wikiskill-wiki-non-memoria-agente/): sono procedure. Per fatti e conoscenze di dominio serve altro (AGENTS.md, documentazione di progetto, tool), non una skill gonfiata