Una Claude Skill non è un prompt lungo: è un file che Claude decide quando leggere

Le Skills sono il motivo per cui Claude non è un chatbot. Sono istruzioni persistenti che trasformano un modello generico in uno specialista del tuo dominio. Ne ho una settantina sul disco, di cui venti agganciate a un task che parte da solo [N=1, il mio sistema: 77 file SKILL.md e 20 task abilitati nello store Cowork, contati il 27 luglio 2026]. Ecco come crearne una da zero in 15 minuti, e soprattutto come non sbagliare la parte che conta.

Prima però una precisazione che vale tutto il resto dell'articolo. La maggior parte delle guide che trovi in giro descrive una Skill come "un prompt riutilizzabile". Il discorso è che non è così, ed è la ragione più frequente per cui una Skill scritta bene non parte mai. Un prompt lo passi tu, quando decidi tu. Una Skill sta ferma sul filesystem finché Claude non decide, da solo, che serve. La differenza non è cosmetica: cambia completamente cosa devi scrivere dentro il file.

Cosa sono le Claude Skills (e perché non sono un prompt lungo)

Una Skill è una cartella che contiene un file SKILL.md, più eventuali file di supporto e script. Non è un file singolo perso in una chat, e non è un preset: un preset lo scegli tu da un menu, una Skill se la sceglie Claude.

Il meccanismo che la rende diversa da un prompt si chiama progressive disclosure, e la documentazione ufficiale di Anthropic lo descrive su tre livelli. Vale la pena capirlo bene perché è l'unica cosa che devi avere in testa mentre scrivi:

1. Livello 1, i metadati. name e description dal frontmatter YAML. Vengono caricati sempre, all'avvio, dentro il system prompt. La tabella della documentazione Agent Skills li quota a circa 100 token per Skill, ed è il motivo per cui puoi installarne molte senza pagare pegno in context window. In Claude Code il conto si fa in modo diverso e conviene saperlo: il budget dell'elenco è a caratteri, pari all'1% della context window del modello, con description e when_to_use troncate insieme a 1.536 caratteri. Quando l'elenco sfora, Claude Code inizia a tagliare le description delle Skill che invochi meno. Fonte: Claude Code — Skills, consultato il 2026-08-12.
2. Livello 2, le istruzioni. Il corpo di SKILL.md. Entra in contesto solo quando la Skill viene attivata, cioè quando Claude legge il file dal filesystem. La documentazione consiglia di stare sotto i 5k token.
3. Livello 3, le risorse. File markdown aggiuntivi, script eseguibili, template, schemi. Costano zero finché nessuno li apre. Gli script sono il caso più interessante: Claude li esegue via bash e in contesto entra solo il loro output, non il codice.

Il punto è questo: la Skill non è un blocco di testo che spingi dentro il modello. È un albero di informazioni che il modello attraversa solo per il ramo che gli serve. Chi scrive Skill come se fossero prompt lunghi paga due volte, in token e in precisione.

Se vuoi il contesto più ampio su come Claude usa i file che gli dai da leggere, ho scritto anche di come dare contesto all'AI con i documenti e non solo con il prompt: stesso principio, applicato al lavoro quotidiano invece che al filesystem.

Anatomia di un file SKILL.md

La struttura minima è sorprendentemente povera: un frontmatter di due righe e del markdown sotto.

---
name: monitor-ricerca-settimanale
description: Monitora Google Search Console ogni lunedì mattina. Estrae click, impressioni e posizione media via service account, calcola il delta rispetto alla settimana precedente e aggiorna la sezione di report. Usare quando serve il monitoraggio SEO settimanale o quando l'utente chiede "com'è andata la settimana su Search Console".
---

# Monitor ricerca settimanale

## Missione
Sei il monitor settimanale di Search Console. Non generi contenuto:
raccogli dati, li confronti, scrivi un delta leggibile.

## Step 1: raccogli i dati
Lancia lo script di fetch con il service account configurato.
Output atteso: un file JSON e un file markdown nella cartella dei report.

## Step 2: calcola i delta
Confronta con il report della settimana precedente. Per ogni metrica
riporta valore assoluto, delta e segno.

## Step 3: scrivi il report
Formato fisso, tre righe di sintesi in testa, poi il dettaglio.

## Error handling
Se lo script di fetch fallisce: non inventare numeri. Scrivi
"fetch fallito" con il messaggio di errore e fermati.

Questo è un esempio reale, ripulito e generalizzato, di come è fatta una delle Skill che ho in produzione. Guarda cosa c'è e cosa non c'è.

I campi obbligatori dipendono da dove gira la Skill

Qui c'è il punto che quasi tutte le guide appiattiscono, e che ti fa scrivere una Skill che si comporta diversamente da come te l'aspettavi. Le regole del frontmatter non sono una sola: cambiano a seconda della superficie. Le due pagine di documentazione dicono cose opposte, e hanno ragione entrambe perché parlano di due implementazioni diverse.

Sulla Skills API e sulle Skill caricate su claude.ai vale la documentazione Agent Skills, che scrive "Required fields: name and description" e impone una validazione:

• name: massimo 64 caratteri, solo lettere minuscole, numeri e trattini. Niente tag XML. Non può contenere le parole riservate "anthropic" e "claude".
• description: non vuota, massimo 1024 caratteri, niente tag XML.
• Il corpo di SKILL.md dovrebbe stare sotto i 5k token.

In Claude Code, dove le Skill sono cartelle sul filesystem e non passano da nessun endpoint, la pagina Skills dice il contrario, testualmente: "All fields are optional. Only description is recommended". Nel dettaglio:

• name è marcato "Required: No" e per default prende il nome della cartella. In una Skill personale o di progetto è solo l'etichetta mostrata nell'elenco: il comando che digiti resta il nome della directory.
• description è "Recommended", non obbligatoria: se manca, Claude Code usa il primo paragrafo del markdown. Il limite che conta non è 1024 ma il troncamento a 1.536 caratteri di description e when_to_use messe insieme, e vale solo nell'elenco.
• I vincoli sui caratteri e le parole riservate non ci sono. La prova ce l'hai installata: Claude Code distribuisce di serie una Skill che si chiama claude-api, e la invochi con /claude-api. Quel nome contiene una parola riservata e sulla Skills API non passerebbe la validazione.
• La raccomandazione sulla lunghezza è espressa in righe, non in token: "Keep SKILL.md under 500 lines".

Cosa farne in pratica. Se scrivi solo per Claude Code puoi permetterti un frontmatter di due righe scarse, ma conviene comunque riempire name e description come se fossero obbligatori e rispettare i vincoli più stretti, quelli API. Costa zero adesso e ti evita di riscrivere tutto il giorno che quella Skill la vuoi caricare via API o su claude.ai. Al contrario, se scrivi per l'API e ti abitui ai default di Claude Code, la prima cosa che vedi è un errore di validazione.

Su una cosa le due pagine sono d'accordo, ed è quella che conta davvero: la description deve dire cosa fa la Skill e quando Claude dovrebbe usarla. Ci torno tra un attimo.

Il corpo: identità, contesto, regole, output, error handling

Il corpo di SKILL.md è markdown normale. La documentazione suggerisce una struttura a istruzioni ed esempi, ma la forma che uso io, e che regge meglio quando la Skill gira in un task schedulato senza nessuno che guarda, è questa:

1. Identità. Una frase che dice chi è Claude mentre esegue questa Skill. "Sei il monitor settimanale di Search Console". Sembra una formalità, non lo è: taglia via metà delle derive.
2. Contesto. I file da leggere prima di agire, con path espliciti. Se la Skill dipende da un documento di regole, il posto per dirlo è qui, in cima, non a metà.
3. Regole e vincoli. Cosa non deve mai succedere. Le regole negative funzionano sensibilmente meglio delle positive: "non inventare numeri" è più efficace di "usa numeri reali".
4. Step operativi. Numerati, in ordine, con l'output atteso di ciascuno.
5. Formato di output. Se l'output finisce in un file, mostra il formato. Un esempio concreto vale dieci righe di descrizione.
6. Error handling. Errore, come lo rilevi, cosa fai, qual è il fallback, chi avvisi. È la sezione che tutti saltano ed è quella che decide se la Skill sopravvive in produzione.

I file di supporto

Quando il corpo supera le 200 righe, spezza. La struttura tipica:

seo-monitor/
├── SKILL.md          (istruzioni principali)
├── METRICHE.md       (definizione delle metriche, letto solo se serve)
├── FORMATO-REPORT.md (template di output)
└── scripts/
    └── fetch.py      (eseguito via bash, il codice non entra in contesto)

Il vantaggio è concreto. METRICHE.md può essere lungo quanto vuoi: costa zero finché Claude non lo apre. Uno script Python di 300 righe costa solo il suo output.

Questa è anche la ragione per cui gli script battono le istruzioni ogni volta che l'operazione è deterministica. Se una cosa si può calcolare, calcolala con codice. Una somma fatta da uno script è giusta sempre; la stessa somma fatta dal modello è giusta quasi sempre, che in produzione è una categoria completamente diversa.

Dove vivono le Skill

Qui la documentazione è netta, e conviene seguirla alla lettera perché è il punto in cui si perde più tempo:

• Claude Code, personali: ~/.claude/skills/<nome-skill>/SKILL.md. Disponibili in tutti i tuoi progetti.
• Claude Code, di progetto: .claude/skills/<nome-skill>/SKILL.md dentro il repo. Versionate con il codice, condivise con chi ci lavora.
• Plugin: le Skill possono essere distribuite come plugin, con namespace nome-plugin:nome-skill.
• claude.ai: si caricano come file zip dalle impostazioni, e restano individuali per utente.
• Claude API: si caricano tramite gli endpoint dedicati e sono condivise a livello di workspace.

Un dettaglio che costa ore a chi non lo sa: le Skill non si sincronizzano tra le superfici. La documentazione lo scrive senza sfumature, "Custom Skills do not sync across surfaces": una Skill caricata su claude.ai non è disponibile via API, e una che vive in ~/.claude/skills/ sulla tua macchina non esiste per una sessione cloud. Se una automazione schedulata in cloud invoca una Skill che hai solo in locale, quella Skill semplicemente non c'è, e Claude Code risponde che non l'ha trovata.

C'è però un'eccezione documentata, e ignorarla ti fa cercare il problema dove non è. Le sessioni Cowork, sia interattive sia schedulate, caricano le Skill abilitate sul tuo account claude.ai, sincronizzate all'avvio della sessione. Le gestisci da Customize nella sidebar dell'app desktop, o dalle impostazioni Skills su claude.ai. Le sessioni cloud, oltre a quelle, prendono anche le Skill di progetto committate nella .claude/skills/ del repo clonato. Quindi il canale di sincronizzazione esiste: passa dall'account, non dal filesystem, e va abilitato a mano una volta.

Ancora diverso il caso dei task schedulati desktop, che girano in locale sulla tua macchina e leggono le Skill dagli stessi posti di qualsiasi altra sessione locale. Tradotto: se il tuo scheduler è sul Mac, ~/.claude/skills/ va benissimo; se è in cloud, no.

I campi opzionali, e la differenza tra doc e file reali

Ecco un punto dove la documentazione dice molto più di quello che troveresti guardando i miei file. Ho contato: tutte e 77 le mie SKILL.md usano name e description, e nient'altro. Zero eccezioni. La documentazione di Claude Code, invece, espone una lista di campi opzionali molto più ricca:

• when_to_use: contesto aggiuntivo su quando invocare la Skill, frasi trigger, esempi di richiesta.
• allowed-tools: strumenti pre-approvati per il turno che invoca la Skill.
• disallowed-tools: strumenti rimossi dal pool mentre la Skill è attiva.
• disable-model-invocation: impedisce a Claude di caricare la Skill da solo, la lasci invocabile solo a mano.
• user-invocable: la nasconde dal menu dei comandi, per conoscenza di background che l'utente non deve lanciare.
• model ed effort: modello e livello di sforzo da usare mentre la Skill è attiva.
• context: fork, agent e background: eseguono la Skill dentro un subagent separato, con la possibilità di aspettarne il risultato invece di lasciarlo girare in background.
• paths: pattern glob che limitano quando la Skill si attiva.
• argument-hint e arguments: argomenti posizionali e suggerimenti di autocompletamento.
• hooks e shell: hook legati al ciclo di vita della Skill, e quale shell usare per i comandi inline.

Attenzione, perché è l'informazione che manca in tutte le guide che ho letto: questi campi esistono solo in Claude Code. Non sono parte del formato Agent Skills generale. Se prendi una SKILL.md che usa allowed-tools o context: fork e la carichi via Skills API o su claude.ai, quei campi non fanno assolutamente nulla: nel migliore dei casi vengono ignorati, e la Skill si comporta come se non li avessi mai scritti. Che è peggio di un errore, perché non te ne accorgi. Se una Skill deve girare su più di una superficie, la logica di controllo va nel corpo, non nel frontmatter.

Perché non li uso? Perché quasi tutte le mie Skill girano come task schedulati, dove non c'è nessuno che digita un comando e la sostituzione di argomenti non serve. Ma se stai scrivendo Skill per lavorare in interattivo dentro Claude Code, disable-model-invocation e allowed-tools sono i due che alzano di più la qualità della vita.

Da verificare: la disponibilità dei singoli campi opzionali dipende dalla versione di Claude Code che hai installata, e la documentazione lo segnala campo per campo (background, per dire, vuole la 2.1.218 o successiva). Controlla la pagina Skills della documentazione di Claude Code prima di dare per scontato che un campo esista nella tua versione.

La description è il vero punto di ingresso

La description non è una didascalia. È il trigger.

È l'unica parte della tua Skill che sta in contesto tutto il tempo. È quella che Claude confronta con la richiesta dell'utente per decidere se aprire il file oppure no. Una Skill perfetta con una description vaga non parte mai, e tu resti lì a chiederti perché.

La regola operativa: la description deve contenere cosa fa e quando si usa, e il "quando" deve includere le parole che una persona userebbe davvero.

Description debole:

description: Skill per gestire i contenuti del blog.

Description che funziona:

description: Genera la bozza di un articolo per il blog partendo da una keyword e dalle regole di voce del file dedicato. Verifica lunghezza minima, link interni e struttura dei titoli prima di consegnare. Usare quando serve scrivere un nuovo articolo, quando l'utente chiede "scrivimi un post su X", oppure quando va rigenerata una bozza esistente.

La seconda è più lunga, ordine di grandezza: 4 volte tanto. Costa una manciata di token in più, sempre caricati. E si attiva quando deve, invece di restare a guardare.

Un secondo effetto collaterale, meno ovvio: le description scritte bene sono anche la documentazione del tuo sistema. Quando ne hai settanta, l'elenco delle description è l'unica mappa che hai. Se sono vaghe, il tuo sistema è illeggibile anche per te.

Tutorial: creare una Skill da zero in 15 minuti

Prendiamo un caso concreto e banale: una Skill che riassume le modifiche non ancora committate in un repo git.

Minuto 0-2: definisci lo scope. Una Skill, un lavoro. Se ti accorgi che stai scrivendo "e poi, se invece l'utente vuole...", stai scrivendo due Skill. Il collo di bottiglia delle Skill che falliscono non è quasi mai la scrittura: è lo scope troppo largo deciso all'inizio.

Minuto 2-3: crea la cartella.

mkdir -p ~/.claude/skills/riassumi-modifiche

Minuto 3-6: scrivi il frontmatter. Prima il frontmatter, sempre, e prima la description. Se non riesci a scrivere in due righe quando serve questa Skill, non è pronta per essere scritta.

---
name: riassumi-modifiche
description: Riassume le modifiche non committate nel repo corrente in un elenco leggibile, raggruppate per area funzionale. Usare quando serve capire cosa è cambiato prima di un commit, quando l'utente chiede "cosa ho modificato" o "riassumi le modifiche".
---

Minuto 6-11: scrivi il corpo. Identità, step, formato di output, error handling. Corto.

# Riassumi modifiche

Sei l'assistente che prepara il riassunto pre-commit.
Non modifichi file, non fai commit. Solo lettura e sintesi.

## Step 1
Leggi lo stato del working tree e il diff non staged.

## Step 2
Raggruppa le modifiche per area funzionale, non per file.
"Autenticazione: 3 file" batte "src/auth/login.ts, src/auth/session.ts".

## Step 3
Scrivi il riassunto. Formato:
- una riga di sintesi
- un elenco per area, con il numero di file toccati
- una riga finale con i file sospetti (file di configurazione,
  file con credenziali, file di lock)

## Error handling
Se la directory non è un repo git: dillo e fermati.
Se non ci sono modifiche: scrivi "working tree pulito" e fermati.
Non inventare mai un riassunto se il diff è vuoto.

Minuto 11-14: prova con un caso reale. Apri Claude Code nel repo e chiedi "cosa ho modificato". Se la Skill non parte da sola, guarda la description prima del corpo. Nella mia esperienza è quasi sempre lì.

Minuto 14-15: itera sull'errore vero. Guarda cosa ha sbagliato e aggiungi una riga. Una. La tentazione di riscrivere tutto dopo il primo output imperfetto è forte e va ignorata: non sapresti più quale modifica ha funzionato.

Le prime due o tre iterazioni sono quasi sempre sulla description, non sulle istruzioni. È controintuitivo e succede sistematicamente.

Tre Skill reali che uso in produzione

Tutti gli esempi qui sotto sono generalizzati. Path privati e nomi di clienti non ci sono, e nemmeno la logica di business che li rende utili a me: la forma è quella vera, i contenuti sono neutri.

Skill di engagement su un social

Legge una lista di profili da monitorare, filtra i post in base a un punteggio di rilevanza calcolato da uno script, e propone risposte seguendo un file di regole di voce. Il pezzo interessante è la catena di file: la Skill non contiene le regole di voce, le legge. Il file delle regole cambia una volta a settimana, la Skill non cambia mai.

Struttura: SKILL.md con gli step e le blacklist, uno script Python che calcola il punteggio, un documento esterno con il fingerprint linguistico.

Skill di generazione contenuti

Genera una bozza per un canale specifico. Ha tre gate obbligatori prima di consegnare: check di voce, check dei claim temporali, check del formato dei link. Se un gate fallisce, la Skill non pubblica: salva la bozza e scrive il motivo.

Il pattern qui è fail-closed. Una Skill che genera contenuto con il tuo nome sopra deve fallire chiudendo, mai aprendo. È la differenza tra un sistema che ti fa risparmiare tempo e uno che te ne fa perdere il triplo in correzioni.

Skill di audit SEO

Interroga un'API di analytics, confronta i dati con lo snapshot precedente, scrive un report con i delta e apre una lista di ipotesi da testare. Zero scrittura di contenuto, zero interpretazioni creative. Solo numeri e differenze.

Questa è la categoria di Skill che rende di più e che nessuno scrive per primo, perché non è divertente. Ma è quella dove il modello sbaglia meno, perché il compito è chiuso.

Se ti interessa vedere questo tipo di catena applicata a un sito intero, l'ho raccontata in dettaglio nel caso studio su Claude Code per la SEO.

Il bootstrap delle dipendenze: il pezzo che nessuno racconta

Quando una Skill esegue script Python, in un ambiente sandbox le dipendenze non ci sono per definizione. E la sandbox può essere ricreata da zero senza avvisarti.

La soluzione che uso è uno snippet di bootstrap in cima a ogni Skill che esegue codice, con tre livelli di fallback:

# Prova la cartella di dipendenze persistente del repo
if [ -d "$REPO/vendor/python" ]; then
  export PYTHONPATH="$REPO/vendor/python:${PYTHONPATH:-}"
  echo "[bootstrap] uso vendor/python"
elif ! python3 -c "import requests" 2>/dev/null; then
  # Fallback: installazione locale in una cartella temporanea
  pip install --target="$WORKDIR/pydeps" --quiet requests 2>&1 | tail -3
  export PYTHONPATH="$WORKDIR/pydeps:${PYTHONPATH:-}"
  echo "[bootstrap] installate in pydeps"
else
  echo "[bootstrap] dipendenze già presenti"
fi

Tre cose da notare. La prima: è idempotente, puoi rilanciarlo cento volte e non succede niente di cumulativo. La seconda: non installa mai niente a livello globale. La documentazione lo raccomanda per i pacchetti in generale, non solo per quelli Python, e la formula è "Global package installation discouraged": in Claude Code una Skill dovrebbe installare soltanto in locale, per non interferire con la macchina di chi la usa. Vale identico per un npm install -g. La terza: stampa sempre quale ramo ha preso, così quando qualcosa si rompe alle 05:00 di un lunedì il log te lo dice.

Errori da evitare nella creazione di Skills

I quattro che vedo più spesso, in ordine di frequenza.

1. Skill troppo generica. "Skill per il marketing" non è una Skill, è una cartella. Se il nome non contiene un verbo, ripensala. Il test è secco: riesci a dire in una frase quale singolo output produce? Se no, spezzala.
2. Nessun error handling. La Skill funziona quando la provi, perché quando la provi tutto è al suo posto. Poi gira alle 05:00 con la rete lenta, l'API risponde 429, e il modello inventa un numero plausibile per completare il compito. Ogni Skill che tocca dati esterni deve avere scritto nero su bianco cosa fare quando il dato non arriva, e "fermati" è una risposta perfettamente valida.
3. Zero esempi concreti. Descrivere un formato di output è meno efficace che mostrarlo. Un esempio nel corpo della Skill vale più di tre paragrafi di specifica, e costa meno token.
4. Ignorare la context window. Il corpo che entra in contesto quando la Skill si attiva dovrebbe stare sotto i 5k token secondo la documentazione Agent Skills, e sotto le 500 righe secondo quella di Claude Code. Sono due modi di dire la stessa cosa. Se il tuo file è più lungo, non tagliarlo: spostalo. Sposta il materiale di riferimento in file separati che il modello apre solo se servono. Questa è tutta la differenza tra usare la progressive disclosure e subirla.

Ne aggiungo un quinto che non è nelle liste classiche ma è il più costoso: installare Skill da fonti che non conosci. La documentazione di Anthropic è esplicita, e ha ragione. Una Skill è codice più istruzioni, e una Skill malevola può indirizzare Claude a invocare strumenti in modi che non c'entrano niente con quello che dichiara di fare. Se una Skill ti arriva da fuori, leggila tutta prima, script inclusi. Trattala come tratteresti un pacchetto npm che ti manda uno sconosciuto.

Come si testa una Skill

Non esiste una suite di test per le Skill, ma esiste un protocollo che funziona e che costa 10 minuti.

• Test di attivazione. Formula la richiesta in tre modi diversi, con parole diverse. Se la Skill parte solo con la formulazione che avevi in testa mentre la scrivevi, la description è troppo stretta.
• Test di non attivazione. Fai una richiesta adiacente ma diversa. Se la Skill parte lo stesso, la description è troppo larga e ti si attiverà addosso nei momenti sbagliati.
• Test di errore. Rompi qualcosa di proposito. Togli il file che la Skill si aspetta, o passale un input vuoto. Guarda cosa fa. Se inventa, torna nel corpo e scrivi il fallback.
• Test a freddo. Lanciala in una sessione nuova, senza il contesto della conversazione in cui l'hai scritta. È il test che ne boccia di più: una Skill scritta in chat si porta dietro tutto quello che avevi detto prima e che nel file non è finito.

L'ultimo è quello che salta più spesso, ed è anche quello che predice meglio se una Skill reggerà in un task schedulato. Se sopravvive a freddo, sopravvive in produzione.

FAQ

Le Skills funzionano su claude.ai o solo su Claude Code?

Su entrambi, ma non sono lo stesso oggetto e non hanno le stesse regole. Dove vivono l'ho scritto sopra; qui il punto pratico è un altro: la validazione del frontmatter è più severa su claude.ai e via API che su filesystem, quindi una Skill nata in Claude Code può benissimo essere rifiutata quando la carichi altrove. Se prevedi di usarla in più posti, scrivila fin dall'inizio con i vincoli API.

Quante Skills posso avere attive contemporaneamente?

Non c'è un limite rigido documentato, e la progressive disclosure fa sì che una Skill installata ma non attivata costi pochissimo: la documentazione la quota intorno ai 100 token. In Claude Code il tetto è espresso diversamente, come budget a caratteri pari all'1% della context window, con le description delle Skill meno usate che vengono accorciate per prime quando l'elenco sfora (Claude Code — Skills, consultato il 2026-08-12).

Il vincolo vero però non è il numero: è la collisione tra description. Quando due Skill descrivono territori che si sovrappongono, il modello deve scegliere, e a volte sceglie male. Nella mia esperienza, con una settantina di Skill sul disco, il limite pratico arriva molto prima da lì che dalla context window. Se due Skill si attivano a vicenda per la stessa richiesta, il fix non è cancellarne una: è riscrivere le due description in modo che la frontiera sia netta.

Skill, CLAUDE.md o subagent: quando uso cosa?

Regola rapida. CLAUDE.md per i fatti sempre veri del progetto: stack, path, convenzioni, vincoli. Una Skill per le procedure che si eseguono a volte: un deploy, un audit, una generazione. Un subagent quando serve un contesto separato dal tuo, con un modello o dei permessi diversi.

Il segnale che una sezione di CLAUDE.md deve diventare una Skill è quando smette di descrivere com'è fatto il progetto e inizia a descrivere una sequenza di passi. A quel punto sta occupando contesto sempre per servire a te qualche volta.

Una Skill può eseguire codice?

Sì, ed è il caso d'uso migliore. In Claude Code gli script hanno lo stesso accesso di rete di qualsiasi altro programma sulla tua macchina. Via API l'ambiente è più chiuso, senza accesso a internet e senza installazione di pacchetti a runtime, quindi puoi contare solo su quello che è preinstallato.

La regola di progetto che seguo: se un'operazione è deterministica, la fa uno script. Il modello decide, il codice calcola. Su questo tema ho scritto anche di come usare gli hook di Claude Code per il controllo qualità, che è il livello subito sotto: dove le Skill dicono cosa fare, gli hook impongono cosa non può passare.

Le Skills funzionano nei task schedulati?

Sì, ed è lì che rendono di più, ma la risposta dipende da dove gira lo scheduler.

Se il task è schedulato in locale sul tuo computer, legge le Skill dagli stessi posti di qualsiasi altra sessione locale, quindi ~/.claude/skills/ e .claude/skills/ funzionano senza fare niente. Se invece parte in cloud, la sessione nasce pulita e non vede il tuo filesystem: le Skill che hai solo lì dentro risultano non trovate. Le vie d'uscita documentate sono tre, e vale la pena conoscerle tutte perché non sono equivalenti. Committarla nella .claude/skills/ del repo, che funziona per le sessioni cloud. Distribuirla in un plugin dichiarato nel .claude/settings.json del repo, perché i plugin abilitati solo nelle tue impostazioni utente non vengono trasferiti. Oppure abilitarla sull'account claude.ai, ed è la strada che serve per Cowork: sia le sessioni interattive sia quelle schedulate caricano le Skill abilitate sull'account, sincronizzate all'avvio della sessione.

Se hai automazioni che girano quando il computer è spento, questa è la prima cosa da verificare: ne ho scritto nel caso studio sull'architettura ibrida tra locale e cloud.

In sintesi

Quello che distingue una Skill che regge da una che non parte non è quanto è ben scritto il testo delle istruzioni.

È la description, prima di tutto: deve dire quando si usa, con le parole di chi la userà. Poi la lunghezza del corpo, che va tenuta corta spostando il materiale pesante in file che si aprono solo se servono. E infine l'error handling, quello scritto nero su bianco, che dice cosa fare quando il dato non arriva e che preferisce fermarsi piuttosto che inventare.

E poi c'è la parte che non si progetta. La prima versione di ogni Skill che ho in produzione era sbagliata, e quasi sempre era sbagliata nello stesso punto: pensavo che il problema fosse quello che chiedevo al modello di fare, e invece era che il modello non capiva quando ero io a volerlo. Ci ho messo diverse iterazioni a smettere di aggiustare il corpo del file e a guardare la riga sopra.

Se vuoi il quadro completo dello strumento intorno a cui girano le Skill, la guida a Claude Code per developer e automatori è il punto di partenza. Se invece stai valutando dove queste automazioni portano valore in un contesto aziendale, il pezzo su l'automazione AI per il B2B è più adatto. Quando il punto non è più scrivere la Skill ma decidere quali processi toccare per primi e chi li mantiene nel tempo, il problema si sposta sull'automazione dei processi aziendali. E per il formato, le fonti sono due e vanno lette in coppia: la documentazione Agent Skills per la Skills API e claude.ai, la pagina Skills di Claude Code per il filesystem. Conviene ricontrollarle ogni tanto, perché i campi opzionali si muovono.