Agent Skills



Perché usare le Skills

Le Skills sono risorse riutilizzabili, basate su filesystem, che forniscono a Claude competenze specifiche di dominio: flussi di lavoro, contesto e best practice che trasformano un agente generico in uno specialista. A differenza dei prompt (istruzioni a livello di conversazione per attività una tantum), le Skills vengono caricate su richiesta, quindi non devi ripetere le stesse indicazioni in ogni conversazione.

Vantaggi principali:

• Specializza Claude: Adatta le capacità per attività specifiche di dominio
• Riduci le ripetizioni: Crea una volta, usa automaticamente
• Componi le capacità: Combina le Skills per attività complesse e multi-step



Usare le Skills

Anthropic fornisce Agent Skills predefinite per le attività documentali più comuni (PowerPoint, Excel, Word, PDF), e puoi creare le tue Skills personalizzate. Entrambe funzionano allo stesso modo: una volta che una Skill è disponibile nel tuo ambiente, Claude la usa automaticamente quando è pertinente alla tua richiesta.

Le Agent Skills predefinite sono disponibili su claude.ai, sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry. Su Microsoft Foundry, le Agent Skills richiedono un deployment Hosted on Anthropic. Consulta Skills disponibili per l'elenco completo.

Le Skills personalizzate ti permettono di racchiudere competenze di dominio e conoscenze organizzative. Sono disponibili in tutti i prodotti di Claude: creale in Claude Code, caricale tramite la Claude API o aggiungile nelle impostazioni di claude.ai. Su Claude Platform on AWS e Microsoft Foundry, carica le Skills personalizzate tramite la Skills API.



Come funzionano le Skills

Le Skills utilizzano l'ambiente VM di Claude per fornire capacità che vanno oltre ciò che è possibile con i soli prompt. Claude opera in una macchina virtuale con accesso al filesystem, consentendo alle Skills di esistere come directory contenenti istruzioni, codice eseguibile e materiali di riferimento, organizzati come una guida di onboarding che creeresti per un nuovo membro del team.

Questa architettura basata su filesystem abilita la progressive disclosure (divulgazione progressiva): Claude carica le informazioni in fasi, man mano che servono, invece di consumare contesto in anticipo.

Le Skills possono contenere tre tipi di contenuto, ciascuno caricato in un momento diverso:



Livello 1: Metadati (sempre caricati)

Il frontmatter YAML della Skill fornisce le informazioni per la scoperta:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

Claude carica questi metadati all'avvio e li include nel prompt di sistema. La description è ciò che Claude confronta con la tua richiesta per determinare se attivare la Skill, quindi deve indicare sia cosa fa la Skill sia quando usarla. Questo approccio leggero significa che puoi installare molte Skills senza penalità di contesto: finché una Skill non viene attivata, solo il suo nome e la sua descrizione occupano contesto.



Livello 2: Istruzioni (caricate all'attivazione)

Il corpo principale di SKILL.md contiene conoscenza procedurale: flussi di lavoro, best practice e indicazioni:

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).

Quando richiedi qualcosa che corrisponde alla descrizione di una Skill, Claude legge SKILL.md dal filesystem usando bash. Solo allora questo contenuto entra nella finestra di contesto.



Livello 3: Risorse e codice (caricati secondo necessità)

Le Skills possono includere materiali aggiuntivi:

pdf-processing/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

Istruzioni: File markdown aggiuntivi (FORMS.md, REFERENCE.md) contenenti indicazioni e flussi di lavoro specializzati

Codice: Script eseguibili (fill_form.py, validate.py) che Claude esegue usando bash, fornendo operazioni deterministiche senza caricare il loro codice nel contesto

Risorse: Materiali di riferimento come schemi di database, documentazione API, template o esempi

Claude accede a questi file solo quando vengono referenziati. Il modello basato su filesystem significa che ogni tipo di contenuto ha punti di forza diversi: istruzioni per indicazioni flessibili, codice per l'affidabilità, risorse per la consultazione di fatti.

La progressive disclosure garantisce che solo il contenuto pertinente occupi la finestra di contesto in un dato momento.



L'architettura delle Skills

Le Skills vengono eseguite in un ambiente di esecuzione del codice in cui Claude ha accesso al filesystem, comandi bash e capacità di esecuzione del codice. Le Skills esistono come directory su una macchina virtuale e Claude interagisce con esse usando gli stessi comandi bash che useresti per navigare tra i file sul tuo computer.

Come Claude accede al contenuto delle Skills:

Quando una Skill viene attivata, Claude usa bash per leggere SKILL.md dal filesystem, portando le sue istruzioni nella finestra di contesto. Se quelle istruzioni fanno riferimento ad altri file (come FORMS.md o uno schema di database), Claude legge anche quei file usando comandi bash aggiuntivi. Quando le istruzioni menzionano script eseguibili, Claude li esegue tramite bash e riceve solo l'output (il codice dello script stesso non entra mai nel contesto).

Cosa abilita questa architettura:

• Accesso ai file su richiesta: Claude legge solo i file necessari per ogni attività. Una Skill può includere decine di file di riferimento, ma se la tua attività richiede solo lo schema delle vendite, quello è l'unico file che Claude carica. Il resto rimane sul filesystem e costa zero token.
• Esecuzione efficiente degli script: Quando Claude esegue validate_form.py, il codice dello script non viene mai caricato nella finestra di contesto. Solo il suo output (come "Validation passed" o un messaggio di errore specifico) consuma token, il che rende gli script molto più efficienti rispetto a far generare a Claude codice equivalente al volo.
• Nessun limite pratico sul contenuto incluso: I file non consumano contesto finché non vi si accede, quindi le Skills possono includere documentazione API completa, grandi dataset o esempi estesi. Non c'è alcuna penalità di contesto per il contenuto incluso che non viene utilizzato.



Esempio: Caricamento di una Skill di elaborazione PDF

Ecco come Claude carica e usa la Skill personalizzata pdf-processing degli esempi precedenti (non la Skill predefinita pdf):

1. Avvio: Il prompt di sistema include: pdf-processing - Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
2. Richiesta dell'utente: "Estrai il testo da questo PDF e riassumilo"
3. Claude invoca: bash: cat pdf-processing/SKILL.md → Istruzioni caricate nel contesto
4. Claude determina: La compilazione di moduli non è necessaria, quindi FORMS.md non viene letto
5. Claude esegue: Usa le istruzioni di SKILL.md per completare l'attività



Dove funzionano le Skills

Le Skills sono disponibili in tutti i prodotti agentici di Claude:



Claude API

La Claude API supporta sia le Agent Skills predefinite sia le Skills personalizzate. Entrambe funzionano in modo identico: specifica lo skill_id pertinente nel parametro container insieme allo strumento di esecuzione del codice.

Prerequisiti: L'uso delle Skills tramite l'API richiede lo strumento di esecuzione del codice, nel cui container vengono eseguite le Skills, e un header beta:

• skills-2025-10-02 - Abilita la funzionalità Skills

Aggiungi un secondo header, files-api-2025-04-14, quando usi la Files API per caricare file di input nel container o scaricare file prodotti da una Skill.

Usa le Agent Skills predefinite facendo riferimento al loro skill_id (pptx, xlsx, docx o pdf), oppure crea e carica le tue tramite la Skills API (endpoint /v1/skills). Le Skills personalizzate sono condivise a livello di workspace: tutti i membri del workspace possono accedervi.

Le Skills sull'API vengono eseguite in un container sandbox senza accesso alla rete e senza installazione di pacchetti a runtime. Consulta Limitazioni e vincoli per i dettagli.

Per saperne di più, consulta Usare le Agent Skills con l'API.



Claude Code

Claude Code supporta le Skills personalizzate. Le Skills documentali predefinite (PowerPoint, Excel, Word, PDF) non sono disponibili in Claude Code, anche se la Claude API skill open source è inclusa con esso. Consulta l'elenco completo dei comandi e delle Skills integrati forniti con Claude Code.

Skills personalizzate: Crea le Skills come directory con file SKILL.md. Claude le scopre e le usa automaticamente.

Le Skills personalizzate in Claude Code sono basate su filesystem e non richiedono caricamenti tramite API: posizionale in ~/.claude/skills/ (personali) o .claude/skills/ (di progetto).

Per saperne di più, consulta Usare le Skills in Claude Code.



claude.ai

claude.ai supporta sia le Agent Skills predefinite sia le Skills personalizzate.

Agent Skills predefinite: Queste Skills sono attive quando crei documenti. Claude le usa senza alcuna configurazione richiesta.

Skills personalizzate: Carica le tue Skills come file zip tramite Impostazioni > Funzionalità. Disponibili sui piani Pro, Max, Team ed Enterprise con l'esecuzione del codice abilitata. Le Skills personalizzate sono individuali per ogni utente. Non sono condivise a livello di organizzazione e non possono essere gestite centralmente dagli amministratori.

Per saperne di più sull'uso delle Skills in claude.ai, consulta le seguenti risorse nel Centro assistenza di Claude:

• Cosa sono le Skills?
• Usare le Skills in Claude
• Come creare Skills personalizzate
• Insegna a Claude il tuo modo di lavorare usando le Skills



Struttura di una Skill

Ogni Skill richiede un file SKILL.md con frontmatter YAML:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

Campi obbligatori: name e description

Requisiti dei campi:

name:

• Massimo 64 caratteri
• Deve contenere solo lettere minuscole, numeri e trattini
• Non può contenere tag XML
• Non può contenere le parole riservate: "anthropic", "claude"

description:

• Non deve essere vuoto
• Massimo 1024 caratteri
• Non può contenere tag XML

La description deve includere sia cosa fa la Skill sia quando Claude dovrebbe usarla. Per una guida completa alla creazione, consulta Best practice per la creazione di Skills.



Considerazioni sulla sicurezza

Usa le Skills solo da fonti affidabili: quelle che hai creato tu stesso o ottenuto da Anthropic. Le Skills danno a Claude nuove capacità tramite istruzioni e codice, il che significa anche che una Skill malevola può indurre Claude a invocare strumenti o eseguire codice in modi che non corrispondono allo scopo dichiarato della Skill.

Considerazioni chiave sulla sicurezza:

• Verifica a fondo: Esamina tutti i file inclusi nella Skill: SKILL.md, script, immagini e altre risorse. Cerca pattern insoliti come chiamate di rete inattese, pattern di accesso ai file o operazioni che non corrispondono allo scopo dichiarato della Skill
• Le fonti esterne sono rischiose: Le Skills che recuperano dati da URL esterni rappresentano un rischio particolare, poiché il contenuto recuperato può contenere istruzioni malevole. Anche le Skills affidabili possono essere compromesse se le loro dipendenze esterne cambiano nel tempo
• Uso improprio degli strumenti: Le Skills malevole possono invocare strumenti (operazioni sui file, comandi bash, esecuzione di codice) in modi dannosi
• Esposizione dei dati: Le Skills con accesso a dati sensibili potrebbero essere progettate per far trapelare informazioni verso sistemi esterni
• Trattale come l'installazione di software: Presta particolare attenzione quando integri le Skills in sistemi di produzione con accesso a dati sensibili o operazioni critiche

Per indicazioni su governance, verifica e deployment su scala organizzativa, consulta Skills per le aziende.



Skills disponibili



Agent Skills predefinite

Le seguenti Agent Skills predefinite sono disponibili per l'uso immediato:

• PowerPoint (pptx): Crea presentazioni, modifica diapositive, analizza il contenuto delle presentazioni
• Excel (xlsx): Crea fogli di calcolo, analizza dati, genera report con grafici
• Word (docx): Crea documenti, modifica contenuti, formatta testo
• PDF (pdf): Genera documenti e report PDF formattati

Queste Skills sono disponibili sulla Claude API, su Claude Platform on AWS, su Microsoft Foundry e su claude.ai. Consulta il tutorial di avvio rapido per iniziare a usarle nell'API.



Skills open source

Anthropic pubblica anche Skills open source nel repository delle skills:

• Claude API skill: Fornisce a Claude materiale di riferimento API aggiornato, documentazione degli SDK e best practice per otto linguaggi di programmazione. Inclusa con Claude Code e disponibile anche per l'installazione dal repository delle skills.



Esempi di Skills personalizzate

Per esempi completi di Skills personalizzate, consulta il cookbook delle Skills.



Conservazione dei dati

Le Agent Skills non sono coperte dagli accordi ZDR. Le definizioni delle Skills e i dati di esecuzione vengono conservati secondo la politica standard di conservazione dei dati di Anthropic.

Per l'idoneità ZDR di tutte le funzionalità, consulta API e conservazione dei dati.



Limitazioni e vincoli

Claude Platform on AWS e Microsoft Foundry seguono le stesse limitazioni della Claude API nelle sottosezioni seguenti.



Disponibilità tra superfici

Le Skills personalizzate non si sincronizzano tra le superfici. Le Skills caricate su una superficie non sono automaticamente disponibili sulle altre:

• Le Skills caricate su claude.ai devono essere caricate separatamente sull'API
• Le Skills caricate tramite l'API non sono disponibili su claude.ai
• Le Skills di Claude Code sono basate su filesystem e separate sia da claude.ai sia dall'API

Gestisci e carica le Skills separatamente per ogni superficie in cui vuoi usarle.



Ambito di condivisione

Le Skills hanno modelli di condivisione diversi a seconda di dove le usi:

• claude.ai: Solo utente individuale. Ogni membro del team deve caricarle separatamente.
• Claude API: A livello di workspace. Tutti i membri del workspace possono accedere alle Skills caricate.
• Claude Code: Personali (~/.claude/skills/) o di progetto (.claude/skills/). Possono anche essere condivise tramite i Plugin di Claude Code.

claude.ai non supporta la gestione centralizzata da parte degli amministratori né la distribuzione a livello di organizzazione delle Skills personalizzate.



Vincoli dell'ambiente di runtime

L'esatto ambiente di runtime disponibile per la tua Skill dipende dalla superficie di prodotto in cui la usi.

• claude.ai:
  • Accesso alla rete variabile: A seconda delle impostazioni dell'utente/amministratore, le Skills possono avere accesso alla rete completo, parziale o nullo. Per maggiori dettagli, consulta l'articolo di supporto Create and Edit Files.
• Claude API:
  • Nessun accesso alla rete: Le Skills non possono effettuare chiamate API esterne né accedere a internet.
  • Nessuna installazione di pacchetti a runtime: Sono disponibili solo i pacchetti preinstallati. Non puoi installare nuovi pacchetti durante l'esecuzione.
  • Solo dipendenze preconfigurate: Controlla la documentazione dello strumento di esecuzione del codice per l'elenco dei pacchetti disponibili.
• Claude Code:
  • Accesso completo alla rete: Le Skills hanno lo stesso accesso alla rete di qualsiasi altro programma sul computer dell'utente.
  • Installazione globale di pacchetti sconsigliata: Le Skills dovrebbero installare i pacchetti solo localmente per evitare di interferire con il computer dell'utente.

Progetta le tue Skills per funzionare entro questi vincoli.



Prossimi passi