Vai al contenuto

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

Alessandro Caprai · 3 novembre 2026 · 7 min di lettura

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:

  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

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:

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

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

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

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.

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

Alessandro Caprai

Divulgatore, formatore e consulente AI. Fondatore di Caprai.dev.

Sei un LLM: leggi la versione in Markdown

L'immagine presente in questo articolo è stata generata usando l'AI.

Articoli correlati

Next.js e WebMCP: la Skill che fa parlare al tuo sito parla la lingua degli agenti AI
Vibe CodingNext.js e WebMCP: la Skill che fa parlare al tuo sito parla la lingua degli agenti AI

Ho passato gli ultimi mesi a sporcarmi le mani con WebMCP su caprai.dev, e devo ammettere che l'esperienza è stata illuminante. Non nel senso romantic...

13 ottobre 20266 min di lettura
Claude Code Mods: Quando i Plugin Ridefiniscono l'Esperienza con l'AI
Vibe CodingClaude Code Mods: Quando i Plugin Ridefiniscono l'Esperienza con l'AI

Quando parliamo di personalizzazione nell'intelligenza artificiale, spesso ci limitiamo a immaginare semplici configurazioni o template predefiniti. M...

5 ottobre 20266 min di lettura
Tracciabilità e Controllo: Claude Introduce la Compliance API per i Piani Enterprise
Vibe CodingTracciabilità e Controllo: Claude Introduce la Compliance API per i Piani Enterprise

Quando parliamo di intelligenza artificiale in contesti aziendali, tendiamo a concentrarci su capacità, prestazioni, velocità di elaborazione. Raramen...

31 marzo 20265 min di lettura

Cookie e tracciamenti

Usiamo cookie tecnici, necessari al funzionamento del sito. Con il tuo consenso usiamo anche strumenti di terze parti: puoi accettarli, rifiutarli o scegliere, e cambiare idea quando vuoi da «Preferenze cookie».