Claude Skills: Cosa Sono e Come Crearne Una da Zero

Perché le Skills Cambiano il Tuo Workflow con Claude Code

Se usi Claude Code come strumento principale nel tuo workflow da developer, prima o poi ti ritrovi a fare sempre le stesse cose. Scrivi la stessa code review request, generi componenti con le stesse istruzioni, documenti il codice seguendo sempre lo stesso schema. Ogni volta da zero. Ogni volta le stesse istruzioni riscritte a mano.

Le Claude Skills risolvono esattamente questo problema. Sono comandi personalizzati — slash command — che invochi con /nome-skill direttamente in Claude Code. Incapsulano istruzioni complesse, workflow interi, o le convenzioni del tuo progetto in un singolo comando riutilizzabile.

In questa guida trovi tutto: cosa sono, come si strutturano, come crearne una da zero con esempi concreti, e alcune skills pronte all’uso che puoi copiare direttamente nel tuo setup.

Cosa Sono le Claude Skills (e Dove Vivono)

Una Claude Skill è un file Markdown salvato in una cartella specifica che Claude Code riconosce come slash command. Quando digiti /nome-skill nella chat, Claude legge automaticamente quel file e segue le istruzioni che contiene — senza che tu debba ripetere nulla.

Esistono due tipi di skills, differenziate dalla posizione del file:

Skills globali — salvate in ~/.claude/skills/, disponibili in qualsiasi progetto sul tuo sistema
Skills di progetto — salvate in .claude/skills/ nella root del repository, disponibili solo in quel progetto e versionabili con git

La distinzione è utile in pratica. Le skills globali contengono i tuoi workflow personali: la tua code review standard, il modo in cui preferisci documentare il codice, i tuoi standard di commit. Le skills di progetto contengono le regole specifiche del codebase: come si nominano i componenti, quale stack di testing si usa, le convenzioni del team.

💡 Differenza chiave: CLAUDE.md fornisce contesto a Claude (cosa sa del progetto), le Skills definiscono azioni (cosa fa quando le invochi). Sono complementari, non alternative. Il CLAUDE.md spiega “usiamo React + TypeScript, i componenti vanno in src/components” — la skill /genera-componente usa quel contesto per generare il file corretto.

Anatomia di una Claude Skill: Struttura del File

Una skill è un file .md con una struttura precisa. Vediamo un esempio completo:

---
name: code-review
description: Esegui una code review completa del file o della funzione specificata
---

Fai una code review approfondita del codice selezionato o del file indicato.

Analizza questi aspetti:
1. **Bug e problemi logici** — comportamenti inattesi, edge case non gestiti
2. **Sicurezza** — input non sanitizzati, vulnerabilità OWASP comuni
3. **Performance** — query N+1, loop inefficienti, operazioni bloccanti
4. **Leggibilità** — nomi di variabili chiari, funzioni troppo lunghe
5. **Best practice** — SOLID, DRY, principi del linguaggio usato

Formato output:
- Una sezione per categoria (solo se ci sono problemi trovati)
- Severità: 🔴 critico / 🟡 warning / 🟢 suggerimento
- Per ogni problema: descrizione + esempio di fix

Le tre parti fondamentali di ogni skill:

Frontmatter YAML — il blocco tra --- con name e description. Il name diventa il nome del comando (/code-review), la description appare nell’autocomplete quando digiti / in Claude Code
Body — le istruzioni che Claude seguirà all’invocazione. Possono essere semplici (poche righe) o dettagliate (workflow multi-step con output strutturato)
Nome del file — deve corrispondere al name nel frontmatter. Il file code-review.md crea il comando /code-review

Tutorial: Creare la Tua Prima Skill da Zero

Costruiamo insieme una skill concreta e subito utile: genera componenti React seguendo le convenzioni del tuo progetto.

Step 1 — Crea la Cartella Skills

Per una skill globale (disponibile in tutti i tuoi progetti):

mkdir -p ~/.claude/skills/

Per una skill di progetto (solo nel repo corrente, committabile con git):

mkdir -p .claude/skills/

Step 2 — Scrivi il File della Skill

Crea il file ~/.claude/skills/genera-componente.md:

---
name: genera-componente
description: Genera un componente React TypeScript seguendo le convenzioni del progetto
---

Genera un componente React TypeScript con le specifiche indicate.

Se l'utente passa un nome come argomento (es. `/genera-componente Button`),
usa quello come nome del componente. Altrimenti chiedi il nome.

Convenzioni obbligatorie:
- File: `NomeComponente.tsx` nella cartella `src/components/`
- Export: named export (non default export)
- Props: interfaccia TypeScript separata `NomeComponenteProps`
- Stili: Tailwind CSS, nessun CSS module o styled-components
- Se il componente gestisce stati: estrai la logica in un hook in `src/hooks/`

Struttura minima da generare:

interface NomeComponenteProps {
  // aggiungi le props richieste
}

export const NomeComponente = ({ ...props }: NomeComponenteProps) => {
  return (
    // JSX qui
  )
}

Dopo aver generato il componente chiedi se vuole anche:
1. Il Storybook story
2. Il test con Vitest + Testing Library

Step 3 — Invoca la Skill

Apri Claude Code nella root del progetto e digita:

/genera-componente SearchBar

Claude legge il file skill e genera SearchBar.tsx seguendo esattamente le tue convenzioni: SearchBarProps come interfaccia TypeScript, named export, stili Tailwind, poi ti chiede se vuoi story e test. Ogni volta. Senza riscrire nulla.

Esempi Pratici: Skills Pronte da Copiare

Una raccolta di skills pronte all’uso che coprono i workflow più comuni nello sviluppo frontend e fullstack. Tutte salvabili in ~/.claude/skills/ come skills globali.

Skill: write-tests

---
name: write-tests
description: Genera test completi per il file o la funzione specificata
---

Scrivi test completi per il codice indicato o selezionato.

Stack: Vitest + Testing Library (per React) o Jest puro (per Node.js).

Per ogni funzione/componente testa obbligatoriamente:
1. **Happy path** — input valido, output atteso
2. **Edge cases** — valori null, undefined, array vuoti, stringhe vuote
3. **Errori attesi** — comportamento con input non valido
4. **Stato asincrono** — se ci sono Promise: testa loading, success, error

Convenzioni:
- Usa `describe` per raggruppare i test per funzione
- Nomi di test in italiano, descrittivi
- I mock con `vi.mock()` vanno in cima al file, mai dentro i test
- Preferisci `userEvent` a `fireEvent` per i test di interazione UI

Skill: explain

---
name: explain
description: Spiega il codice selezionato con contesto, motivazioni e possibili problemi
---

Spiega il codice indicato o selezionato.

Struttura la spiegazione in quattro parti:
1. **Cosa fa** — una frase sola, il più concisa possibile
2. **Come funziona** — step-by-step del flusso di esecuzione
3. **Perché è scritto così** — scelte architetturali, trade-off, pattern usato
4. **Cosa potrebbe andare storto** — edge case, dipendenze critiche, assunzioni implicite

Usa analogie concrete se stai spiegando qualcosa di astratto.
Se il codice ha bug evidenti o code smell, segnalali brevemente alla fine.

Skill: commit

---
name: commit
description: Analizza le modifiche staged e propone un commit message in Conventional Commits
---

Analizza le modifiche staged con `git diff --staged` e crea un commit message.

Formato (Conventional Commits):
  tipo(scope): descrizione breve in italiano

Tipi validi: feat, fix, refactor, style, test, docs, chore, perf
Regole:
- Prima riga: massimo 72 caratteri
- Scope: il modulo o componente principale modificato
- Descrizione: tempo presente ("aggiunge", "corregge", "rimuove")

Proponi il messaggio e chiedi conferma esplicita prima di eseguire il commit.

Passare Argomenti: Rendere le Skills Dinamiche

Le skills possono ricevere argomenti direttamente dalla riga di comando. Quando scrivi /skill-name argomento, tutto il testo dopo il nome della skill è disponibile nelle istruzioni come segnaposto args.

Esempio concreto — una skill per trovare dove viene usato un simbolo in tutto il codebase:

---
name: find
description: Trova dove viene usato un simbolo nel codebase e spiega il contesto d'uso
---

L'utente vuole trovare e capire dove viene usato il simbolo passato come argomento.

Esegui questi passi:
1. Cerca tutti i file che lo contengono (funzione, classe, variabile, tipo TypeScript)
2. Per ogni occorrenza: file, riga, contesto (3 righe sopra e sotto)
3. Identifica il pattern d'uso generale: come viene tipicamente importato e chiamato
4. Segnala eventuali utilizzi anomali, deprecati, o inconsistenti

Cerca sia nelle importazioni che nelle implementazioni.
Distingui tra definizione, importazione, e utilizzo effettivo.

Invocazione: /find useAuthContext — Claude cerca useAuthContext in tutto il progetto, mostra dove viene usato, e segnala eventuali inconsistenze. Utilissimo prima di un refactoring: sai esattamente l’impatto prima di toccare qualcosa.

Se vuoi costruire workflow dove Claude interagisce con tool esterni e API oltre le skills, la guida su Tool Use con Claude API è il passo successivo naturale.

Skills Avanzate: Workflow Multi-Step

Le skills possono orchestrare workflow completi che coinvolgono lettura di file, analisi del progetto e output strutturati. Un esempio reale: una skill di onboarding automatico che analizza il codebase e genera una guida per un nuovo sviluppatore.

---
name: onboard
description: Analizza il progetto e genera una guida di onboarding per un nuovo developer
---

Stai aiutando un nuovo sviluppatore a orientarsi in questo progetto.

Esegui questi step nell'ordine:

**1. Analisi dello stack**
- Leggi `package.json` per identificare framework, dipendenze principali, script disponibili
- Leggi `CLAUDE.md` o `README.md` per le convenzioni del team

**2. Mappa del codebase**
- Entry point dell'applicazione
- Come è organizzata la business logic
- Dove si trovano i componenti/moduli principali
- Come funziona il routing e la gestione dello stato

**3. Setup ambiente di sviluppo**
- Comandi per installare dipendenze e avviare il dev server
- Variabili d'ambiente necessarie (solo nomi, senza valori)
- Come eseguire i test

**4. Primo task consigliato**
- Suggerisci un task piccolo e circoscritto per iniziare

Formatta tutto come documento Markdown leggibile, non in stile conversazionale.

Questa skill trasforma Claude in un tech lead virtuale per il tuo progetto. Per architetture dove hai bisogno di agenti che collaborano tra loro, vale la pena esplorare come creare agenti AI in JavaScript con Claude.

Organizzare e Versionare le Skills

Man mano che costruisci più skills, l’organizzazione diventa importante. Regole pratiche che fanno la differenza nel lungo periodo:

Naming con verbi o sostantivi chiari — usa nomi come review, commit, generate-component, explain. Il nome deve dirti cosa fa senza dover aprire il file
Description precisa nel frontmatter — appare nell’autocomplete quando digiti /. Deve distinguersi da skills simili con un colpo d’occhio
Skills di progetto nel repository — le skills in .claude/skills/ vanno committate come qualsiasi altro file. Tutto il team le usa automaticamente, e si evolvono con il codebase
Testare le istruzioni prima di finalizzare — prova le istruzioni come prompt normale prima di salvarle come skill. Istruzioni ambigue producono output inconsistenti
Skills specifiche > skills generiche — una skill review-api-endpoint che conosce il tuo stack Express e controlla autenticazione JWT è molto più utile di una review generica

🎯 Consiglio strategico: le skills di progetto sono il modo migliore per rendere le convenzioni del team “eseguibili”. Invece di scrivere un documento di coding standards che nessuno legge, scrivi una skill /genera-componente che segue automaticamente quelle convenzioni. La documentazione migliore è quella che funziona.

Skills vs CLAUDE.md vs Prompt Diretto: Quando Usare Cosa

Prompt diretto — per richieste one-shot, contestuali, che non ripeterai. “Spiega questa funzione specifica” non vale la pena diventi una skill
CLAUDE.md — per contesto persistente che Claude deve avere sempre: stack tecnologico, architettura, convenzioni, link alla documentazione. È sempre attivo, non richiede invocazione
Skills — per workflow che ripeti spesso con output strutturato. Il criterio è semplice: se hai riscritto le stesse istruzioni più di tre volte, è il momento di farne una skill

La qualità delle istruzioni nelle skills dipende direttamente dal prompt engineering: le istruzioni nel body di una skill sono prompt, e prompt ben scritti producono output consistenti. Non è un dettaglio secondario.

FAQ e Domande Frequenti

Posso usare le Claude Skills senza Claude Code CLI?

No, le Skills sono una funzionalità specifica di Claude Code (il CLI tool di Anthropic) e non funzionano sulla web app di claude.ai o tramite la Claude API diretta. Se vuoi qualcosa di simile via API, devi implementare un sistema di template di prompt nel tuo codice applicativo.

Quante skills posso creare?

Non esiste un limite tecnico documentato. In pratica conviene mantenere un set di 5–15 skills ad alta frequenza d’uso piuttosto che crearne decine poco usate. Più skills hai, meno ricordi cosa fa ognuna e l’autocomplete si affolla. Meglio poche skills precise che molte skills vaghe.

Le skills possono eseguire comandi shell o leggere file?

Le skills stesse sono solo istruzioni Markdown, non codice eseguibile. Ma Claude Code, seguendo quelle istruzioni, può eseguire comandi shell, leggere e modificare file, fare chiamate API — tutto quello che normalmente può fare nel tuo progetto. È Claude che agisce, guidato dalle istruzioni della skill.

Posso condividere le mie skills con il team?

Sì, ed è uno degli use case più potenti. Le skills di progetto in .claude/skills/ si committano nel repository come qualsiasi altro file. Quando un collega clona il repo e apre Claude Code, ha automaticamente accesso a tutte le skills — senza configurazione aggiuntiva. Il modo più efficace per standardizzare il workflow del team attorno a Claude.

Conclusione

Le Claude Skills trasformano Claude Code da un assistente “rispondi e dimentica” a un sistema con memoria procedurale: sa come fare le cose nel tuo progetto specifico, non solo cosa fare in generale. Una volta che le hai integrate nel workflow, è difficile immaginare di farne a meno.

Il punto di partenza migliore è identificare le tre cose che spieghi più spesso a Claude — le istruzioni che riscrive ogni settimana. Quelle diventano le tue prime skills. Poi crescono organicamente con il progetto.

Se stai costruendo un setup strutturato attorno a Claude — con MCP server, agenti e automazioni — la guida su Model Context Protocol è il passo successivo naturale.

Suggerimenti e Risorse

🔨 Setup consigliato: inizia con tre skills globali essenziali — /review per la code review, /commit per i commit message, e /explain per capire codice sconosciuto. Queste coprono l’80% dei casi d’uso quotidiani. Poi aggiungi skills di progetto man mano che identifichi pattern ripetitivi specifici del tuo codebase.

💡 Pro tip: crea una skill /skills che lista tutte le tue skills disponibili con una breve descrizione. Quando non ricordi cosa hai configurato, la invochi e hai una panoramica immediata di tutti i comandi a disposizione.

🎯 Prossimo step: esplora la combinazione Skills + MCP Server. Le skills guidano Claude su cosa fare, i MCP server gli danno gli strumenti per farlo — accesso al database, API esterne, servizi di terze parti. Insieme formano un setup molto potente per l’automazione dello sviluppo.

Claude Skills: Cosa Sono e Come Crearne Una da Zero