# Come creare le Skill di Claude: guida completa in italiano (aggiornata al 2026)

3 novembre 2026 · Alessandro Caprai, Divulgatore, formatore e consulente AI

<https://caprai.dev/it/vibe-coding/post/come-creare-skill-claude-guida-completa>

---

Ho scritto la prima versione di questa guida quando le Skill erano appena uscite. Da allora sono diventate lo standard per insegnare a Claude e in generale agli LLMs di frontiera un lavoro ripetibile. Questa è la guida aggiornata, con quello che è conta davvero per costruire una Skill che funzioni.

> **In breve.** Una Skill è una cartella con un file `SKILL.md`: istruzioni, esempi ed eventuali script che Claude carica solo quando servono. Nel 2026 le Skill sono uscite dalla beta sull'API, sono diventate uno standard aperto e in Claude Code hanno assorbito gli slash command, con argomenti, esecuzione in un subagente e strumenti per misurarne l'efficacia.

## Come funzionano, in trenta secondi

Il principio è la **progressive disclosure**, il caricamento a strati di cui ho parlato nell'[articolo sui file .md di Claude Code](/it/vibe-coding/post/progressive-disclosure-l-architettura-a-strati-che-rivoluziona-l-efficienza-di-claude-code-con-i-file-md):

1. all'avvio Claude vede solo nome e descrizione di ogni Skill;
2. quando la richiesta corrisponde alla descrizione, legge il corpo di `SKILL.md`;
3. i file di riferimento li apre solo se il compito li richiede, e gli script li esegue senza caricarli nel contesto.

Per questo puoi avere decine di Skill installate senza riempire la finestra di contesto: paghi solo quelle che usi.

## «Skills 2.0»: che cosa è cambiato davvero

In rete circola il nome «Skills 2.0», ma Anthropic non ha pubblicato una versione 2 ufficiale. È la somma di aggiornamenti arrivati nel corso del 2026:

- **Fine della beta sull'API** (19 agosto 2026): Agent Skills e la Skills API (`/v1/skills`) non richiedono più l'header `skills-2025-10-02`; dagli SDK di fine agosto si usa `client.skills` invece di `client.beta.skills`.
- **Skill dai repository**: le sessioni di Claude Managed Agents scoprono da sole le Skill nella cartella `.claude/skills` di un repository GitHub montato.
- **Skill e slash command unificati** in Claude Code: `.claude/commands/deploy.md` e `.claude/skills/deploy/SKILL.md` creano lo stesso comando `/deploy`, ma la Skill aggiunge file di supporto, controllo dell'invocazione e caricamento automatico.
- **Molti nuovi campi del frontmatter** in Claude Code: argomenti, modello, effort, esecuzione in un subagente, percorsi.
- **Ricarica a caldo**: le modifiche a una Skill valgono subito, senza riavviare la sessione.
- **Misurazione**: valutazioni con il plugin `skill-creator`, `claude plugin eval` e il report `/skill-doctor` su costo e utilizzo di ogni Skill.

## Anatomia di una Skill

```text
revisione-articolo/
├── SKILL.md          obbligatorio: frontmatter e istruzioni
├── checklist.md      riferimento, letto solo quando serve
└── scripts/
    └── conta.py      eseguito, non caricato nel contesto
```

Il file deve iniziare con `---` alla prima riga. La documentazione consiglia di restare sotto le 500 righe e di spostare i dettagli nei file di riferimento, citandoli dal corpo:

```markdown
---
name: revisione-articolo
description: Rivede la bozza di un articolo del blog prima della pubblicazione. Usala quando l'utente chiede di rivedere, controllare o preparare un articolo da pubblicare.
when_to_use: Frasi come "rivedi l'articolo", "è pronto da pubblicare?", "controlla la bozza".
allowed-tools: Read Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/conta.py *)
---

# Revisione di un articolo

1. Leggi la bozza indicata dall'utente.
2. Calcola il tempo di lettura con `python3 ${CLAUDE_SKILL_DIR}/scripts/conta.py <file>`.
3. Controlla la bozza con [checklist.md](checklist.md).
4. Restituisci un elenco di correzioni, dalla più importante.
```

## Il frontmatter: due insiemi di campi

Qui sta la trappola più frequente. Lo **standard aperto** Agent Skills prevede sei campi, gli unici accettati su claude.ai e dall'API: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`. Un campo in più, fuori da Claude Code, produce un errore di validazione.

**Claude Code** ne accetta molti altri; i più utili:

- `description` e `when_to_use`: sono ciò che Claude legge per decidere se usare la Skill. Insieme vengono troncati a 1.536 caratteri, quindi il caso d'uso principale va scritto per primo.
- `disable-model-invocation: true`: solo tu puoi avviarla con `/nome`, e la descrizione non occupa contesto. Obbligatorio per tutto ciò che ha effetti, come deploy e commit.
- `user-invocable: false`: il contrario, la Skill sparisce dal menu `/` e la usa solo Claude.
- `argument-hint` e `arguments`: suggerimenti e nomi per gli argomenti.
- `model` ed `effort`: modello e livello di ragionamento per quel turno.
- `context: fork` e `agent`: esecuzione in un subagente isolato.
- `paths`: limita il caricamento automatico ai file che corrispondono a un glob.
- `disallowed-tools`: strumenti tolti mentre la Skill è attiva.

Se la Skill deve funzionare ovunque, scrivila con i sei campi standard e aggiungi quelli di Claude Code solo nella copia che usi lì.

## Argomenti, script e contesto dinamico

Una Skill invocata a mano riceve gli argomenti in `$ARGUMENTS`, oppure per posizione (`$0`, `$1`) o per nome:

```markdown
---
name: deploy
description: Pubblica l'applicazione in produzione
disable-model-invocation: true
arguments: [ambiente]
---
Pubblica in $ambiente:
1. Esegui i test
2. Crea la build
3. Pubblica e verifica che il sito risponda
```

`${CLAUDE_SKILL_DIR}` punta alla cartella della Skill e rende portabili i percorsi degli script. La sintassi `` !`comando` `` esegue un comando **prima** che Claude legga la Skill e ne inserisce l'output nel testo: utile per dare a Claude dati freschi, come il diff corrente. Se il comando fallisce, la Skill non parte; i comandi rispettano le regole di permesso, e `allowed-tools` li approva in anticipo.

## Skill che lavorano da sole: `context: fork`

Con `context: fork` la Skill gira in un **subagente**, senza la cronologia della conversazione, e ti restituisce solo il risultato. Va usata per compiti espliciti; una Skill fatta solo di linee guida, in un subagente, non produce nulla.

```markdown
---
name: riassunto-pr
description: Riassume le modifiche di una pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## Contesto
- Diff: !`gh pr diff`
- File modificati: !`gh pr diff --name-only`

## Compito
Riassumi le modifiche, i rischi e cosa testare.
```

Per impostazione predefinita il subagente lavora in background; con `background: false` la risposta arriva nello stesso turno.

## Dove metterle

- `~/.claude/skills/<nome>/`: personali, valgono in tutti i tuoi progetti.
- `.claude/skills/<nome>/` nel repository: del progetto, si versionano e arrivano a tutto il team.
- Dentro un **plugin**: si invocano come `/plugin:skill` e non vanno in conflitto con le altre.
- Su **claude.ai**: le Skill abilitate sul tuo account vengono sincronizzate anche in Claude Code, in `~/.claude/skills/synced/`.

Per installare Skill pubblicate da altri, su più agenti, c'è la CLI aperta `skills`:

```bash
npx skills add https://github.com/coreyhaines31/marketingskills --skill ai-seo --agent claude-code --copy
```

Crea anche un file `skills-lock.json` con l'origine e l'impronta della versione installata. Il messaggio finale della CLI ricorda la regola più importante: le Skill girano con tutti i permessi dell'agente. Io, prima di installarne una, la scarico in una cartella separata e leggo tutto, `SKILL.md`, riferimenti e script.

## Misurare se una Skill funziona

Una Skill vale qualcosa solo se Claude la usa sulle richieste giuste e il risultato migliora. Il metodo consigliato è il **confronto con la baseline**:

1. scegli alcune richieste realistiche;
2. eseguile in **sessioni nuove** con la Skill attiva e poi disattivata (`"skillOverrides": { "nome": "off" }`);
3. confronta i risultati. Le sessioni devono essere nuove, perché il contesto rimasto dalla creazione nasconderebbe i difetti delle istruzioni.

Il plugin `skill-creator` automatizza il ciclo: salva i casi di prova in `evals/evals.json`, lancia un subagente per ogni caso e registra token e tempi.

```text
/plugin install skill-creator@claude-plugins-official
```

Per le Skill dentro un plugin c'è `claude plugin eval`, che può fare da controllo in CI. `/skill-doctor` mostra infine quanto costa ogni Skill nel contesto e quante volte viene usata: è il modo più rapido per scoprire quelle che non servono.

## Gli errori più comuni

- **Descrizione vaga**: «aiuta con i documenti» non si attiva mai, o si attiva sempre. Scrivi cosa fa e con quali frasi l'utente la chiede.
- **Tutto nel** `SKILL.md`: oltre le 500 righe sposta i dettagli nei riferimenti.
- **Effetti senza protezione**: deploy, commit e invii vanno con `disable-model-invocation: true`.
- **Campi di Claude Code caricati su claude.ai**: l'upload fallisce, usa i sei campi standard.
- **Skill di terzi installate senza leggerle**: sono istruzioni che eseguirai con i tuoi permessi.

## Domande frequenti

**Skill o slash command**?Per il lavoro nuovo, Skill: fanno tutto ciò che fa un comando, più file di supporto e caricamento automatico. I comandi esistenti continuano a funzionare.

**Skill o server MCP**?Si completano. MCP collega Claude a strumenti e dati; la Skill gli insegna come usarli in un processo preciso.

**Funzionano anche su claude.ai e via API**?Sì, con il frontmatter standard. Sull'API sono stabili dall'agosto 2026.

## In sintesi

Le Skill sono il modo più economico di trasformare un'abitudine in un processo: una cartella, un file Markdown e, quando serve, uno script. Nel 2026 sono diventate misurabili, ed è questa la novità che conta: una Skill che non migliora i risultati in un confronto con la baseline va riscritta o tolta. Se vuoi portare questo metodo nel tuo team, ne parliamo nei percorsi di [formazione per le aziende](/it/aziende).
