Tutorial Claude Skills: Crea il Tuo Primo SKILL.md in 10 Minuti (2026)

Tutorial Claude Skills: Crea il Tuo Primo SKILL.md in 10 Minuti (2026)

Gli skill sono la funzionalità di Claude Code più importante che probabilmente non stai ancora usando. Un Claude skill è una cartella con un file SKILL.md che Claude carica automaticamente nel momento in cui il tuo prompt corrisponde alla sua descrizione — niente copia-incolla di prompt, niente CLAUDE.md gonfio, niente da ricordare su quale template usare. Abbiamo pubblicato 4 skill nella cartella .claude/skills/agent/ di questo repo, e con Skills 2.0 e il Marketplace di Anthropic in arrivo all'inizio del 2026, il formato ha finalmente raggiunto la sua maturità. Ecco il pattern che funziona davvero, dopo aver incontrato tutti i problemi del caso.

Punti chiave

• Un Claude skill è una cartella che contiene un file SKILL.md con frontmatter YAML che Claude carica automaticamente quando è rilevante.
• Gli skill si trovano in ~/.claude/skills/ (personali) o .claude/skills/ (di progetto) — Claude scansiona entrambe le posizioni all'avvio.
• Usa gli Skill per i workflow ripetibili; usa MCP per dati esterni in tempo reale; usa i subagent per la pianificazione multi-step; usa gli hook per eventi deterministici.
• Il percorso più rapido per il tuo primo skill è chiedere a Claude di invocare il proprio skill skill-creator — lo scrive per te.

Cosa Sono i Claude Skills?

Un Claude skill è una cartella che contiene un file SKILL.md con frontmatter YAML (name, description, allowed-tools opzionale) che Claude Code carica automaticamente nel contesto quando il tuo prompt corrisponde alla descrizione. Gli skill impacchettano workflow riutilizzabili — come /commit o /explain-code — senza appesantire il system prompt.

Secondo la documentazione ufficiale di Anthropic, ogni cartella di skill ha tre elementi: un SKILL.md obbligatorio, script opzionali inclusi (da un helper Python a una configurazione JSON), e documentazione di riferimento opzionale che si carica insieme al corpo. Tutto qui. Nessun passaggio di build, nessuna installazione, nessun manifest.

La parte intelligente è la progressive disclosure. All'avvio, Claude scansiona solo il campo description di ogni skill. Il corpo — istruzioni, esempi, pattern di chiamata agli strumenti — rimane su disco finché il tuo prompt non corrisponde davvero. Puoi quindi avere 50 skill installati e pagare zero token cost finché uno non si attiva.

Pensa agli skill come alle ricette di un libro di cucina che Claude consulta quando vede gli ingredienti nel tuo prompt. Uno skill è una cartella che Claude legge su richiesta — non un prompt che devi ricordare di incollare. È tutto qui.

Un SKILL.md minimale si presenta così:

---
name: Summarize file
description: Use when the user asks for a 3-sentence summary of a file or function.
---

Read the file at $ARGUMENTS. Summarize purpose, key dependencies, and the
single most surprising thing about it. Three sentences max.

Dieci righe. Uno skill reale. Pronto per attivarsi.

Quick Start: Crea il Tuo Primo Skill in 10 Minuti

Per creare il tuo primo Claude skill in 10 minuti: (1) crea ~/.claude/skills/explain-code/, (2) aggiungi un file SKILL.md con name, description e il corpo del workflow, (3) riavvia Claude Code così scansiona la nuova directory, (4) attivalo con un prompt che corrisponde alla descrizione.

Ecco il flusso completo.

Step 1: Crea la directory

mkdir -p ~/.claude/skills/explain-code

Gli skill personali (solo per te) vanno sotto ~/.claude/skills/. Gli skill di progetto (condivisi via git con il team) vanno sotto .claude/skills/ alla radice del repo. Scegli personale per i workflow quotidiani; scegli progetto quando vuoi che ogni collaboratore del repo lo erediti.

Step 2: Scrivi SKILL.md

Salva questo file in ~/.claude/skills/explain-code/SKILL.md:

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
---

You are explaining code to a developer who is new to this codebase.

1. Read the file or snippet at $ARGUMENTS.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies or side effects.
5. End with one question the reader should ask before changing this code.

Questo è l'intero skill. Il frontmatter è il contratto; il corpo è il manuale operativo.

Step 3: Riavvia Claude Code

La scoperta in tempo reale è una funzionalità di Skills 2.0 — le versioni precedenti di Claude Code richiedono un riavvio per individuare la nuova directory. Se non sei sicuro di quale versione stai usando, un riavvio non costa nulla.

Step 4: Attivalo

Apri un progetto e scrivi:

walk me through what auth/middleware.ts does

Claude confronta il tuo prompt con il campo description, trova explain-code e carica silenziosamente il corpo di SKILL.md nel contesto. Vedrai "Using skill: explain-code" nel log degli strumenti. Fatto.

Pro tip: Non hai voglia di scrivere il file da solo? Apri Claude Code e scrivi Use the skill-creator skill to scaffold an explain-code skill for me. Il skill-creator incluso di Anthropic è uno meta-skill che ti intervista, sceglie gli allowed-tools appropriati e scrive il SKILL.md nella cartella giusta. Il percorso più rapido per il tuo primo skill, senza dubbio.

Questa è la promessa dei 10 minuti — cinque minuti di scrittura, un riavvio, un prompt di test.

Dentro SKILL.md: Il Riferimento del Frontmatter

Il frontmatter di SKILL.md è YAML racchiuso in delimitatori ---. Due campi sono obbligatori: name (≤64 caratteri, usato come nome dello slash-command) e description (il testo trigger che Claude confronta con il tuo prompt). I campi opzionali controllano l'accesso agli strumenti, l'invocazione del modello, i glob dei file e il contesto di esecuzione.

Ecco il riferimento completo, tratto dalla documentazione sugli skill di Anthropic:

La riga context: fork merita una nota a parte. È una primitiva di Skills 2.0 che esegue lo skill in una finestra di contesto isolata — utile per skill di ricerca a lunga durata o per qualsiasi cosa che produca molti token intermedi che non vuoi far inquinare il thread principale. Se non conosci ancora questo concetto, la nostra guida sul context engineering copre i compromessi.

Un frontmatter SKILL.md massimalista, con ogni campo popolato:

---
name: Deploy preview
description: Use when the user wants to deploy a preview build of the current branch to staging.
allowed-tools: ["Bash(git status:*)", "Bash(npm run build:*)", "Bash(vercel:*)"]
disable-model-invocation: true
user-invocable: true
argument-hint: <branch-name or 'current'>
model: claude-opus-4-7
context: fork
globs: ["package.json", "vercel.json"]
references: ["./deploy-runbook.md"]
bundled-files: ["./scripts/preflight.sh"]
tags: ["deploy", "vercel", "preview"]
---

Pro tip: Il singolo errore più comune nella description: scriverla per gli esseri umani. Scrivila per Claude — frasi trigger concrete, non testo marketing. Sbagliato: "Un potente skill di automazione Git." Giusto: "Use when the user wants to commit changes, write a commit message, or open a PR."

Due Skill Reali, End-to-End

Due pattern di skill coprono l'80% dei casi d'uso reali: (1) uno skill /commit invocabile dall'utente con disable-model-invocation: true e allowed-tools: Bash(git *) per azioni deterministiche; (2) uno skill /explain-code auto-invocato con frontmatter predefinito che Claude attiva quando i prompt corrispondono alla sua descrizione.

La maggior parte dei tutorial mostra frammenti. Ecco due file completi che puoi copiare in ~/.claude/skills/ oggi stesso.

Lo skill /commit (invocabile dall'utente)

---
name: Commit
description: Use when the user wants to stage and commit code changes with an AI-written conventional-commit message.
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - "Bash(git status:*)"
  - "Bash(git diff:*)"
  - "Bash(git add:*)"
  - "Bash(git commit:*)"
---

1. Run `git status` and `git diff` to see what's staged and unstaged.
2. Group changes into one logical commit. If there are multiple unrelated
   changes, ask the user which to include.
3. Draft a Conventional Commits message: `type(scope): subject` (≤72 chars),
   blank line, body explaining *why*, not *what*.
4. Show the message to the user. Ask "Commit this?" Wait for explicit yes.
5. On confirmation, run `git add` for the included files and `git commit -m`.
6. Print the resulting commit hash.

Prompt di test: /commit

Cosa succede: Claude ispeziona lo stato git, elabora un messaggio, chiede conferma e solo allora esegue git commit. Il disable-model-invocation: true significa che non si attiva mai automaticamente su un vago "salva le mie modifiche" — si esegue solo quando scrivi /commit. La whitelist allowed-tools lo limita ai sottocomandi git; non può fisicamente eseguire rm -rf o fare push sul remote. Questo è uno skill che usiamo nella nostra pipeline.

Per azioni post-commit deterministiche (eseguire lint, rigenerare i tipi, inviare un webhook Slack), usa invece gli hook di Claude Code — gli skill sono probabilistici, gli hook si attivano ogni singola volta.

Lo skill /explain-code (invocabile dal modello)

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
argument-hint: <file path or pasted snippet>
model: claude-opus-4-7
---

1. Read the file or snippet at $ARGUMENTS. If $ARGUMENTS is empty, ask
   the user which file to explain.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies, side effects, or hidden assumptions.
5. End with one question the reader should ask before modifying this code.

Prompt di test: walk me through what auth/middleware.ts does

Cosa succede: nota che l'utente non ha digitato /explain-code. Claude confronta "walk me through" con il campo description, trova lo skill e lo invoca automaticamente. Questa è la magia — la description fa il routing. Il campo model: claude-opus-4-7 fissa questo skill su Opus indipendentemente dal modello impostato come predefinito, così le analisi approfondite del codice usano sempre il modello più capace. (Ulteriori informazioni sull'utilizzo di Claude Code con modelli diversi.)

Perché due pattern? Lo skill #1 è invocabile dall'utente e limitato a strumenti specifici — prevedibile, sicuro, perfetto per git o deploy. Lo skill #2 è auto-invocato e a campo aperto — la magia degli skill, ma fidati del tuo campo description. Gli skill invocabili dall'utente ti danno prevedibilità; quelli invocabili dal modello ti danno magia. Scegli per ogni skill, non per ogni repo.

Per altri skill di esempio reali, consulta il repo ufficiale anthropics/skills e la lista mantenuta dalla community awesome-claude-skills.

Skills vs MCP vs Subagent vs Hook: Quando Usare Cosa

Usa gli Skill per workflow riutilizzabili che Claude deve auto-attivare o che invochi come slash-command. Usa i server MCP quando hai bisogno di dati esterni in tempo reale (database, API, filesystem oltre la working dir). Usa i subagent per piani multi-step che Claude deve delegare a un contesto fresco. Usa gli hook per eventi deterministici (pre-commit, post-tool-use) che devono sempre attivarsi — mai probabilisticamente.

Schema rapido: gli skill sono workflow, il Model Context Protocol è dati, i subagent sono piani, gli hook sono eventi. Ciascuno vive a un livello diverso di Claude Code, e il livello sbagliato è lo strumento sbagliato. Secondo il post Skills explained di Anthropic, questo è il framework che vogliono che tu interiorializzi.

Si compongono. Uno skill può chiamare uno strumento MCP tramite allowed-tools. Un hook può attivarsi dopo che uno skill è completato. Un subagent può usare gli skill a cui ha accesso. Il modello mentale più pulito: scegli prima il livello giusto, poi lasciali impilare. Gli skill sono la primitiva di context engineering a cui arrivi quando vuoi un workflow che Claude può scegliere; automatizzi con gli hook quando vuoi qualcosa che Claude non può saltare.

Il peggior modo di usare male ciascuno: Skill per dati in tempo reale (usa MCP); MCP per template di prompt one-shot (usa Skill); subagent per modifiche deterministiche ai file (usa hook); hook per logica ramificata (usa Skill). Gli skill sono workflow, MCP è dati, i subagent sono piani, gli hook sono eventi. Scegli per livello, non per parola chiave.

Dove Vivono gli Skill: Personale, Progetto, Plugin, Enterprise

Gli skill di Claude si installano in quattro ambiti: personale (~/.claude/skills/, solo tu), progetto (.claude/skills/ nella radice del repo, il tuo team via git), plugin (distribuiti tramite il Marketplace di Anthropic o qualsiasi URL di plugin), e enterprise (distribuiti dall'IT tramite MDM/policy di amministrazione). Claude scansiona tutti e quattro gli ambiti all'avvio.

Gli skill per documenti inclusi sono facili da dimenticare — Claude Code include già skill per pdf, docx, pptx e xlsx out of the box, più una piccola libreria di /debug, /simplify e simili. (Lo strumento gemello Claude Design include i propri skill di workflow per la generazione di design; stesso modello, dominio diverso.)

Quando distribuire tramite plugin invece che tramite progetto? I plugin vincono quando lo stesso workflow beneficia di più repo — uno skill /release che usi in cinque codebase di clienti appartiene a un plugin, non copiato in ogni .claude/skills/ del repo. Gli skill di progetto vincono per le convenzioni specifiche del codebase (il template PR del tuo team, il tuo test runner personalizzato). Il Marketplace di Anthropic, più /plugin install da qualsiasi URL, rende i plugin la risposta giusta per il riuso cross-repo. Secondo la documentazione dei plugin, la scoperta e gli aggiornamenti sono gestiti automaticamente.

Pattern Avanzati: $ARGUMENTS, Shell Injection Dinamica, context: fork

Tre pattern avanzati degli skill contano davvero: $ARGUMENTS permette agli utenti di passare parametri agli skill invocabili dall'utente (/translate $ARGUMENTS); la shell injection dinamica (con allowed-tools: Bash(...)) permette a uno skill di eseguire script e inviare l'output nel contesto; e context: fork (Skills 2.0) esegue lo skill in una finestra di contesto isolata. Il whitepaper Complete Guide di Anthropic è il riferimento canonico per context: fork a partire da maggio 2026.

$ARGUMENTS per skill parametrizzati

---
name: Translate
description: Translate the most recent message into the target language.
user-invocable: true
argument-hint: <target-language, e.g. spanish, japanese, brazilian portuguese>
---

Translate the user's previous message into $ARGUMENTS. Preserve tone,
preserve markdown formatting, return only the translation.

Prompt di test: /translate spanish. Claude sostituisce spanish con $ARGUMENTS a runtime. Il modo più pulito per rendere uno skill multi-purpose senza scrivere varianti.

Shell injection dinamica tramite allowed-tools

---
name: Review last commit
description: Use when the user wants a code review of the last git commit.
allowed-tools: ["Bash(git diff HEAD~1:*)", "Bash(git log -1:*)"]
---

Run `git diff HEAD~1` and `git log -1`. Review the diff for bugs, security
issues, and style violations. Output a 5-bullet review.

Lo skill esegue il shell, invia il diff nel contesto e lo analizza. Limita allowed-tools a comandi specifici (Bash(git diff HEAD~1:*)), mai Bash generico — il permesso Bash generico è la versione da "colpo di pistola al piede" di questo pattern.

context: fork (Skills 2.0)

---
name: Deep research
description: Use when the user wants a multi-source research summary on a topic.
context: fork
---

Research the topic in $ARGUMENTS using available web tools. Produce a
2-page summary with citations. Do not pollute the main thread.

Il forking dà allo skill la propria finestra di contesto, così i 50K token di note di ricerca intermedie non contaminano la sessione principale. Utile per ricerche lunghe, pianificazione di grandi refactoring, o qualsiasi cosa che produca molti token temporanei. Solo Skills 2.0 — le versioni precedenti di Claude Code ignorano il campo.

Troubleshooting: Perché il Tuo Skill Non Si Attiva

Gli skill di solito non si attivano per uno di questi quattro motivi: (1) la description è troppo generica per consentire a Claude di trovare una corrispondenza con il tuo prompt, (2) la directory è nel percorso sbagliato (.claude/skills/ non claude/skills/), (3) Claude Code non è stato riavviato dopo l'aggiunta dello skill (solo pre-Skills-2.0), oppure (4) il nome dello skill è in conflitto con uno skill bundled o con priorità più alta. Secondo le modalità di fallimento più cercate nel tracker delle issue di Claude Code su GitHub, questi quattro casi coprono il ~95% dei report "perché non funziona".

Modalità di fallimento 1: "Il mio skill non appare affatto"

La causa principale è un percorso sbagliato — .claude/skills/ (con il punto) vs claude/skills/ (senza punto) è un errore di battitura che tutti abbiamo fatto all'una di notte. Esegui ls -la ~/.claude/skills/ per confermare che la directory esiste con il punto. Se è lì ma Claude ancora non la vede, riavvia Claude Code una volta. Le versioni pre-Skills-2.0 scansionano solo all'avvio.

Modalità di fallimento 2: "Claude non invoca automaticamente il mio skill"

Il campo description è troppo vago o è scritto per gli esseri umani, non per Claude. Riscrivilo con frasi trigger concrete che rispecchiano come gli utenti pongono effettivamente le richieste. Dopo aver costruito 4 skill per questo repo, l'errore in cui sono incappato era lasciare descrizioni come "A helpful skill for SEO." Inutile. Riscrivi così: "Use when the user wants to add JSON-LD schema, meta tags, or SEO frontmatter to a Markdown post." La precisione di attivazione è passata da ~30% a ~95%. La precisione di attivazione dipende dal campo description. Scrivilo per Claude, non per il tuo curriculum.

Modalità di fallimento 3: "La descrizione è troncata nel pannello slash-command"

O la tua description supera i 1024 caratteri o il tuo name supera i 64 caratteri. Entrambi hanno limiti rigidi. Soluzione: dividi lo skill in due skill più specifici, oppure sposta il dettaglio lungo nel corpo del SKILL.md. Il frontmatter serve per il routing, non per la documentazione.

Modalità di fallimento 4: "Il rilevamento delle modifiche in tempo reale non funziona"

Claude Code pre-Skills-2.0 richiede un riavvio completo dopo ogni modifica a SKILL.md. Se stai iterando su uno skill e le tue modifiche non vengono applicate, probabilmente stai usando una build precedente. Aggiorna a una versione di Claude Code che include Skills 2.0 (scoperta in tempo reale) oppure prendi l'abitudine di riavviare dopo ogni salvataggio. È scomodo, ma economico.

Skills Oltre Claude: Lo Standard Aperto Agent Skills

Sì — gli skill sono uno standard aperto. Lo standard Agent Skills su agentskills.io definisce il formato SKILL.md indipendentemente da qualsiasi vendor. Il CLI Codex di OpenAI e ChatGPT Desktop hanno adottato lo standard a dicembre 2025; lo stesso SKILL.md che scrivi per Claude Code funziona in Codex con piccole modifiche al frontmatter.

Ecco la matrice di supporto cross-tool a maggio 2026: Claude Code ha il supporto completo per Agent Skills (l'implementazione di riferimento). Il CLI Codex di OpenAI ha il supporto completo. ChatGPT Desktop ha supporto parziale — name, description e il corpo funzionano, ma la parità per allowed-tools non c'è ancora. Gemini CLI ha annunciato il supporto all'inizio del 2026 ma non lo aveva ancora pubblicato al momento della scrittura. Cursor è l'eccezione — usa il proprio formato Cursor rules e non legge nativamente SKILL.md, anche se esistono shim della community.

Cosa scrivere oggi per far sopravvivere i tuoi skill nel tempo: mantieni name e description puliti e agnostici rispetto al vendor. Isola qualsiasi frontmatter specifico del vendor dietro un namespace (claude: o codex:) se vuoi il supporto cross-tool. La superficie portabile — name, description, body, $ARGUMENTS — funziona ovunque; i campi avanzati come context: fork sono specifici di Claude finché altri vendor non pubblicano equivalenti. Anthropic sta anche spingendo per una maggiore integrazione con il marketplace secondo la roadmap di Claude Code trapelata, quindi la portabilità migliorerà ancora.

I tre posti dove cercare skill di esempio: anthropics/skills (ufficiale), awesome-claude-skills (community), e agentskills.io (la pagina delle specifiche dello standard). Gli skill non sono più una funzionalità di Claude. Sono uno standard aperto che Claude ha lanciato per primo.

FAQ

Qual è la differenza tra un Claude skill e un server MCP?

Un Claude skill è un file SKILL.md con istruzioni di workflow che Claude carica quando il tuo prompt corrisponde alla sua descrizione. Un server MCP è un processo separato che Claude chiama per recuperare dati in tempo reale (database, API, filesystem oltre la working dir). Usa gli skill per i workflow; usa MCP per i dati. Si compongono — gli skill possono chiamare strumenti MCP.

I Claude skills sono gratuiti?

Sì — Skills è una funzionalità integrata di Claude Code, senza costi aggiuntivi. Paghi solo per i token del modello consumati quando uno skill viene eseguito. Gli skill installati dall'Anthropic Marketplace possono essere a pagamento (raro oggi), ma il repo ufficiale anthropics/skills e le liste della community sono tutti gratuiti da copiare e usare.

Dove si installano i Claude skills?

Gli skill personali vanno in ~/.claude/skills/{skill-name}/, quelli di progetto in .claude/skills/{skill-name}/ alla radice del repo. Gli skill plugin si installano tramite /plugin install <url> e si trovano nella tua directory dei plugin. Gli skill enterprise sono distribuiti dall'IT della tua organizzazione tramite le impostazioni gestite. Claude Code scansiona tutti e quattro gli ambiti all'avvio.

Come si crea un Claude skill da zero?

Crea una cartella sotto ~/.claude/skills/, aggiungi un file SKILL.md con frontmatter YAML (name, description) seguito dalle istruzioni del workflow, e riavvia Claude Code. Il percorso più rapido: apri Claude Code e chiedigli di invocare lo skill skill-creator incluso — crea lo scaffold del SKILL.md per te in meno di un minuto.

Perché il mio Claude skill non si attiva?

Le quattro cause più comuni: (1) la description è troppo vaga per Claude per trovare corrispondenza con il tuo prompt — riscrivila con frasi trigger concrete; (2) lo skill si trova nel percorso sbagliato (.claude/skills/ non claude/skills/); (3) Claude Code ha bisogno di un riavvio sulle versioni pre-Skills-2.0; (4) il nome dello skill è in conflitto con uno skill bundled. Verifica con ls -la ~/.claude/skills/.

ChatGPT o Cursor possono usare i Claude skills?

ChatGPT Desktop e Codex CLI supportano lo stesso standard Agent Skills di Claude — lo stesso SKILL.md funziona in entrambi con piccole modifiche al frontmatter. Cursor usa il proprio formato Cursor rules e non legge nativamente SKILL.md. Gemini CLI ha annunciato il supporto all'inizio del 2026 ma non lo aveva ancora pubblicato a maggio 2026.

Cos'è lo skill skill-creator?

skill-creator è un meta-skill incluso nel repo anthropics/skills che aiuta Claude a scrivere nuovi file SKILL.md per te. Descrivi a Claude cosa vuoi che lo skill faccia; skill-creator ti intervista per la descrizione, sceglie gli allowed-tools appropriati e scrive il SKILL.md nella cartella giusta. Lo scaffold più rapido possibile.

Cosa fa disable-model-invocation?

Impostare disable-model-invocation: true nel frontmatter del tuo skill impedisce a Claude di attivare automaticamente lo skill in base alla corrispondenza del prompt. Lo skill diventa invocabile solo dall'utente — appare nel pannello slash-command come /skill-name e si esegue solo quando viene chiamato esplicitamente. Usalo per azioni distruttive o deterministiche come /commit o /deploy.

Crea qualche skill, pubblicali in un progetto, vedi cosa funziona. Se il tuo team continua a imbattersi nel gruppo di problemi "skill non si attiva" su più repo e vuoi un secondo paio di occhi sulla configurazione .claude/skills/, contattaci — siamo felici di fare un'analisi insieme.