Giacomo Mantovani

Articolo · 3 novembre 2026 · Di Giacomo Mantovani

Skill per Claude Code: come insegnare all'agente i processi del tuo team

Le 14 skill nella repo di questo sito: cosa contiene un SKILL.md, come si scrive una descrizione che l'agente riconosce e quando una skill non serve.

  • claude-code
  • agenti-ai
  • flusso-di-lavoro
  • skill
È la descrizione a decidere se la skill parte. 14 skill, 5 si avviano solo con /nome.

Nella repo di questo sito ci sono 14 skill, in .claude/skills. Una scrive gli articoli del blog, una toglie dai testi i tic da AI, due si occupano dei test, una porta in produzione le modifiche. Le ho scritte perché continuavo a ripetere le stesse istruzioni in chat, ogni volta con parole un po' diverse. Una skill trasforma una procedura che il team segue già in un file che l'agente apre quando serve.

Qui spiego come le scrivo: cosa mettere nel file, come fare in modo che l'agente scelga quella giusta e quando una skill è lo strumento sbagliato. Gli esempi sono in inglese perché le skill lo sono: le legge un agente, e servono a chiunque lavori sulla repo.

Cos'è una skill di Claude Code e in cosa è diversa da CLAUDE.md e hook?

Una skill è una cartella che contiene un file SKILL.md. Le skill di progetto stanno in .claude/skills/<nome>/SKILL.md e si versionano con la repo, quindi le ha tutto il team; quelle personali stanno in ~/.claude/skills. La documentazione ufficiale riassume la differenza in una frase: a differenza del CLAUDE.md, il corpo di una skill si carica solo quando viene usata, quindi anche un materiale di riferimento lungo non costa quasi nulla finché non serve (documentazione Claude Code, ottobre 2026). I comandi slash personalizzati sono confluiti nelle skill: un file .claude/commands/deploy.md e una skill di nome deploy creano entrambi /deploy.

Il CLAUDE.md invece si carica a ogni sessione, e Claude lo tratta come contesto e non come configurazione vincolante ("context, not enforced configuration"). Per bloccare un'azione qualunque cosa decida il modello, la documentazione sulla memoria rimanda a un hook PreToolUse (documentazione Claude Code, ottobre 2026). Sono tre strumenti con compiti diversi:

CLAUDE.md, skill e hook a confronto
CLAUDE.mdSkillHook
Quando si caricaA ogni sessione, per interoLa descrizione sempre, il corpo solo quando serveScatta su un evento di un tool
Serve perFatti che l'agente non può dedurre: package manager, stranezze della build, regole di rilascioProcedure: scrivere un articolo, fare TDD, rilasciare una modificaCose che non devono mai succedere: leggere segreti, fare force push
È vincolante?No, è contestoNo, è contestoSì, può negare la chiamata al tool
CostoOgni riga, a ogni turnoUna riga di descrizione per turnoIl tempo di esecuzione dello script

Il criterio della documentazione è quello che uso anch'io: si crea una skill quando ci si ritrova a incollare in chat sempre la stessa checklist o procedura, oppure quando una sezione del CLAUDE.md è diventata una procedura invece di un fatto.

Cosa contiene un file SKILL.md?

Due parti: un frontmatter YAML in cima e sotto le istruzioni in markdown. Tutti i campi del frontmatter sono facoltativi e la documentazione raccomanda solo description. Questo è l'inizio della skill blog-post di questa repo, quella con cui preparo le bozze di articoli come questo:

---
name: blog-post
description: Use when writing or planning a blog post for this site (topic, outline, draft, SEO fields, or creating the Sanity draft).
---

# Blog post

Pillars, calendar, backlog and measurement: [docs/content-strategy.md](../../../docs/content-strategy.md). Pick the topic from there.

Il corpo è di 122 righe. Dice chi è il lettore, quali prove servono, come si struttura l'articolo, i limiti dei campi SEO, le regole sui link, e chiude con un flusso numerato che termina con la creazione della bozza nel CMS. Somiglia al brief che darei a un nuovo redattore, con la differenza che l'agente lo rilegge per intero ogni volta.

I campi che uso più spesso:

I campi del frontmatter da conoscere
CampoCosa faQuando lo uso
descriptionDice a Claude cosa fa la skill e quando caricarlaSempre
disable-model-invocation: trueSi avvia solo se una persona scrive /nomeFlussi che voglio lanciare io: triage, retrospettive, suddivisione in ticket
user-invocable: falseNascosta dal menu /, la carica solo ClaudeConoscenza di contesto che nessuno deve lanciare a mano
allowed-toolsTool usabili senza richiesta di permesso in quel turnoComandi ripetitivi e a basso rischio
context: forkEsegue la skill in un subagente separatoLavori lunghi i cui dettagli non devono riempire la sessione principale

Come si scrive una descrizione che Claude usa davvero?

La descrizione è l'unica parte della skill che resta sempre nel contesto, e Claude la legge per decidere se caricare il resto. Va scritta quindi come un elenco di situazioni in cui usarla: se è vaga, la skill non parte mai. C'è anche un limite fisso: description e when_to_use insieme vengono troncati a 1.536 caratteri nell'elenco delle skill, quindi il caso d'uso principale va messo all'inizio.

Questa è la descrizione della skill tdd della repo:

description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

Comincia con il nome della cosa e poi elenca i casi distinti in cui deve attivarsi, compresa l'espressione esatta che si scrive in chat. La skill writing-for-agents della stessa repo mette per iscritto le regole che seguo: la parola chiave per prima, un solo trigger per ogni caso distinto, e via i sinonimi che descrivono due volte lo stesso caso. Ogni parola della descrizione si paga a ogni turno; una frase come "aiuta a scrivere test migliori in modo efficiente" occupa contesto e non fa scattare niente.

Quando conviene spostare il materiale di una skill in altri file?

Quando serve solo in alcuni casi. La documentazione consiglia di tenere il SKILL.md sotto le 500 righe e di spostare il materiale di riferimento più dettagliato in file separati, collegati dalla skill con l'indicazione di cosa contengono e quando aprirli. L'agente li apre solo quando la frase del collegamento corrisponde al task.

In questa repo la skill writing-for-agents tiene nel SKILL.md le regole generali di scrittura e manda altrove un solo caso: "When the document you're writing is a skill, read SKILL-MECHANICS.md for frontmatter, invocation choice, and router skills." Un agente che modifica un CLAUDE.md non ha motivo di aprire quel file; uno che scrive una skill sì. La skill blog-post fa lo stesso con la strategia dei contenuti: calendario e argomenti stanno in docs/content-strategy.md, che legge anche il team, e la skill contiene solo il rimando.

Una skill può richiamarne un'altra?

Sì. Il corpo di una skill può dire all'agente di invocare un'altra skill, ed è così che tengo il materiale comune in un solo posto. L'esempio più piccolo della repo è grill-with-docs, sette righe in tutto:

---
name: grill-with-docs
description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
disable-model-invocation: true
---

Call the Skill tool twice, for "grilling" and "domain-modeling".

La skill blog-post funziona allo stesso modo. Il penultimo passo del suo flusso è la revisione con humanizer: passare l'intera bozza, FAQ e campi SEO compresi, alla skill humanizer, lasciando invariati numeri, link e fonti. Humanizer è una skill di 416 righe che ho preso dal progetto open source blader/humanizer, con una sezione sull'italiano aggiunta in locale: em dash, "non solo... ma anche", "fondamentale", burocratese. Essendo una skill separata la uso anche per messaggi di commit e documentazione, e blog-post resta concentrata sull'articolo.

Allo stesso modo la skill tdd rimanda a codebase-design quando è in discussione la forma di un'interfaccia, e il CLAUDE.md del progetto apre con "TDD, non negoziabile" e nomina le skill tdd e testing. La regola sta nel CLAUDE.md perché vale per ogni modifica; il come sta nelle skill perché serve solo mentre si scrivono i test.

Meglio una skill che Claude attiva da solo o una che lanci tu?

Cinque delle 14 skill della repo hanno disable-model-invocation: true: triage, retro, to-tickets, grill-with-docs e improve-codebase-architecture. Sono lavori che avvio io, e nessuno dei cinque deve partire perché una frase della conversazione per caso combacia con la descrizione. Una skill di questo tipo non costa niente in contesto, perché la sua descrizione non entra nell'elenco; in cambio bisogna ricordarsi che esiste.

Le altre nove le attiva il modello. L'agente deve arrivare da solo a testing o tdd ogni volta che scrive codice, e altre skill devono poter richiamare humanizer o domain-modeling. Se né l'agente né un'altra skill dovranno mai avviarla, conviene renderla manuale.

Quando una skill non è lo strumento giusto?

Quale meccanismo usare
Ti serveUsaPerché
Un fatto che l'agente non può dedurre ("pnpm only")Una riga nel CLAUDE.mdVale per ogni task e una riga costa poco
Una garanzia (non leggere mai i file .env)Un hook o una regola di permessoSkill e CLAUDE.md sono contesto, il modello può ignorarli
Qualcosa che il codice dice già (cartelle, script)NienteL'agente sa leggere package.json, una copia invecchia
Una procedura che serve ogni tantoUna skillIl corpo si carica solo per quel task

Non scrivo una skill nemmeno quando una procedura è capitata una volta sola. La scrivo alla seconda o terza volta che spiego la stessa cosa, quando so quali parti l'agente sbaglia. Nella guida su come scrivere il CLAUDE.md trovi l'altra metà di questa divisione: cosa resta nel file sempre caricato.

Quali errori evitare quando si scrivono skill per Claude Code?

Il primo è una descrizione pensata per le persone ("Una skill utile per i contenuti del blog") invece che un elenco di casi d'uso: la skill c'è ma non si carica mai. Il secondo è affidare a una skill regole che devono valere sempre. Una skill che dice "non fare mai push su main" resta una richiesta, e a bloccare il push può essere solo un hook o un permesso. Il terzo è copiare nella skill materiale che sta già in un documento mantenuto dal team: nel giro di un mese le due versioni divergono. Il quarto è un'unica skill da mille righe che copre ogni caso, che la documentazione sconsiglia e che seppellisce i passi utili sotto materiale che in quel momento non serve. L'ultimo è non rileggerle mai. Ogni regola nelle mie skill è stata aggiunta dopo un errore dell'agente, e una regola che nessuno rilegge resta lì anche quando non serve più.

Negli errori più comuni con Claude Code racconto dove hook e review prendono il posto delle regole scritte.

Prossimo passo

Vuoi i processi del tuo team in skill che gli agenti usano davvero?

Configuro Claude Code per team di sviluppo: skill, CLAUDE.md, hook e review costruiti su come il team lavora già. Raccontami da dove partite.

Parliamone

Se invece di configurare un assistente di coding stai costruendo agenti per la tua azienda, gli stessi principi valgono per prompt di sistema e descrizioni dei tool. È il lavoro che faccio nel servizio di sviluppo di agenti AI.

Domande frequenti

Dove metto una skill perché la usi tutto il team?

Nella repo, in .claude/skills/<nome>/SKILL.md, versionata con git. Le skill personali in ~/.claude/skills valgono per tutti i tuoi progetti sul tuo computer ma non sono condivise.

Le skill rallentano Claude Code o riempiono il contesto?

Nel contesto resta sempre solo la descrizione delle skill che il modello può attivare. Il corpo si carica quando la skill viene usata, e quelle con disable-model-invocation: true non aggiungono nulla finché non scrivi il loro nome.

Comandi slash e skill ormai sono la stessa cosa?

Sì. Secondo la documentazione di Claude Code i comandi personalizzati sono confluiti nelle skill: .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md creano entrambi /deploy. Le skill in più hanno i file di supporto e il controllo su chi le avvia.

Quanto deve essere lungo un SKILL.md?

La documentazione consiglia di restare sotto le 500 righe e di spostare il materiale di riferimento più dettagliato in file collegati. La mia skill più lunga, humanizer, ha 416 righe; la maggior parte sta sotto le 125.

Autore

Giacomo Mantovani

AI Engineer e Consulente AI per Aziende e Agenzie

LinkedInGitHub

Prossimo passo

Raccontami il processo. Lo definiamo in una call gratuita, poi una versione funzionante è operativa entro 10 giorni.

Prenota una call di analisi

Articoli correlati