# Claude Code Skills nel 2026: come creare una libreria di skills per te
> Come creare le Skills di Claude Code: struttura di SKILL.md, formula per la description, raccolte ufficiali pronte all’uso e anti-pattern. Passo dopo passo in 30 minuti.
Source: https://ailoot.ai/blog/it/claude-code-skills-library/
Canonical: https://ailoot.ai/blog/it/claude-code-skills-library/
Language: it
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-213
Revision: sha256-fe4145c6c9bb452652465eb8c05038319f7a833b68768b212a5d6f7c9e980f50
Punti chiave
Le Skills di Claude Code sono cartelle che contengono un file SKILL.md che Claude carica nel contesto solo quando serve. CLAUDE.md resta in memoria tutto il tempo e consuma il budget di token, mentre una skill si carica in risposta a un trigger: in un progetto possono convivere facilmente decine di skills. La parte più importante di una skill è la sua description: Claude la usa per decidere se attivarla. In questo articolo spiego la struttura di SKILL.md, la formula per la description, le raccolte pronte all’uso e come creare la tua prima skill in 30 minuti.
[Documentazione Ailoot: API, chiavi e configurazione](https://ailoot.ai/docs/).
## Che cos’è una skill in Claude Code e perché non è solo «un prompt più grande»?
Punti chiave
Una skill è una directory che contiene un file SKILL.md in cui si descrive quando e come applicare una metodologia specifica. Anthropic paragona una skill alle istruzioni per un nuovo dipendente: non gli detti ogni passaggio ogni giorno; gli dai una procedura e lui la applica da sé nelle situazioni giuste. La differenza principale rispetto a CLAUDE.md è che una skill viene caricata nel contesto solo quando serve, quindi in un progetto possono esserci decine di skills senza intaccare il budget di token.
Claude Code Skills è una funzionalità nativa di Claude Code che Anthropic ha lanciato nell’ottobre 2025 per Pro/Max/Team/Enterprise. In seguito ha reso pubblica la specifica [Agent Skills](https://agentskills.io) come standard utilizzabile anche al di fuori di Claude. Nel codice è solo una cartella:
```
.claude/skills/
├── deploy-to-prod/
│ ├── SKILL.md
│ └── scripts/
│ └── check-migrations.sh
├── weekly-content-plan/
│ └── SKILL.md
└── triage-support-tickets/
└── SKILL.md
```
Ogni cartella è una skill. Il file `SKILL.md` è un Markdown con YAML frontmatter in cima e normali istruzioni sotto. Quando un utente dice «dispieghiamo in produzione», Claude vede la description della skill `deploy-to-prod`, riconosce il trigger «dispiega in produzione», carica il corpo di SKILL.md nel contesto e segue i passaggi.
### Tre livelli di caricamento progressivo
Anthropic ha progettato le skills con un caricamento progressivo: i dati vengono caricati a strati, secondo necessità. Nel blog Anthropic Engineering, il team lo descrive come il «principio di progettazione fondamentale che rende Agent Skills flessibile e scalabile» ([Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)).
I tre livelli di caricamento:
1. **Metadati (sempre)** - quando inizia una sessione, Claude vede solo `name` e `description` di ogni skill. Budget: circa 100 token per skill.
2. **Istruzioni (al trigger)** - quando l’utente dice qualcosa di pertinente, Claude carica nel contesto il corpo di SKILL.md. Budget: meno di 5000 token.
3. **Risorse (su richiesta)** - i file inclusi (esempi, modelli, set di dati) vengono recuperati solo quando è il modello stesso a cercarli. Budget: illimitato.
In precedenza, [CLAUDE.md](https://ailoot.ai/blog/it/claude-md-template/) doveva contenere tutto ciò che l’IA doveva «ricordare» e un progetto con 50 regole raggiungeva rapidamente il limite del contesto. Con le skills, in un progetto possono convivere facilmente decine di procedure, perché nel contesto iniziale entrano solo le loro description.
### Dove si trovano le skills: quattro livelli
| Livello | Percorso | Si applica a |
|------------|-----------------------------------|--------------------|
| Enterprise | Impostazioni gestite dell’organizzazione | Tutti gli utenti dell’azienda |
| Personale | `~/.claude/skills//SKILL.md` | Tutti i tuoi progetti |
| Progetto | `.claude/skills//SKILL.md` | Solo questo progetto |
| Plugin | `/skills//SKILL.md` | Dove è abilitato il plugin |
Priorità: enterprise prevale su personale, personale prevale su progetto. I plugin usano lo spazio dei nomi `plugin-name:skill-name` e non entrano in conflitto. È comodo: metti le skills professionali generali in `~/.claude/skills/` e quelle specifiche del progetto nel repository, in `.claude/skills/`.
## Che cosa contiene SKILL.md?
Punti chiave
SKILL.md è un file Markdown con YAML frontmatter in cima e testo con le istruzioni sotto. Come minimo ha due campi: name (fino a 64 caratteri) e description (fino a 1024 caratteri). Lo schema completo comprende allowed-tools, disable-model-invocation, paths, context: fork, agent e hooks. Anthropic consiglia di mantenere il corpo delle istruzioni entro 500 righe e mettere tutto il resto in file di riferimento vicini.
Ecco un esempio minimale: venti righe e la skill è pronta:
```markdown
---
name: weekly-content-plan
description: Prepares a weekly post plan for a Telegram channel and short-form videos. Triggers - "make a post plan", "what should I post this week", "a 7-day channel plan". Do not activate if the request is about a website or email newsletter.
---
# Weekly Content Plan
## Steps
1. Read `knowledge/audience.md` - who we're writing for
2. Read `knowledge/tone-of-voice.md` - how we write
3. Read the last 10 posts in the channel - what has already been covered
4. Come up with 7 topics for the week: 3 sales-focused, 2 expert, 2 personal
5. For each, provide one hook line and three bullets about the post
6. Output as a table: day of the week | type | hook | plan
```
Basta così. Se un utente scrive «pianifichiamo i post della settimana», Claude trova il trigger nella description, carica SKILL.md, legge i file indicati e restituisce una tabella.
### Limiti da tenere presenti
La [documentazione ufficiale dell’API Claude](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) stabilisce limiti rigorosi:
- **`name`**: fino a 64 caratteri, solo lettere minuscole, numeri e trattini, senza tag XML. `anthropic` e `claude` sono riservati.
- **`description`**: fino a 1024 caratteri nell’API; obbligatoria, senza tag XML.
- **Budget dell’elenco**: in Claude Code, le description di tutte le skills insieme occupano circa l’1% della finestra di contesto. Se le skills sono molte, le description vengono troncate e potrebbero sparire le parole chiave che Claude deve usare per abbinarle.
- **Corpo di SKILL.md**: Anthropic consiglia di mantenerlo entro 500 righe. Sposta il materiale più lungo nei file `references/`, `scripts/` ed `examples/` e indica nelle istruzioni di caricarli.
Dopo la compattazione del contesto (`/compact`), Claude conserva i primi 5000 token di ogni skill richiamata in precedenza; il budget totale per tutte le skills ricollegate è di 25 000 token. Se una skill non ci sta, il suo comportamento viene «dimenticato».
### Schema completo del frontmatter
Come minimo, usa `name` e `description`. Le skills per la produzione usano anche altri campi:
| Campo | Funzione | Esempio |
|----|----|----|
| `name` | Nome della skill; se omesso, il valore predefinito è il nome della cartella | `deploy-to-prod` |
| `description` | Trigger per l’invocazione automatica | Vedi la formula sotto |
| `when_to_use` | Frasi trigger aggiuntive | `["deploy", "let's ship it"]` |
| `allowed-tools` | Quali strumenti si possono usare senza chiedere il permesso | `["Read", "Bash(npm run build)"]` |
| `disable-model-invocation` | `true` - può invocarla solo l’utente | Per operazioni pericolose |
| `user-invocable` | `false` - può invocarla solo Claude | Per conoscenze di sfondo |
| `paths` | Pattern glob in cui la skill è attiva | `["src/**/*.ts"]` |
| `context: fork` | Esecuzione in un subagent isolato | Quando il contesto è pesante |
| `agent` | Tipo di subagent da avviare | `Explore`, `Plan`, `general-purpose` |
| `effort` | Livello di ragionamento | `low`, `medium`, `high`, `xhigh`, `max` |
| `model` | Modello da assegnare alla skill | `claude-opus-4-7` |
| `hooks` | Hook sul ciclo di vita della skill | Vedi la sezione sugli hooks |
Il campo `disable-model-invocation: true` è indispensabile per tutto ciò che non deve essere eseguito automaticamente. Per esempio, una skill `deploy-to-prod` con questo flag può essere invocata solo se l’utente digita esplicitamente `/deploy-to-prod`. Senza il flag, Claude potrebbe eseguire il deploy perché «il codice sembra pronto».
## Perché la description costituisce il 90% del lavoro e come scriverne una?
Punti chiave
All’inizio di una sessione, Claude vede solo il campo description. Se è scritto male, la skill non funzionerà anche se il corpo delle istruzioni è perfetto. Una buona description ha tre parti: che cosa fa + frasi trigger tra virgolette + quando NON usarla. Nel suo `skill-creator`, Anthropic consiglia di rendere le description «un po’ insistenti»: Claude tende a non attivare abbastanza le skills.
L’errore più comune di chi fa vibe coding è scrivere una description come «Helper for X». La skill esiste materialmente nella sua cartella, ma Claude non la invoca.
### Una description sbagliata
```yaml
description: Build dashboards.
```
Quello che Claude non può capire: quando l’utente chiede «mostrami le vendite della settimana», si parla di una dashboard? Quando chiede un «grafico delle entrate», si parla di una dashboard o di un grafico in generale? Quando chiede un «report mensile», non si tratta di sicuro di una dashboard?
Il `skill-creator` [di Anthropic](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) formula direttamente la raccomandazione:
Claude attualmente tende a non attivare abbastanza le skills, cioè a non usarle quando sarebbero utili. Per contrastare questa tendenza, rendi le description delle skills un po’ «insistenti».
— Anthropic Skill Creator (SKILL.md), https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md
### La formula per una buona description
Tre parti:
1. **Che cosa fa** - una frase sul risultato, non sul processo. Non «genera SQL», ma «esporta le vendite in una tabella per un canale Telegram».
2. **Quando attivarla** - 3-5 frasi tra virgolette che gli utenti dicono davvero. Non tirare a indovinare; guarda le tue chat e la cronologia del supporto.
3. **Quando NON attivarla** - 1-2 frasi su attività simili a cui la skill non dovrebbe rispondere. Senza questa sezione, due skills simili continueranno a entrare in conflitto.
Un esempio di description efficace dal mio progetto (semplificato e anonimizzato):
```yaml
description: |
Scrive e pubblica una guida SEO sul blog, seguendo le linee editoriali.
Trigger: "scrivi una guida su X", "creiamo un nuovo pillar",
"un articolo del blog su Y", "crea una guida per il blog su Z".
Non attivare se la richiesta riguarda una newsletter email,
un post Telegram o un’istruzione interna per il team:
sono altre skills.
```
Perché funziona:
- Il verbo «scrive e pubblica» invece di «aiuta con» specifica un risultato concreto.
- Quattro frasi trigger tra virgolette coprono formulazioni diverse.
- Include anche un trigger in inglese: se l’utente passa alla lingua del team, la skill funziona comunque.
- Una sezione «non attivare se» separata evita conflitti con le skills per email e post.
### Come testare una description
Nel suo `skill-creator`, Anthropic ha integrato una metodologia di trigger-evals: 20 prompt per verificare se una skill si attiva. Dieci dovrebbero attivarla e dieci no (comprese situazioni simili in cui la formulazione è vicina, ma l’attività è diversa).
In termini di vibe coding, significa che dopo aver scritto la description apri una chat vuota e provi 5 frasi che usi davvero, più 3 frasi simili che vogliono dire un’altra cosa. Se la skill non si attiva quando dovrebbe, o si attiva quando non dovrebbe, modifica la description. Solo dopo scrivi il corpo delle istruzioni.
## Quali 5 skills installerei per prime?
Punti chiave
La strategia più rapida per un imprenditore è partire da raccolte già pronte e personalizzarle. Anthropic e Vercel hanno pubblicato raccolte pubbliche installabili con un solo comando, che coprono attività tipiche come documenti e design. A maggio 2026, il repository ufficiale `anthropics/skills` aveva circa 138.000 stelle.
Passare le prime due settimane a scrivere skills da zero è una strategia perdente. Inizia installando quelle già pronte e osservando come sono fatte; poi aggiungi le tue seguendo lo stesso approccio. Prendere raccolte collaudate create da altri e adattarle alle tue esigenze costa meno che costruire tutto da zero. Ecco cinque raccolte da cui partirei:
### 1. anthropics/skills - raccolta ufficiale con skill-creator
Repository: [github.com/anthropics/skills](https://github.com/anthropics/skills). 138,000 stelle su GitHub. Contiene le skills ufficiali del team Anthropic: `skill-creator` (una meta-skill che scrive altre skills), `claude-api` (aiuta a creare integrazioni API) e skills per lavorare con documenti PowerPoint, Excel, Word e PDF.
Installa con Claude Code:
```bash
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
```
Il valore principale è `skill-creator`. Crea un SKILL.md a partire dalla tua description, poi esegue 20 trigger-evals e modifica la description finché la skill non inizia ad attivarsi nei casi giusti. In sostanza, è «una skill per creare skills».
### 2. mattpocock/skills - la raccolta virale di un esperto di TypeScript
Contiene 12 skills attive, tra cui:
Installa:
```bash
npx skills@latest add mattpocock/skills
/setup-matt-pocock-skills
```
### 3. coreyhaines31/marketingskills - una raccolta per chi si occupa di marketing
Se gestisci programmi online, lavori come freelance nel marketing o gestisci un’agenzia, non devi passare sei mesi a scrivere le tue skills. Metà delle attività sono già pronte.
### 4. vercel-labs/agent-skills - design senza l’aspetto da IA
Repository: [github.com/vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills). La sua skill di punta è `web-design-guidelines`. Verifica il codice UI rispetto a regole di accessibilità, prestazioni e usabilità.
A questa si affianca [frontend-design di Anthropic](https://github.com/anthropics/skills/tree/main/skills/frontend-design), con oltre 110,000 installazioni settimanali. Fa scegliere all’IA uno stile prima di iniziare a scrivere codice. Senza, ogni pagina generata da Claude usa il font Inter, un gradiente viola e card disposte a griglia. Il risultato è uguale per tutti.
### 5. obra/superpowers - flusso di lavoro multi-agent
In generale, installando le prime tre di questo elenco - `anthropics/skills`, `mattpocock/skills` e `coreyhaines31/marketingskills` - Claude Code avrà decine di skills già pronte che coprono la maggior parte delle attività di un imprenditore nel primo mese.
Vuoi non solo installare skills già pronte, ma anche creare **una configurazione che trasformi Claude nel tuo vero assistente**? Le skills sono uno dei tre pilastri della metodologia. La configurazione funzionante ha tre parti: **clone IA** (skills come competenze confezionate) + **[Second Brain](https://ailoot.ai/blog/it/claude-code-second-brain/)** (una struttura di conoscenze per il contesto) + **Context Engineering** (il modo in cui Claude vede il progetto nel suo insieme). Questa configurazione trasforma Claude da assistente che tira a indovinare in uno strumento che ragiona secondo la tua logica.
## Quali attività ripetitive dovresti trasformare in una skill?
Punti chiave
La regola è semplice: qualsiasi attività che svolgi più di due volte a settimana e segue all’incirca gli stessi passaggi è candidata a diventare una skill. Non un complesso «report annuale per il revisore», ma attività di routine: un piano editoriale per un canale, il controllo delle ricevute dei clienti, un’email di benvenuto per un nuovo partecipante. Una skill trasforma un’attività occasionale in una risorsa che funziona senza di te.
Nel lavoro con i clienti e nei progetti altrui, ho visto questo schema decine di volte. Qualcuno ha «quella cosa che fa ogni volta da zero». Ogni lunedì scrive lo stesso tipo di report. Ogni volta che arriva un nuovo cliente, segue la stessa procedura. Ogni pubblicazione segue lo stesso modello. E ogni volta ci vogliono 30-90 minuti, perché bisogna ricordare i passaggi, aprire i file giusti e formulare di nuovo il prompt per Claude.
La soluzione è confezionare il procedimento in una skill una volta sola. Dopodiché basta dire una frase e Claude carica la metodologia, legge le fonti necessarie e produce il risultato. Tre esempi di settori diversi:
### Esempio 1. Marketer freelance - skill `weekly-content-plan`
Attività manuale: ogni lunedì prepara i post Telegram della settimana per tre clienti. Apre la guida alla voce del brand del cliente, rivede i post recenti, pensa agli argomenti in base al calendario dei prodotti e prepara una tabella con hook e punti elenco.
Come skill, diventa un’istruzione in cinque passaggi: leggere il file del tono di voce del cliente, leggere il calendario dei prodotti, controllare gli ultimi 10 post per evitare ripetizioni, ideare sette argomenti suddivisi per tipologia (vendite, competenza, personale) e restituire una tabella.
Il comando «pianifichiamo i post della settimana per il cliente X» trasforma un’ora di preparazione in tre minuti di attesa. Il marketer controlla il risultato, fa modifiche mirate e lo invia al cliente.
### Esempio 2. Commercialista esterno - skill `monthly-receipts-close` (esempio dell’autore)
Attività manuale: per ogni cliente del portafoglio, ogni mese esporta l’estratto conto, lo riconcilia con i pagamenti nel sistema contabile, segnala quelli non classificati, prepara un report preliminare sui ricavi e confronta la struttura dei ricavi con quella del mese precedente.
La skill è un’istruzione in sei passaggi più un paio di script shell nella cartella `scripts/` per analizzare gli estratti conto. Il trigger «chiudi maggio per il cliente X» induce Claude a produrre in 4-5 minuti un report con le anomalie segnalate.
### Esempio 3. Creatore di programmi online - skill `welcome-letter-new-participant`
Attività manuale: un nuovo partecipante ha pagato e bisogna scrivergli un’email di benvenuto. Un buon messaggio è personale: tiene conto del canale da cui è arrivato, del prodotto acquistato, della coorte a cui appartiene e dei materiali da inviargli. Un modello del tipo «ciao, siamo felici» non basta.
La skill indica a Claude di leggere `knowledge/audience.md` (chi sono queste persone), `knowledge/products/.md` (che cosa ricevono) e le ultime tre email di benvenuto (per evitare ripetizioni), poi di scrivere l’email con questa struttura: aggancio - dettagli del prodotto - primi tre passaggi - saluto.
È molto più veloce che farlo a mano. La qualità è più costante perché Claude si ricorda di consultare tre fonti, mentre chi ha fretta ne salta una.
### Che cosa NON trasformare in una skill
- **Attività una tantum**. Se la fai una volta all’anno per la dichiarazione dei redditi, basta descriverla a Claude in chat. Una skill ripaga dopo 3+ ripetizioni.
- **Attività troppo generiche**. «Aiutami con il marketing» non è una skill; comprende tutto il marketing. Una skill è «un piano editoriale settimanale»: un’attività specifica con un risultato specifico.
- **Attività senza passaggi ripetibili**. Se il processo cambia ogni volta, non è una skill, ma un’attività occasionale.
## Come fa Skill Creator a scrivere skills per te?
Punti chiave
Skill Creator è una meta-skill di Anthropic, lanciata con il comando `/skill-creator`. Ti guida attraverso sei passaggi: bozza, test, valutazione, iterazione, ottimizzazione e confezionamento. Il risultato è un SKILL.md pronto all’uso, testato con 20 trigger-evals (10 che dovrebbero attivarsi e 10 che non dovrebbero). Per chi non programma, è il modo più rapido per scrivere una prima skill funzionante, senza dover capire YAML o discutere con Claude.
Il problema è che scrivere bene una skill al primo tentativo è difficile. Spesso la description è troppo circoscritta o troppo ampia, non include le frasi che gli utenti usano davvero oppure entra in conflitto con una skill simile. Anthropic ha affrontato il problema pubblicando [skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md), una meta-skill che può crearne altre.
Dopo aver installato `anthropics/skills`, dì a Claude `/skill-creator` (o semplicemente «creiamo una skill per il report settimanale») e segui un flusso di lavoro in sei fasi:
1. **Bozza** - skill-creator pone domande: che cosa dovrebbe fare la skill, quali frasi trigger usare, quali fonti leggere e quali passaggi seguire. Il risultato è la prima versione di SKILL.md.
2. **Test** - skill-creator genera 20 prompt di test: 10 che dovrebbero attivare la skill e 10 che sembrano trigger ma non dovrebbero farlo (quasi corrispondenze).
3. **Valutazione** - esegue ogni prompt in una chat nuova e verifica se la skill si è attivata. Se si attiva quando non dovrebbe o non si attiva quando dovrebbe, segnala il risultato.
4. **Iterazione** - riscrive la description in base agli errori e ripete i test.
5. **Ottimizzazione** - rifinitura finale: verifica se si supera il limite di 1024 caratteri e se ci sono conflitti con le skills già presenti nel progetto.
6. **Confezionamento** - organizza SKILL.md e i file di riferimento nella struttura corretta.
In pratica, funziona così: parli con Claude per 15-20 minuti, rispondi a 7-8 domande di chiarimento e alla fine ottieni una skill pronta e testata che si attiva con i trigger giusti.
Un altro vantaggio è che `skill-creator` mostra uno stile esemplare per scrivere SKILL.md. Puoi aprire il suo file e vedere il formato, il tono e la struttura dei passaggi. È uno strumento che mostra da sé come usarlo: lo leggi e impari a scrivere le tue skills.
## Skills, CLAUDE.md, subagents, MCP, hooks: quale usare?
Punti chiave
Claude Code ha cinque elementi distinti per estenderne il comportamento e non sono intercambiabili. CLAUDE.md contiene conoscenze permanenti sul progetto. Le skills sono flussi di lavoro ripetibili attivati da trigger. I subagent svolgono attività in parallelo in un contesto separato. MCP collega sistemi esterni (API, database). Gli hooks reagiscono automaticamente agli eventi. L’errore più comune di chi fa vibe coding è mettere tutto in CLAUDE.md o provare a creare una skill con un hook.
Il problema più comune nei progetti che ho esaminato è che CLAUDE.md contiene insieme regole del progetto, istruzioni passo passo per la pubblicazione, un modello di commit e una descrizione del database. Questo sovraccarica il contesto e, nella pratica, non funziona: Claude non esegue l’istruzione «quando l’utente chiede di pubblicare», perché il modello tratta tutto CLAUDE.md come contesto generale privo di trigger espliciti.
La soluzione consiste nell’assegnare ogni elemento all’elemento giusto:
| Che cosa | Quando usarlo | Esempio |
|----|----|----|
| **CLAUDE.md** | Conoscenze necessarie SEMPRE | «Il progetto usa una lingua specifica», «niente trattini lunghi nei testi», «il brand si scrive con una “o”» |
| **Skills** | Un processo ripetibile attivato da un trigger | «Pubblica in produzione», «piano dei post settimanale», «chiudi la contabilità del cliente per il mese» |
| **Subagents** | Lavoro in parallelo o isolamento di un contesto pesante | «Audit di sicurezza mentre pianifico una nuova funzionalità», «rivedi il codebase in una sessione separata» |
| **MCP** | Collegamento a un sistema esterno | «Recupera i dati dal CRM», «prendi le attività dal tracker», «controlla il sito in un browser» |
| **Hooks** | Risposta automatica a un evento | «Esegui un controllo dopo Edit», «blocca i comandi pericolosi», «invia una notifica Telegram al termine» |
In breve, il quadro si riduce a una logica semplice: Skills e MCP coprono la maggior parte dei flussi di lavoro; gli hooks automatizzano le attività di routine, come controlli del codice, test e misure di protezione. I subagent servono quando il contesto diventa pesante. L’errore più comune è creare un subagent quando basterebbe una skill.
### Albero decisionale
Quando pensi «mi serve che Claude faccia X»:
1. **È una conoscenza necessaria in ogni momento?** Per esempio, «il progetto usa una lingua specifica» o «non usiamo trattini lunghi». → Mettila in `CLAUDE.md`.
2. **È una procedura attivata da un trigger che ora svolgi a mano?** Per esempio, «scrivo un report ogni lunedì». → Crea una **skill**.
3. **Ti serve accesso a un sistema esterno?** Per esempio, l’API di Stripe o il tuo CRM. → Collega un **server MCP**.
4. **Claude Code dovrebbe reagire automaticamente a un evento?** Per esempio, eseguire un linter dopo ogni Edit. → Scrivi un **hook**.
5. **L’attività è pesante, consumerà tutto il contesto e devi fare qualcos’altro in parallelo?** → Eseguila in un **subagent**.
Il 90% delle attività di un imprenditore che fa vibe coding rientra nelle categorie 1-3. Hooks e subagent sono strumenti di livello successivo, per chi è andato oltre «un’attività alla volta».
### I comandi slash e le skills sono la stessa cosa
Un cambiamento importante in Claude Code: il vecchio sistema dei comandi slash (`.claude/commands/`) e le skills si sono di fatto fusi. Il file `.claude/commands/deploy.md` e il file `.claude/skills/deploy/SKILL.md` creano entrambi un comando `/deploy`. Se i nomi corrispondono, prevale la skill. Quindi, se usi ancora il vecchio formato dei comandi slash, passa alle skills: la sintassi è più chiara e offre più funzionalità.
## 7 errori che impediscono a una skill di funzionare
Punti chiave
I problemi più comuni delle skills non sono bug di Claude, ma errori nella skill stessa. Una description senza trigger, un SKILL.md sovraccarico di 2,000 righe, due skills simili in conflitto o il tentativo di scaricare «tutto il marketplace». Ognuno di questi errori compromette l’attivazione della skill o il suo funzionamento.
### 1. Description senza trigger: la skill non si attiva
Sintomo: hai scritto una skill, verificato la struttura e tutto è valido, ma Claude non la invoca quando l’utente fa una richiesta. La causa è quasi sempre la stessa: una description come «Helper for content writing». Claude non sa a quali frasi rispondere. Soluzione: inserisci nella description 3-5 frasi effettivamente usate dagli utenti, tra virgolette.
### 2. SKILL.md oltre 500 righe: l’attenzione si disperde
Anthropic [consiglia esplicitamente](https://code.claude.com/docs/en/skills) di mantenere il corpo del file entro 500 righe. Se le istruzioni sono lunghe 2,000 righe, Claude perde la concentrazione, segue solo in parte i passaggi e si confonde sull’ordine. Soluzione: sposta le sezioni più lunghe in file vicini, come `examples/`, `references/`, `scripts/`, e rimandavi da SKILL.md.
### 3. Una skill per «tutto sui contenuti» invece di tre più piccole
Una configurazione allettante: una grande skill `content` che comprende post Telegram, landing page ed email. Non funziona. La skill si attiva per le richieste sbagliate, mescola metodologie e produce un risultato medio. Soluzione: una skill = un’azione ripetibile. Se hai davvero tre routine legate ai «contenuti», crea tre skills: `telegram-post`, `landing-section`, `email-broadcast`.
### 4. Skill senza una sezione «quando NON usarla»: conflitti
Sintomo: nel progetto ci sono due skills simili e Claude invoca quella sbagliata. Per esempio, una skill riguarda una newsletter email e un’altra le email di benvenuto per i partecipanti a un programma. Senza una clausola esplicita come «non attivarla se la richiesta riguarda una mailing list generale», la skill per le email di benvenuto si attiverà a ogni menzione di «email». Soluzione: specifica nella description i casi negativi.
### 5. 50 skills in un progetto: le description vengono troncate
Dalla [documentazione di Claude Code](https://code.claude.com/docs/en/skills):
I nomi delle skills sono sempre inclusi, ma se ce ne sono molte, le description vengono troncate per rispettare il limite di caratteri e potrebbero sparire le parole chiave che Claude usa per abbinare la tua richiesta. Budget - 1% della finestra di contesto del modello.
— Documentazione di Claude Code, https://code.claude.com/docs/en/skills
Se hai scaricato 50 raccolte di skills da un marketplace, alcune description verranno troncate. Le parole chiave su cui contavi potrebbero sparire. Soluzione: tieni nel progetto attivo le 10-15 skills più utili. Conserva le altre in un archivio inattivo esterno a tutte le directory in cui vengono rilevate le skill, per esempio una cartella `skill-archive/` separata tra i tuoi materiali. Installa nell’ambito del progetto o personale soltanto le skill necessarie. `~/.claude/skills/` è una libreria personale installata e visibile nei vari progetti: spostarvi le skill non le sottrae al rilevamento.
### 6. Skills da fonti non verificate: rischio per la sicurezza
Anthropic avverte di questo nella [documentazione ufficiale](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview):
Usa skills solo da fonti affidabili: create da te o ricevute da Anthropic. Una skill malevola potrebbe indurre Claude a chiamare strumenti o eseguire codice in modi diversi da quelli dichiarati nella sua funzione.
— Panoramica di Anthropic Agent Skills, https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Un repository GitHub casuale potrebbe contenere una skill che sottrae le tue chiavi API alla prima invocazione. Soluzione: apri SKILL.md e leggilo personalmente prima dell’installazione. Non eseguire skills di autori sconosciuti nei progetti importanti.
### 7. Una skill senza una cartella di conoscenze produce «ChatGPT medio»
L’anti-pattern più sottile e comune. Una skill è una metodologia, ma la metodologia da sola non significa nulla senza contesto. Se scrivi una skill «crea un’email di benvenuto», ma nel progetto non c’è un file che descrive il pubblico né un file sulla voce del brand, Claude scriverà un’email media da ChatGPT, indistinguibile da quella di chiunque altro.
Una skill funziona al meglio solo dopo aver creato la [Second Brain](https://ailoot.ai/blog/it/claude-code-second-brain/) del progetto secondo i principi della [guida su CLAUDE.md](https://ailoot.ai/blog/it/claude-md-template/). Prima crea la struttura di conoscenze, poi le skills che ne dipendono. Invertendo l’ordine, otterrai un lavoro generico e di qualità media, invece di un risultato personalizzato nel tuo stile.
## Come creare la tua prima skill in 30 minuti
Punti chiave
Una ricetta passo passo per creare la tua prima skill funzionante: scegli un’attività ripetibile, scrivi i passaggi, crea la struttura delle cartelle, scrivi la description usando la formula, testala con 5-8 prompt e ripeti finché non si attiva nei casi giusti. Una tempistica realistica per la prima skill è 30-40 minuti. Ogni successiva richiede 10-15 minuti perché il formato diventa familiare.
Ecco il piano concreto che ho usato per creare le prime skills nei miei progetti:
### Passaggio 1. Scegli un’attività ripetibile
Apri il calendario del mese scorso. Trova un’attività che hai svolto almeno 4-5 volte e che richiede 30-60 minuti ogni volta. Non un’attività generica di «marketing», ma qualcosa di specifico: «report delle vendite del lunedì», «accoglienza di un nuovo cliente» o «aggiornamento del listino per una promozione».
Più la descrizione è precisa, più la skill è semplice e il trigger è pulito.
### Passaggio 2. Descrivi a mano il processo
In un file separato o in una chat con Claude (non per la skill, ma come bozza), scrivi i passaggi che segui:
```
1. Apri il database dei clienti
2. Filtra per stato "in attesa dell’email di benvenuto"
3. Verifica da quale canale proviene il cliente
4. Recupera dalla cartella "templates" il modello email per quel canale
5. Inserisci il nome, il prodotto e la data di inizio
6. Invia
```
Non è ancora una skill, sono appunti. Ma senza questi appunti, iniziare a scrivere SKILL.md significa confondersi fin dall’inizio.
### Passaggio 3. Crea la struttura delle cartelle
```bash
mkdir -p .claude/skills/welcome-email-new-client
touch .claude/skills/welcome-email-new-client/SKILL.md
```
Oppure, se vuoi usare la skill in tutti i tuoi progetti, mettila in `~/.claude/skills/`.
### Passaggio 4. Scrivi SKILL.md usando il modello
Struttura:
```markdown
---
name: welcome-email-new-client
description: |
Prepares a welcome email for a new client using the template for their acquisition channel.
Triggers: "write a welcome email for new client X",
"onboard new participant Y", "welcome email for client from channel Z".
Do not activate if the request is about a general mailing list
or an email campaign—those are other skills.
---
# Welcome Email for a New Client
## Steps
1. Read `knowledge/audience/segments.md` - what client segments we have
2. Read `knowledge/templates/welcome/` - templates by channel
3. Identify the client's channel from the request context
4. Insert the client's name, product name, and start date
5. Check the length—it should be no more than 800 characters
6. Output the final email text in a copy-ready format
## Important
- Non usare "caro amico" o "ciao"; usa un linguaggio naturale
- Un paragrafo, un’idea
- Concludi con un invito all’azione, non due
```
### Passaggio 5. Prova con 5-8 prompt
Apri una chat vuota con Claude Code in questo progetto. Prova 5 frasi che usi davvero e 3 simili che non dovrebbero attivare la skill:
Dovrebbe attivarsi:
- «Scrivi un’email di benvenuto per il nuovo cliente Ivanov»
- «Accogli un nuovo partecipante che ha acquistato il programma X»
- «Email di benvenuto per un cliente arrivato da Instagram»
Non dovrebbe attivarsi:
- «Invia un’email promozionale a tutta la lista»
- «Campagna email per le festività di Capodanno»
- «Scrivi un follow-up a un cliente che non ha pagato»
Per ciascuno, verifica se la skill si è attivata. Se si attiva nei casi sbagliati, restringi la description. Se non si attiva quando dovrebbe, amplia le frasi trigger.
### Passaggio 6. Itera sulla description
Dopo ogni test fallito, modifica solo la description, senza toccare il corpo delle istruzioni. Dopo 2-3 iterazioni, la skill inizia ad attivarsi in modo affidabile. Salvala, sottoponila a commit e poi usala ogni giorno.
Consiglio finale: non cercare di rendere perfetta la tua prima skill. Falla funzionare. La rifinitura viene dopo la quinta o decima skill, quando inizi a vedere schemi nel modo in cui formuli le richieste e nelle risposte di Claude.
Scegli per questa settimana un’attività ricorrente dal calendario, riservati 30 minuti e segui i sei passaggi qui sopra. Così Claude lavorerà secondo la tua metodologia, invece di tirare a indovinare.
### Fonti
- [Estendere Claude con le skills - Documentazione di Claude Code](https://code.claude.com/docs/en/skills)
- [Panoramica di Agent Skills - Documentazione della piattaforma Claude](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Fornire agli agenti gli strumenti per il mondo reale con Agent Skills - Blog Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [anthropics/skills - repository ufficiale con skill-creator](https://github.com/anthropics/skills)
- [Skill Creator SKILL.md - fonte della metodologia trigger-evals](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)
- [vercel-labs/agent-skills - linee guida di design](https://github.com/vercel-labs/agent-skills)
- [Standard aperto Agent Skills - specifica](https://agentskills.io)
La configurazione funzionante è **clone IA + Second Brain + Context Engineering**. Tre parti di un’unica metodologia.
Se ti serve accedere ai modelli di IA tramite Ailoot, dai un’occhiata ad [Ailoot](https://ailoot.ai/).
## Domande frequenti
### Spostare una skill in ~/.claude/skills/ la rende inattiva?
No. È la directory personale delle skill installate, disponibili nei tuoi progetti. Conserva i pacchetti inutilizzati in un archivio esterno a tutte le directory in cui le skill vengono rilevate, poi installa soltanto quelle necessarie al momento.
### Come verifico se una description attiva la skill correttamente?
Prova cinque frasi che dovrebbero richiamarla e tre richieste simili che non dovrebbero farlo. Usa chat nuove, registra quale skill viene caricata e modifica la description quando manca una richiesta valida o intercetta un caso solo simile.
## Ailoot · L’azienda e il suo portafoglio di progetti
Ailoot si basa su un’esperienza operativa consolidata, un’ampia base di clienti, un servizio stabile e un controllo costante dei KPI.
L’azienda e il suo portafoglio di progetti: milioni di clienti; vendite nell’ordine dei miliardi ogni mese.
Ailoot mette questa esperienza operativa al servizio dell’accesso API alle funzioni AI nei prodotti dei clienti, negli agenti, nelle applicazioni e nelle automazioni.