Le competenze (Skills) sono diventate uno dei punti di estensione più utilizzati in Claude Code. Sono fless. Sono flessibili, facili da creare e semplici da distribuire.
Ma questa flessibilità rende anche difficile capire cosa funzioni meglio. Quali tipi di competenze vale la pena creare? Qual è il segreto per scrivere una buona competenza? Quando condividere le competenze con gli altri?
In Anthropic, usiamo estesamente le competenze in Claude Code, con centinaia di esse attivamente in uso. Queste sono le lezioni che abbiamo imparato sull'uso delle competenze per accelerare il nostro sviluppo.
Cosa sono le Competenze?
Se sei nuovo alle competenze, ti consiglio di leggere la nostra documentazione o guardare il nostro nuovo corso su Skilljar sulle Competenze degli Agenti. Questo post presuppone che tu abbia già una certa familiarità con le competenze.
Un malinteso comune che sentiamo sulle competenze è che siano "solo file markdown", ma la parte più interessante è che non sono solo file di testo. Sono cartelle che possono includere script, risorse, dati, ecc., che l'agente può scoprire, esplorare e manipolare.
In Claude Code, le competenze hanno anche un'ampia varietà di opzioni di configurazione tra cui la registrazione di hook dinamici.
Abbiamo scoperto che alcune delle competenze più interessanti in Claude Code utilizzano queste opzioni di configurazione e la struttura delle cartelle in modo creativo.
Tipi di Competenze
Dopo aver catalogato tutte le nostre competenze, abbiamo notato che si raggruppano in alcune categorie ricorrenti. Le migliori competenze rientrano perfettamente in una di esse; quelle più confuse ne abbracciano diverse. Questo non è un elenco definitivo, ma è un buon modo per capire se ti manca qualcosa all'interno della tua organizzazione.
1. Librerie e Riferimenti API
Competenze che spiegano come utilizzare correttamente una libreria, una CLI o degli SDK. Possono essere sia per librerie interne che per librerie comuni con cui Claude Code a volte ha difficoltà. Queste competenze spesso includevano una cartella di frammenti di codice di riferimento e un elenco di insidie da evitare per Claude durante la scrittura di uno script.
Esempi:
- billing-lib — la tua libreria di fatturazione interna: casi limite, insidie comuni, ecc.
- internal-platform-cli — ogni sottocomando del tuo wrapper CLI interno con esempi su quando usarli
- frontend-design — migliora Claude nel tuo sistema di design
2. Verifica del Prodotto
Competenze che descrivono come testare o verificare che il tuo codice funzioni. Sono spesso abbinate a uno strumento esterno come Playwright, tmux, ecc. per eseguire la verifica.
Le competenze di verifica sono estremamente utili per garantire che l'output di Claude sia corretto. Può valere la pena che un ingegnere dedichi una settimana solo per rendere le tue competenze di verifica eccellenti.
Prendi in considerazione tecniche come far registrare a Claude un video del suo output in modo da poter vedere esattamente cosa ha testato, o imporre asserzioni programmatiche sullo stato a ogni passaggio. Queste vengono spesso realizzate includendo una varietà di script nella competenza.
Esempi:
- signup-flow-driver — esegue il flusite → verifica email → onboarding in un browser headless, con hook per asserire lo stato a ogni passaggio
- checkout-verifier — guida l'interfaccia di checkout con le carte di test di Stripe, verifica che la fattura arrivi effettivamente nello stato corretto
- tmux-cli-driver — per test interattivi da CLI dove la cosa che stai verificando necessita di un TTY
3. Acquisizione e Analisi dei Dati
Competenze che si collegano ai tuoi stack di dati e monitoraggio. Queste competenze potrebbero includere librerie per recuperare i tuoi dati con le credenziali, ID di dashboard specifici, ecc., oltre a istruzioni su flussi di lavoro comuni o modi per ottenere dati.
Esempi:
- funnel-query — "quali eventi devo unire per vedere iscrizione → attivazione → pagamento" più la tabella che ha effettivamente lo user_id canonico
- cohort-compare — confronta la fidelizzazione o la conversione di due coorti, segnala le differenze statisticamente significative, collega alle definizioni dei segmenti
- grafana — UID delle origini dati, nomi dei cluster, tabella di ricerca problema → dashboard
4. Processi Aziendali e Automazione del Team
Competenze che automatizzano flussi di lavoro ripetitivi in un unico comando. Queste competenze sono di solito istruzioni piuttosto semplici ma potrebbero avere dipendenze più complicate da altre competenze o MCP. Per queste competenze, salvare i risultati precedenti in file di log può aiutare il modello a rimanere coerente e riflettere sulle esecuzioni precedenti del flusso di lavoro.
Esempi:
- standup-post — aggrega il tuo tracker dei ticket, l'attività su GitHub e i precedenti messaggi Slack → un riepilogo formattato, solo le differenze
- crea-<sistema-di-ticket>-ticket — impone uno schema (valori enum validi, campi obbligatori) più un flusso di lavoro post-creazione (pinga il revisore, collega in Slack)
- riepilogo-settimanale — PR unite + ticket chiusi + deploy → un post di riepilogo formattato
5. Scaffolding del Codice e Template
Competenze che generano boilerplate del framework per una funzione specifica nel codebase. Potresti combinare queste competenze con script componibili. Sono particolarmente utili quando lo scaffolding ha requisiti in linguaggio naturale che non possono essere coperti puramente dal codice.
Esempi:
- nuovo-flusso-di-lavoro-<framework> — crea un nuovo servizio/flusso di lavoro/gestore con le tue annotazioni
- nuova-migrazione — il tuo template di file di migrazione più insidie comuni
- crea-app — nuova app interna con la tua autenticazione, logging e configurazione di deploy preimpostati
6. Qualità del Codice e Revisione
Competenze che impongono la qualità del codice all'interno della tua organizzazione e aiutano a revisionare il codice. Possono includere script deterministici o strumenti per la massima robustezza. Potresti voler eseguire queste competenze automaticamente come parte di hook o all'interno di un'azione GitHub.
- revisione-avversaria — genera un sotto-agente con occhi nuovi per criticare, implementa correzioni, itera fino a quando i risultati degenerano in piccolezze
- stile-codice — impone lo stile del codice, specialmente gli stili che Claude non gestisce bene per impostazione predefinita.
- pratiche-di-test — istruzioni su come scrivere test e cosa testare.
7. CI/CD e Deploy
Competenze che ti aiutano a recuperare, inviare e distribuire il codice all'interno del tuo codebase. Queste competenze potrebbero fare riferimento ad altre competenze per raccogliere dati.
Esempi:
- babysit-pr — monitora una PR → riprova CI instabile → risolve i conflitti di merge → abilita l'unione automatica
- deploy-<servizio> — build → smoke test → rollout graduale del traffico con confronto del tasso di errore → rollback automatico in caso di regressione
- cherry-pick-prod — worktree isolato → cherry-pick → risoluzione dei conflitti → PR con template
8. Runbook
Competenze che prendono un sintomo (come un thread Slack, un avviso o una firma di errore), esaminano un'indagine multi-strumento e producono un report strutturato.
Esempi:
- <servizio>-debugging — mappa sintomi → strumenti → pattern di query per i tuoi servizi a traffico più elevato
- esecutore-reperibilità — recupera l'avviso → controlla i soliti sospetti → formatta un risultato
- correlatore-log — dato un ID richiesta, recupera i log corrispondenti da ogni sistema che potrebbe averlo toccato
9. Operazioni sull'Infrastruttura
Competenze che eseguono manutenzione ordinaria e procedure operative, alcune delle quali comportano azioni distruttive che traggono vantaggio da misure di sicurezza. Queste facilitano il rispetto delle best practice da parte degli ingegneri nelle operazioni critiche.
Esempi:
- <risorsa>-orfani — trova pod/volumi orfani → pubblica su Slack → periodo di attesa → l'utente conferma → pulizia a cascata
- gestione-dipendenze — il flusso di lavoro di approvazione delle dipendenze della tua organizzazione
- indagine-costi — "perché la nostra bolletta di storage/uscita è aumentata?" con i bucket e i pattern di query specifici
Consigli per Creare Competenze
Una volta deciso quale competenza creare, come la scrivi? Queste sono alcune delle migliori pratiche, consigli e trucchi che abbiamo trovato.
Abbiamo anche rilasciato di recente Skill Creator per facilitare la creazione di competenze in Claude Code.
Non Dire l'Ovvio
Claude Code sa molto del tuo codebase e Claude sa molto di programmazione, incluse molte opinioni predefinite. Se stai pubblicando una competenza che riguarda principalmente la conoscenza, cerca di concentrarti sulle informazioni che spingono Claude fuori dal suo modo di pensare normale.
La competenza di progettazione frontend è un grande esempio: è stata creata da uno degli ingegneri di Anthropic iterando con i clienti per migliorare il gusto del design di Claude, evitando pattern classici come il font Inter e i gradienti viola.
Crea una Sezione "Insidie"
Il contenuto di maggior valore in qualsiasi competenza è la sezione "Insidie". Queste sezioni dovrebbero essere costruite a partire dai punti di errore comuni in cui Claude si imbatte quando usa la tua competenza. Idealmente, aggiornerai la tua competenza nel tempo per catturare queste insidie.
Usa il File System e la Divulgazione Progressiva
Come abbiamo detto prima, una competenza è una cartella, non solo un file markdown. Dovresti pensare all'intero file system come a una forma di ingegneria del contesto e di divulgazione progressiva. Di' a Claude quali file sono nella tua competenza e li leggerà al momento opportuno.
La forma più semplice di divulgazione progressiva è puntare ad altri file markdown da usare per Claude. Ad esempio, potresti dividere le firme dettagliate delle funzioni e gli esempi di utilizzo in references/api.md.
Un altro esempio: se il tuo output finale è un file markdown, potresti includere un file template per esso in assets/ da copiare e utilizzare.
Puoi avere cartelle di riferimenti, script, esempi, ecc., che aiutano Claude a lavorare in modo più efficace.
Evita di Guidare Troppo Claude
Claude tenderà generalmente a attenersi alle tue istruzioni e, poiché le competenze sono così riutilizzabili, devi stare attento a non essere troppo specifico nelle tue istruzioni. Dai a Claude le informazioni di cui ha bisogno, ma dagli la flessibilità di adattarsi alla situazione. Per esempio:
Pensa alla Configurazione Iniziale
Alcune competenze potrebbero dover essere configurate con il contesto dell'utente. Ad esempio, se stai creando una competenza che pubblica il tuo standup su Slack, potresti volere che Claude chieda in quale canale Slack pubblicarlo.
Un buon pattern per farlo è memorizzare queste informazioni di configurazione in un file config.json nella directory della competenza, come nell'esempio sopra. Se la configurazione non è impostata, l'agente può quindi chiedere all'utente le informazioni.
Se vuoi che l'agente presenti domande strutturate a scelta multipla, puoi istruire Claude a utilizzare lo strumento AskUserQuestion.
Il Campo Descrizione è per il Modello
Quando Claude Code avvia una sessione, costruisce un elenco di ogni competenza disponibile con la sua descrizione. Questo elenco è ciò che Claude scansiona per decidere "c'è una competenza per questa richiesta?" Il che significa che il campo descrizione non è un riepilogo, ma una descrizione di quando attivare questa PR.
Memoria e Memorizzazione dei Dati
Alcune competenze possono includere una forma di memoria memorizzando i dati al loro interno. Potresti memorizzare i dati in qualsiasi cosa, da un semplice file di log di testo in append-only o file JSON, fino a un database SQLite.
Ad esempio, una competenza di pubblicazione dello standup potrebbe mantenere un file standups.log con ogni post scritto, il che significa che la prossima volta che lo esegui, Claude legge la propria cronologia e può dire cosa è cambiato rispetto a ieri.
I dati memorizzati nella directory della competenza potrebbero essere eliminati quando aggiorni la competenza, quindi dovresti memorizzarli in una cartella stabile. Oggi forniamo ${**CLAUDE_PLUGIN_DATA**} come cartella stabile per plugin in cui memorizzare i dati.
Memorizza Script e Genera Codice
Uno degli strumenti più potenti che puoi dare a Claude è il codice. Dare a Claude script e librerie permette a Claude di dedicare i suoi turni alla composizione, decidendo cosa fare dopo piuttosto che ricostruire codice boilerplate.
Ad esempio, nella tua competenza di scienza dei dati potresti avere una libreria di funzioni per recuperare dati dalla tua fonte di eventi. Affinché Claude possa eseguire analisi complesse, potresti dargli un set di funzioni helper come segue:
Claude può quindi generare script al volo per comporre queste funzionalità e fare analisi più avanzate per prompt come "Cosa è successo martedì?"
Hook su Richiesta
Le competenze possono includere hook che si attivano solo quando la competenza viene chiamata e durano per la durata della sessione. Usali per hook più opinabili che non vuoi eseguire sempre, ma che sono estremamente utili a volte.
Per esempio:
- /attento — blocca rm -rf, DROP TABLE, force-push, kubectl delete tramite il matcher PreToolUse su Bash. Lo vuoi solo quando sai che stai toccando la produzione — averlo sempre attivo ti farebbe impazzire
- /congela — blocca qualsiasi modifica/scrittura che non sia in una directory specifica. Utile
- durante il debug: "Voglio aggiungere log ma continuo a 'correggere' accidentalmente cose non correlate"
Distribuzione delle Competenze
Uno dei maggiori vantaggi delle competenze è che puoi condividerle con il resto del tuo team.
Ci sono due modi in cui potresti condividere le competenze con altri:
- controllare le tue competenze nel tuo repository (sotto ./.claude/skills)
- creare un plugin e avere un mercato di plugin Claude Code dove gli utenti possono caricare e installare plugin (leggi di più nella documentazione
Per team più piccoli che lavorano su relativamente pochi repository, controllare le competenze nei repository funziona bene. Ma ogni competenza controllata aggiunge anche un po' di contesto al modello. Man mano che cresci, un mercato di plugin interno ti permette di distribuire le competenze e lasciare che il tuo team decida quali installare.
Gestire un Mercato
Come decidi quali competenze vanno in un mercato? Come fanno le persone a inviarle?
Non abbiamo un team centralizzato che decide; invece, proviamo a trovare le competenze più utili in modo organico. Se hai una competenza che vuoi far provare alle persone, puoi caricarla in una cartella sandbox su GitHub e indirizzare le persone ad essa in Slack o altri forum.
Una volta che una competenza ha guadagnato trazione (sta al proprietario della competenza deciderlo), può fare una PR per spostarla nel mercato.
Un avvertimento: può essere abbastanza facile creare competenze scadenti o ridondanti, quindi è importante assicurarsi di avere un qualche metodo di curatione prima del rilascio.
Comporre Competenze
Potresti volere competenze che dipendono l'una dall'altra. Ad esempio, potresti avere una competenza di caricamento file che carica un file e una competenza di generazione CSV che crea un CSV e lo carica. Questo tipo di gestione delle dipendenze non è ancora nativamente integrato nei mercati o nelle competenze, ma puoi semplicemente fare riferimento ad altre competenze per nome e il modello le invocherà se sono installate.
Misurare le Competenze
Per capire come sta andando una competenza, utilizziamo un hook PreToolUse che ci permette di registrare l'uso delle competenze all'interno dell'azienda (codice di esempio qui). Questo significa che possiamo trovare competenze popolari o che vengono attivate meno del previsto.
Conclusione
Le competenze sono strumenti incredibilmente potenti e flessibili per gli agenti, ma è ancora presto e stiamo tutti imparando a usarli al meglio.
Pensa a questo più come a un sacco pieno di consigli utili che abbiamo visto funzionare, piuttosto che a una guida definitiva. Il modo migliore per capire le competenze è iniziare, sperimentare e vedere cosa funziona per te. La maggior parte delle nostre competenze è nata con poche righe e una singola insidia, ed è migliorata perché le persone hanno continuato ad aggiungervi cose man mano che Claude incontrava nuovi casi limite.
Spero che questo ti sia stato utile, fammi sapere se hai domande.
