Questa guida ti mostra come creare, utilizzare e gestire le Competenze dell’Agente in Claude Code. Le Competenze sono capacità modulari che estendono la funzionalità di Claude attraverso cartelle organizzate contenenti istruzioni, script e risorse.

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 file SKILL.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
Scopri di più nella panoramica delle Competenze dell’Agente.
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 file SKILL.md.

Competenze Personali

Le Competenze Personali sono disponibili in tutti i tuoi progetti. Memorizzale in ~/.claude/skills/:
mkdir -p ~/.claude/skills/my-skill-name
Usa le Competenze personali per:
  • 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:
mkdir -p .claude/skills/my-skill-name
Usa le Competenze di progetto per:
  • Flussi di lavoro e convenzioni del team
  • Expertise specifico del progetto
  • Utilità e script condivisi
Le Competenze di Progetto sono inserite in git e automaticamente disponibili ai membri del team.

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 file SKILL.md con frontmatter YAML e contenuto Markdown:
---
name: Nome della Tua Competenza
description: Breve descrizione di cosa fa questa Competenza e quando usarla
---

# Nome della Tua Competenza

## Istruzioni
Fornisci una guida chiara, passo dopo passo per Claude.

## Esempi
Mostra esempi concreti di utilizzo di questa Competenza.
Il campo 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:
my-skill/
├── SKILL.md (richiesto)
├── reference.md (documentazione opzionale)
├── examples.md (esempi opzionali)
├── scripts/
│   └── helper.py (utilità opzionale)
└── templates/
    └── template.txt (template opzionale)
Riferisci questi file da SKILL.md:
Per l'uso avanzato, vedi [reference.md](reference.md).

Esegui lo script helper:
```bash
python scripts/helper.py input.txt
```
Claude legge questi file solo quando necessario, usando la divulgazione progressiva per gestire il contesto in modo efficiente.

Limitare l’accesso agli strumenti con allowed-tools

Usa il campo frontmatter allowed-tools per limitare quali strumenti Claude può usare quando una Competenza è attiva:
---
name: Lettore File Sicuro
description: Leggi file senza apportare modifiche. Usa quando hai bisogno di accesso ai file in sola lettura.
allowed-tools: Read, Grep, Glob
---

# Lettore File Sicuro

Questa Competenza fornisce accesso ai file in sola lettura.

## Istruzioni
1. Usa Read per visualizzare il contenuto dei file
2. Usa Grep per cercare all'interno dei file
3. Usa Glob per trovare file per pattern
Quando questa Competenza è attiva, Claude può usare solo gli strumenti specificati (Read, Grep, Glob) senza dover chiedere il permesso. Questo è utile per:
  • 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à
Se 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
Per visualizzare tutte le Competenze disponibili, chiedi direttamente a Claude:
Quali Competenze sono disponibili?
o
Elenca tutte le Competenze disponibili
Questo mostrerà tutte le Competenze da tutte le fonti, incluse le Competenze plugin. Per ispezionare una Competenza specifica, puoi anche controllare il filesystem:
# Elenca Competenze personali
ls ~/.claude/skills/

# Elenca Competenze di progetto (se in una directory di progetto)
ls .claude/skills/

# Visualizza il contenuto di una Competenza specifica
cat ~/.claude/skills/my-skill/SKILL.md

Testare una Competenza

Dopo aver creato una Competenza, testala facendo domande che corrispondono alla tua descrizione. Esempio: Se la tua descrizione menziona “file PDF”:
Puoi aiutarmi a estrarre testo da questo PDF?
Claude decide autonomamente di usare la tua Competenza se corrisponde alla richiesta—non hai bisogno di invocarla esplicitamente. La Competenza si attiva automaticamente basandosi sul contesto della tua domanda.

Debug di una Competenza

Se Claude non usa la tua Competenza, controlla questi problemi comuni:

Rendi la descrizione specifica

Troppo vaga:
description: Aiuta con i documenti
Specifica:
description: Estrai testo e tabelle da file PDF, compila moduli, unisci documenti. Usa quando lavori con file PDF o quando l'utente menziona PDF, moduli, o estrazione documenti.
Includi sia cosa fa la Competenza sia quando usarla nella descrizione.

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:
# Personale
ls ~/.claude/skills/my-skill/SKILL.md

# Progetto
ls .claude/skills/my-skill/SKILL.md

Controlla la sintassi YAML

YAML non valido impedisce il caricamento della Competenza. Verifica il frontmatter:
cat SKILL.md | head -n 10
Assicurati:
  • --- 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:
claude --debug

Condividere Competenze con il tuo team

Approccio raccomandato: Distribuisci Competenze attraverso plugin. Per condividere Competenze via plugin:
  1. Crea un plugin con Competenze nella directory skills/
  2. Aggiungi il plugin a un marketplace
  3. I membri del team installano il plugin
Per istruzioni complete, vedi Aggiungi Competenze al tuo plugin. Puoi anche condividere Competenze direttamente attraverso repository di progetto:

Passo 1: Aggiungi Competenza al tuo progetto

Crea una Competenza di progetto:
mkdir -p .claude/skills/team-skill
# Crea SKILL.md

Passo 2: Commit su git

git add .claude/skills/
git commit -m "Aggiungi Competenza team per elaborazione PDF"
git push

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:
git pull
claude  # Le Competenze sono ora disponibili

Aggiornare una Competenza

Modifica SKILL.md direttamente:
# Competenza Personale
code ~/.claude/skills/my-skill/SKILL.md

# Competenza di Progetto
code .claude/skills/my-skill/SKILL.md
Le modifiche hanno effetto la prossima volta che avvii Claude Code. Se Claude Code è già in esecuzione, riavvialo per caricare gli aggiornamenti.

Rimuovere una Competenza

Elimina la directory della Competenza:
# Personale
rm -rf ~/.claude/skills/my-skill

# Progetto
rm -rf .claude/skills/my-skill
git commit -m "Rimuovi Competenza inutilizzata"

Migliori pratiche

Mantieni le Competenze focalizzate

Una Competenza dovrebbe affrontare una capacità: Focalizzata:
  • “Compilazione moduli PDF”
  • “Analisi dati Excel”
  • “Messaggi commit Git”
Troppo ampia:
  • “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:
description: Analizza fogli di calcolo Excel, crea tabelle pivot e genera grafici. Usa quando lavori con file Excel, fogli di calcolo, o analizzando dati tabulari in formato .xlsx.
Vaga:
description: Per file

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:
# La Mia Competenza

## Cronologia Versioni
- v2.0.0 (2025-10-01): Modifiche breaking all'API
- v1.1.0 (2025-09-15): Aggiunte nuove funzionalità
- v1.0.0 (2025-09-01): Release iniziale
Questo aiuta i membri del team a capire cosa è cambiato tra le 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:
description: Aiuta con i dati
Specifica:
description: Analizza fogli di calcolo Excel, genera tabelle pivot, crea grafici. Usa quando lavori con file Excel, fogli di calcolo, o file .xlsx.
Controlla: Il YAML è valido? Esegui la validazione per controllare errori di sintassi:
# Visualizza frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# Controlla problemi comuni
# - --- di apertura o chiusura mancanti
# - Tab invece di spazi
# - Stringhe non quotate con caratteri speciali
Controlla: La Competenza è nella posizione corretta?
# Competenze Personali
ls ~/.claude/skills/*/SKILL.md

# Competenze di Progetto
ls .claude/skills/*/SKILL.md

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?
chmod +x .claude/skills/my-skill/scripts/*.py
Controlla: I percorsi dei file sono corretti? Usa barre in avanti (stile Unix) in tutti i percorsi: Corretto: 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:
# Competenza 1
description: Per analisi dati

# Competenza 2
description: Per analizzare dati
Usa:
# Competenza 1
description: Analizza dati di vendita in file Excel ed esportazioni CRM. Usa per report vendite, analisi pipeline e tracciamento ricavi.

# Competenza 2
description: Analizza file log e dati metriche sistema. Usa per monitoraggio prestazioni, debugging e diagnostica sistema.

Esempi

Competenza Semplice (file singolo)

commit-helper/
└── SKILL.md
---
name: Generazione Messaggi Commit
description: Genera messaggi commit chiari da diff git. Usa quando scrivi messaggi commit o rivedi modifiche staged.
---

# Generazione Messaggi Commit

## Istruzioni

1. Esegui `git diff --staged` per vedere le modifiche
2. Suggerirò un messaggio commit con:
   - Riassunto sotto 50 caratteri
   - Descrizione dettagliata
   - Componenti interessati

## Migliori pratiche

- Usa tempo presente
- Spiega cosa e perché, non come

Competenza con permessi strumenti

code-reviewer/
└── SKILL.md
---
name: Revisore Codice
description: Rivedi codice per migliori pratiche e problemi potenziali. Usa quando rivedi codice, controlli PR, o analizzi qualità codice.
allowed-tools: Read, Grep, Glob
---

# Revisore Codice

## Checklist revisione

1. Organizzazione e struttura codice
2. Gestione errori
3. Considerazioni prestazioni
4. Preoccupazioni sicurezza
5. Copertura test

## Istruzioni

1. Leggi i file target usando lo strumento Read
2. Cerca pattern usando Grep
3. Trova file correlati usando Glob
4. Fornisci feedback dettagliato sulla qualità del codice

Competenza Multi-file

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py
SKILL.md:
---
name: Elaborazione PDF
description: Estrai testo, compila moduli, unisci PDF. Usa quando lavori con file PDF, moduli, o estrazione documenti. Richiede pacchetti pypdf e pdfplumber.
---

# Elaborazione PDF

## Avvio rapido

Estrai testo:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Per compilazione moduli, vedi [FORMS.md](FORMS.md).
Per riferimento API dettagliato, vedi [REFERENCE.md](REFERENCE.md).

## Requisiti

I pacchetti devono essere installati nel tuo ambiente:
```bash
pip install pypdf pdfplumber
```
Elenca i pacchetti richiesti nella descrizione. I pacchetti devono essere installati nel tuo ambiente prima che Claude possa usarli.
Claude carica file aggiuntivi solo quando necessario.

Prossimi passi