Tutorial ufficiale sulle Agent Skills di Anthropic: note complete sul corso di 6 lezioni

Anthropic ha finalmente pubblicato un video tutorial ufficiale sulle Agent Skills, composto da 6 lezioni per una durata totale di 22 minuti. Copre l'intero ciclo di vita delle Skills, da cosa sono a come crearle, configurare impostazioni multi-file, distinguerle da altre funzionalità, condividerle e risolvere i problemi.

Il valore più grande di questo tutorial non è solo insegnarti come scrivere una Skill, ma spiegare la filosofia di design e i meccanismi sottostanti delle Skills. Molti problemi che le persone incontrano quando usano le Skills derivano da una comprensione insufficiente di questi meccanismi.

Quali Problemi Risolvono le Skills?

Ogni volta che spieghi a Claude gli standard di codifica del tuo team, ti ripeti. Ad ogni revisione di una PR, devi ridescrivere come vuoi che sia organizzato il feedback. Per ogni messaggio di commit, devi ricordare a Claude il formato che preferisci.

Le Skills sono progettate per eliminare questa ripetizione. Una Skill è un file Markdown che insegna a Claude come fare una cosa una volta, e Claude applica automaticamente quella conoscenza nelle situazioni pertinenti.

Più precisamente, un'Agent Skill è una cartella che contiene istruzioni, script e risorse. Claude può scoprire e utilizzare automaticamente queste risorse per completare il lavoro in modo più accurato ed efficiente.

Il meccanismo principale è il campo description. Quando Claude si avvia, carica i nomi e le descrizioni di tutte le Skills. Quando fai una richiesta, Claude esegue una corrispondenza semantica tra la tua richiesta e le descrizioni di tutte le Skills disponibili per trovare e attivare quella corrispondente. Solo al momento dell'attivazione, il contenuto completo della Skill viene caricato nella finestra di contesto.

Questo è fondamentalmente diverso da claude.md. Il contenuto di claude.md viene caricato in ogni conversazione, indipendentemente da ciò che stai facendo. Una Skill viene caricata solo quando necessario; la tua checklist per la revisione delle PR non deve essere nel contesto mentre esegui il debug, apparendo solo quando richiedi effettivamente una revisione.

Quando dovresti usare una Skill? Se ti ritrovi a spiegare ripetutamente la stessa cosa a Claude, quella è una Skill in attesa di essere sviluppata.

Creare la Tua Prima Skill da Zero

Creare una Skill richiede solo due passaggi: creare una directory e scrivere un file.

Primo passo: crea una directory con il nome della Skill in ~/.claude/skills/. Posizionarla qui significa che è una Skill a livello personale, disponibile in tutti i progetti.

Secondo passo: crea un file SKILL.md nella directory. Il file è diviso in due parti, separate da tre trattini. La parte superiore sono metadati YAML che contengono name e description. La parte inferiore contiene le istruzioni specifiche che Claude deve seguire.

Quando Claude Code si avvia, esegue la scansione di quattro posizioni per le Skills: percorsi aziendali, directory delle Skills personali, directory delle Skills di progetto e plugin installati. Carica solo il nome e la descrizione di ogni Skill, non il contenuto completo.

Quando invii una richiesta, Claude confronta la richiesta con tutte le descrizioni delle Skills. Se l'intento corrisponde, ti chiederà prima di confermare se caricare la Skill. Solo dopo la conferma legge il file completo ed esegue le istruzioni. Questo passaggio di conferma ti tiene informato su quale contesto Claude sta utilizzando.

Se esistono Skills con lo stesso nome, la priorità dall'alto al basso è: Livello aziendale (managed-settings.json), Livello personale (~/.claude/skills), Livello di progetto (project/.claude/skills) e Livello plugin (project/.claude-plugins/skills).

Ciò significa che un'azienda può imporre standard tramite Skills a livello aziendale, consentendo al contempo ai singoli di personalizzare tramite Skills con nomi diversi. Se la tua azienda ha una Skill aziendale per la revisione del codice, puoi creare una Skill personale chiamata front-end-pr-review per integrarla, non per sovrascriverla.

Configurazione Avanzata: Campi dei Metadati e Divulgazione Progressiva

Le Skills di base necessitano solo di name e description, ma diverse configurazioni avanzate possono rendere le Skills più potenti.

Il campo allowed-tools può limitare quali strumenti Claude può utilizzare quando la Skill è attiva. Ad esempio, se hai una Skill di analisi in sola lettura, puoi proibire comandi di modifica, scrittura e Bash. Se questo campo viene omesso, la Skill non impone restrizioni e Claude utilizza il normale modello di autorizzazione.

Il campo model può specificare quale versione del modello Claude utilizzare.

Il modo in cui viene scritta la description determina direttamente se una Skill può essere attivata correttamente. Una buona descrizione dovrebbe rispondere a due domande: Cosa fa questa Skill? Quando dovrebbe usarla Claude? Se una Skill non si attiva, aggiungi più parole chiave che corrispondono alla formulazione delle tue richieste.

Il concetto avanzato più importante è la divulgazione progressiva. Le Skills condividono la finestra di contesto con la tua conversazione. Se stipi tutto in un file SKILL.md di 20.000 righe, consumerà uno spazio di contesto enorme.

L'approccio corretto è: metti le istruzioni essenziali in SKILL.md e i materiali di riferimento dettagliati in file separati, che Claude legge solo quando necessario. La struttura di directory consigliata per gli standard aperti è: una cartella scripts per il codice eseguibile, references per i documenti di riferimento e resources per file di dati come immagini e modelli. Usa i collegamenti in SKILL.md per fare riferimento a questi file.

Regola chiave: SKILL.md non deve superare le 500 righe. Se lo fa, deve essere suddiviso. Gli script possono essere eseguiti direttamente senza caricare il loro contenuto nel contesto; solo l'output consuma token. Quindi, dì a Claude di eseguire lo script piuttosto che leggerlo. Questo è particolarmente utile per la convalida dell'ambiente e la trasformazione dei dati, poiché il codice script testato è più affidabile della generazione al volo.

Differenze tra Skills e Altre Funzionalità di Claude Code

Skills vs. claude.md: claude.md viene sempre caricato in ogni conversazione per standard e regole di progetto che si applicano sempre, come "Questo progetto usa la modalità strict di TypeScript." Le Skills vengono caricate su richiesta, attivate solo quando Claude corrisponde a una richiesta.

Skills vs. Sub Agents: Le Skills aggiungono conoscenza alla conversazione corrente; una volta attivate, le istruzioni vengono aggiunte al contesto esistente. I Sub Agents vengono eseguiti in un contesto indipendente, completando le attività e inviando i risultati separatamente, completamente isolati dalla conversazione principale.

Skills vs. Hooks: Gli Hooks sono guidati da eventi, attivandosi quando si verificano eventi specifici, come Claude che esegue un Linter ogni volta che un file viene salvato. Le Skills sono guidate dalle richieste, attivandosi in base alle domande che fai.

Skills vs. MCP: MCP fornisce connessioni a strumenti esterni, consentendo a Claude di chiamare servizi come Gmail o Notion. Le Skills forniscono conoscenza e flussi di lavoro, dicendo a Claude come usare quegli strumenti per completare attività specifiche.

Riepilogo in una frase: claude.md contiene istruzioni sempre attive, le Skills contengono competenze abbinate automaticamente, i Sub Agents eseguono attività delegate in contesti isolati, gli Hooks rispondono agli eventi e MCP si connette a strumenti esterni. Possono essere usati in combinazione.

Condividere le Skills: Da Individui a Team a Organizzazioni

Il valore delle Skills sta nella condivisione. Una Skill per la revisione delle PR usata solo da te è utile, ma una Skill condivisa dal team può standardizzare le revisioni del codice e fornire un'esperienza coerente.

Tre modi per condividere:

Il primo è la directory del progetto. Esegui il commit della Skill nella directory .claude/skills del repository del codice. Chiunque cloni il repo riceve automaticamente queste Skills senza installazione aggiuntiva. Gli aggiornamenti vengono ricevuti al prossimo pull. Questo è adatto per gli standard di codifica del team e i flussi di lavoro specifici del progetto.

Il secondo sono i plugin. Pensa ai plugin come a un modo per distribuire le Skills tra i progetti. Una volta caricato in un app store, altri utenti possono scaricarli e installarli. Se la tua Skill è generica e non specifica per un progetto, questa è la scelta migliore per i membri della comunità.

Il terzo è la distribuzione aziendale. Gli amministratori inviano le Skills all'intera organizzazione tramite impostazioni gestite. Le Skills a livello aziendale hanno la priorità più alta e sovrascriveranno le Skills personali e di progetto con lo stesso nome. Questo viene utilizzato per standard obbligatori, requisiti di sicurezza e flussi di lavoro di conformità.

Una nota importante: i Sub Agents non ereditano automaticamente le tue Skills. Quando deleghi un'attività a un sub-agent, questo inizia con un contesto nuovo. Gli agenti integrati (Explorer, Plan, Verify) non possono accedere affatto alle Skills; solo i sub-agent personalizzati che definisci possono usarle e devono essere elencati esplicitamente in agent.md.

Per creare un sub-agent personalizzato con Skills, crea un file agent.md nella directory .claude/agents e aggiungi un campo skills elencando i nomi delle Skills richieste. Elenca solo le Skills che sono sempre pertinenti all'obiettivo del sub-agent, poiché queste Skills verranno caricate all'avvio del sub-agent.

Guida alla Risoluzione dei Problemi: Sei Motivi per Cui le Skills Falliscono e le Loro Soluzioni

I problemi con le Skills di solito rientrano in sei categorie:

1. Skill che non si attiva: Il motivo è quasi sempre una description scritta male. Claude usa la corrispondenza semantica; la tua richiesta deve allinearsi al significato della descrizione. Se non c'è abbastanza sovrapposizione, non corrisponderà. Soluzione: Confronta la descrizione con la formulazione della tua richiesta e aggiungi frasi di attivazione che gli utenti dicono effettivamente, come "aiutami ad analizzare", "perché è lento" o "acceleralo".

1. Skill che non si carica: Controlla i percorsi e i nomi dei file. SKILL.md deve essere all'interno di una directory con nome, non direttamente nella root delle skills. Il nome del file deve essere esattamente SKILL.md in maiuscolo. Esegui claude --debug per visualizzare gli errori di caricamento.

1. Claude usa la Skill sbagliata: Ciò significa che hai più Skills con descrizioni troppo simili, rendendo impossibile per Claude distinguerle. Soluzione: Rendi ogni descrizione il più specifica possibile per aiutare Claude a decidere quando usarle.

1. Skill personale ignorata: Una Skill con priorità più alta (come una aziendale) con lo stesso nome potrebbe sovrascriverla. Controlla i quattro livelli di priorità. Soluzione: Rinomina la tua Skill con un nome più univoco.

1. Plugin installato ma Skill non visibile: Cancella la cache con rm ~/.claude/plugins/cache, riavvia Claude Code e reinstalla. Se ancora non funziona, la struttura di directory del plugin potrebbe essere errata; usa lo strumento di convalida skills-ref validate per controllare.

1. Skill caricata ma che fallisce durante l'esecuzione: Se la Skill utilizza pacchetti esterni, assicurati che siano installati. Aggiungi le informazioni sulle dipendenze alla descrizione della Skill.

Anthropic fornisce anche uno strumento di convalida chiamato skills-ref per verificare se la struttura del file e la sintassi YAML della Skill sono corrette. Si consiglia di installarlo tramite uv per il metodo più veloce.