Prerequisiti
- Claude Code versione 1.0 o successiva
- Familiarità di base con Claude Code
Cosa sono le Competenze dell’Agente?
Le Competenze dell’Agente impacchettano l’expertise in capacità scopribili. Ogni Competenza consiste di un fileSKILL.md
con istruzioni che Claude legge quando rilevante, più file di supporto opzionali come script e template.
Come vengono invocate le Competenze: Le Competenze sono invocate dal modello—Claude decide autonomamente quando usarle basandosi sulla tua richiesta e sulla descrizione della Competenza. Questo è diverso dai comandi slash, che sono invocati dall’utente (digiti esplicitamente /comando
per attivarli).
Vantaggi:
- Estendere le capacità di Claude per i tuoi flussi di lavoro specifici
- Condividere expertise attraverso il tuo team via git
- Ridurre i prompt ripetitivi
- Comporre più Competenze per compiti complessi
Per un approfondimento sull’architettura e le applicazioni nel mondo reale delle Competenze dell’Agente, leggi il nostro blog di ingegneria: Equipping agents for the real world with Agent Skills.
Creare una Competenza
Le Competenze sono memorizzate come directory contenenti un fileSKILL.md
.
Competenze Personali
Le Competenze Personali sono disponibili in tutti i tuoi progetti. Memorizzale in~/.claude/skills/
:
- I tuoi flussi di lavoro individuali e preferenze
- Competenze sperimentali che stai sviluppando
- Strumenti di produttività personale
Competenze di Progetto
Le Competenze di Progetto sono condivise con il tuo team. Memorizzale in.claude/skills/
all’interno del tuo progetto:
- Flussi di lavoro e convenzioni del team
- Expertise specifico del progetto
- Utilità e script condivisi
Competenze Plugin
Le Competenze possono anche provenire dai plugin di Claude Code. I plugin possono raggruppare Competenze che sono automaticamente disponibili quando il plugin è installato. Queste Competenze funzionano allo stesso modo delle Competenze personali e di progetto.Scrivere SKILL.md
Crea un fileSKILL.md
con frontmatter YAML e contenuto Markdown:
description
è critico per Claude per scoprire quando usare la tua Competenza. Dovrebbe includere sia cosa fa la Competenza sia quando Claude dovrebbe usarla.
Vedi la guida alle migliori pratiche per una guida completa alla creazione.
Aggiungere file di supporto
Crea file aggiuntivi accanto a SKILL.md:Limitare l’accesso agli strumenti con allowed-tools
Usa il campo frontmatterallowed-tools
per limitare quali strumenti Claude può usare quando una Competenza è attiva:
- Competenze in sola lettura che non dovrebbero modificare file
- Competenze con ambito limitato (es. solo analisi dati, nessuna scrittura file)
- Flussi di lavoro sensibili alla sicurezza dove vuoi limitare le capacità
allowed-tools
non è specificato, Claude chiederà il permesso per usare gli strumenti come normale, seguendo il modello di permessi standard.
allowed-tools
è supportato solo per le Competenze in Claude Code.Visualizzare le Competenze disponibili
Le Competenze sono automaticamente scoperte da Claude da tre fonti:- Competenze Personali:
~/.claude/skills/
- Competenze di Progetto:
.claude/skills/
- Competenze Plugin: raggruppate con plugin installati
Testare una Competenza
Dopo aver creato una Competenza, testala facendo domande che corrispondono alla tua descrizione. Esempio: Se la tua descrizione menziona “file PDF”:Debug di una Competenza
Se Claude non usa la tua Competenza, controlla questi problemi comuni:Rendi la descrizione specifica
Troppo vaga:Verifica il percorso del file
Competenze Personali:~/.claude/skills/skill-name/SKILL.md
Competenze di Progetto: .claude/skills/skill-name/SKILL.md
Controlla che il file esista:
Controlla la sintassi YAML
YAML non valido impedisce il caricamento della Competenza. Verifica il frontmatter:---
di apertura sulla riga 1---
di chiusura prima del contenuto Markdown- Sintassi YAML valida (nessun tab, indentazione corretta)
Visualizza errori
Esegui Claude Code con modalità debug per vedere errori di caricamento Competenze:Condividere Competenze con il tuo team
Approccio raccomandato: Distribuisci Competenze attraverso plugin. Per condividere Competenze via plugin:- Crea un plugin con Competenze nella directory
skills/
- Aggiungi il plugin a un marketplace
- I membri del team installano il plugin
Passo 1: Aggiungi Competenza al tuo progetto
Crea una Competenza di progetto:Passo 2: Commit su git
Passo 3: I membri del team ottengono le Competenze automaticamente
Quando i membri del team fanno pull delle ultime modifiche, le Competenze sono immediatamente disponibili:Aggiornare una Competenza
Modifica SKILL.md direttamente:Rimuovere una Competenza
Elimina la directory della Competenza:Migliori pratiche
Mantieni le Competenze focalizzate
Una Competenza dovrebbe affrontare una capacità: Focalizzata:- “Compilazione moduli PDF”
- “Analisi dati Excel”
- “Messaggi commit Git”
- “Elaborazione documenti” (dividi in Competenze separate)
- “Strumenti dati” (dividi per tipo di dati o operazione)
Scrivi descrizioni chiare
Aiuta Claude a scoprire quando usare le Competenze includendo trigger specifici nella tua descrizione: Chiara:Testa con il tuo team
Fai usare le Competenze ai compagni di squadra e fornisci feedback:- La Competenza si attiva quando previsto?
- Le istruzioni sono chiare?
- Ci sono esempi mancanti o casi limite?
Documenta le versioni delle Competenze
Puoi documentare le versioni delle Competenze nel contenuto del tuo SKILL.md per tracciare le modifiche nel tempo. Aggiungi una sezione cronologia versioni:Risoluzione problemi
Claude non usa la mia Competenza
Sintomo: Fai una domanda rilevante ma Claude non usa la tua Competenza. Controlla: La descrizione è abbastanza specifica? Descrizioni vaghe rendono difficile la scoperta. Includi sia cosa fa la Competenza sia quando usarla, con termini chiave che gli utenti menzionerebbero. Troppo generica:La Competenza ha errori
Sintomo: La Competenza si carica ma non funziona correttamente. Controlla: Le dipendenze sono disponibili? Claude installerà automaticamente le dipendenze richieste (o chiederà il permesso per installarle) quando ne ha bisogno. Controlla: Gli script hanno permessi di esecuzione?scripts/helper.py
Sbagliato: scripts\helper.py
(stile Windows)
Più Competenze in conflitto
Sintomo: Claude usa la Competenza sbagliata o sembra confuso tra Competenze simili. Sii specifico nelle descrizioni: Aiuta Claude a scegliere la Competenza giusta usando termini trigger distinti nelle tue descrizioni. Invece di:Esempi
Competenza Semplice (file singolo)
Competenza con permessi strumenti
Competenza Multi-file
Elenca i pacchetti richiesti nella descrizione. I pacchetti devono essere installati nel tuo ambiente prima che Claude possa usarli.