Agent Skills

Perché usare le Skills

Le Skills sono risorse riutilizzabili basate sul filesystem che forniscono a Claude competenze specifiche per dominio: flussi di lavoro, contesto e best practice che trasformano gli agenti di uso generale in specialisti. A differenza dei prompt (istruzioni a livello di conversazione per attività una tantum), le Skills si caricano su richiesta ed eliminano la necessità di fornire ripetutamente le stesse indicazioni in più conversazioni.

Vantaggi principali:

• Specializzare Claude: Adattare le capacità per attività specifiche del dominio
• Ridurre la ripetizione: Creare una volta, usare automaticamente
• Comporre capacità: Combinare Skills per costruire flussi di lavoro complessi

Utilizzo delle Skills

Anthropic fornisce Agent Skills precostruite per attività comuni con documenti (PowerPoint, Excel, Word, PDF), e puoi creare le tue Skills personalizzate. Entrambe funzionano allo stesso modo. Claude le utilizza automaticamente quando sono pertinenti alla tua richiesta.

Le Agent Skills precostruite sono disponibili per tutti gli utenti su claude.ai e tramite l'API di Claude. Consulta la sezione Skills disponibili di seguito per l'elenco completo.

Le Skills personalizzate ti permettono di raggruppare competenze di dominio e conoscenze organizzative. Sono disponibili su tutti i prodotti di Claude: creale in Claude Code, caricale tramite l'API, o aggiungile nelle impostazioni di claude.ai.

Come funzionano le Skills

Le Skills sfruttano 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 sul filesystem abilita la divulgazione progressiva: Claude carica le informazioni in fasi secondo necessità, invece di consumare contesto in anticipo.

Tre tipi di contenuto Skill, tre livelli di caricamento

Le Skills possono contenere tre tipi di contenuto, ciascuno caricato in momenti diversi:

Livello 1: Metadati (sempre caricati)

Tipo di contenuto: Istruzioni. Il frontmatter YAML della Skill fornisce informazioni di 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. Questo approccio leggero significa che puoi installare molte Skills senza penalità di contesto; Claude sa solo che ogni Skill esiste e quando usarla.

Livello 2: Istruzioni (caricate quando attivate)

Tipo di contenuto: Istruzioni. Il corpo principale di SKILL.md contiene conoscenze procedurali: 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 tramite bash. Solo allora questo contenuto entra nella finestra di contesto.

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

Tipi di contenuto: Istruzioni, codice e risorse. Le Skills possono raggruppare materiali aggiuntivi:

pdf-skill/
├── 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 specializzate e flussi di lavoro

Codice: Script eseguibili (fill_form.py, validate.py) che Claude esegue tramite bash; gli script forniscono operazioni deterministiche senza consumare 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 sul filesystem significa che ogni tipo di contenuto ha punti di forza diversi: le istruzioni per una guida flessibile, il codice per l'affidabilità, le risorse per la consultazione fattuale.

La divulgazione progressiva 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. Pensaci così: le Skills esistono come directory su una macchina virtuale, e Claude interagisce con esse usando gli stessi comandi bash che useresti per navigare i file sul tuo computer.

Come Claude accede al contenuto delle Skill:

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 ulteriori comandi bash. 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à specifica. Una Skill può includere decine di file di riferimento, ma se il tuo compito richiede solo lo schema delle vendite, Claude carica solo quel file. Il resto rimane sul filesystem consumando 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 l'output dello script (come "Validation passed" o messaggi di errore specifici) consuma token. Questo rende gli script molto più efficienti rispetto al fatto che Claude generi codice equivalente al volo.

Nessun limite pratico al contenuto raggruppato: Poiché i file non consumano contesto finché non vengono acceduti, le Skills possono includere documentazione API completa, grandi dataset, esempi estesi o qualsiasi materiale di riferimento di cui hai bisogno. Non c'è penalità di contesto per il contenuto raggruppato che non viene utilizzato.

Questo modello basato sul filesystem è ciò che fa funzionare la divulgazione progressiva. Claude naviga la tua Skill come faresti riferimento a sezioni specifiche di una guida di onboarding, accedendo esattamente a ciò che ogni attività richiede.

Esempio: Caricamento di una skill per l'elaborazione PDF

Ecco come Claude carica e usa una skill per l'elaborazione PDF:

1. Avvio: Il prompt di sistema include: PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. Richiesta utente: "Estrai il testo da questo PDF e riassumilo"
3. Claude invoca: bash: read pdf-skill/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 da SKILL.md per completare l'attività

Il diagramma mostra:

1. Stato predefinito con prompt di sistema e metadati delle skill precaricati
2. Claude attiva la skill leggendo SKILL.md tramite bash
3. Claude legge opzionalmente file raggruppati aggiuntivi come FORMS.md secondo necessità
4. Claude procede con l'attività

Questo caricamento dinamico garantisce che solo il contenuto pertinente delle skill occupi la finestra di contesto.

Dove funzionano le Skills

Le Skills sono disponibili su tutti i prodotti agente di Claude:

API di Claude

L'API di Claude supporta sia le Agent Skills precostruite che le Skills personalizzate. Entrambe funzionano in modo identico: specifica il skill_id pertinente nel parametro container insieme allo strumento di esecuzione del codice.

Prerequisiti: L'utilizzo delle Skills tramite l'API richiede tre header beta:

• code-execution-2025-08-25 - Le Skills vengono eseguite nel container di esecuzione del codice
• skills-2025-10-02 - Abilita la funzionalità delle Skills
• files-api-2025-04-14 - Necessario per caricare/scaricare file da/verso il container

Usa le Agent Skills precostruite facendo riferimento al loro skill_id (ad esempio, pptx, xlsx), oppure crea e carica le tue tramite l'API delle Skills (endpoint /v1/skills). Le Skills personalizzate sono condivise a livello di organizzazione.

Per saperne di più, consulta Usa le Skills con l'API di Claude.

Claude Code

Claude Code supporta solo le Skills personalizzate.

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

Le Skills personalizzate in Claude Code sono basate sul filesystem e non richiedono caricamenti tramite API.

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

Claude Agent SDK

Il Claude Agent SDK supporta le Skills personalizzate tramite configurazione basata sul filesystem.

Skills personalizzate: Crea Skills come directory con file SKILL.md in .claude/skills/. Abilita le Skills includendo "Skill" nella tua configurazione allowed_tools.

Le Skills nell'Agent SDK vengono quindi scoperte automaticamente quando l'SDK viene eseguito.

Per saperne di più, consulta Agent Skills nell'SDK.

Claude.ai

Claude.ai supporta sia le Agent Skills precostruite che le Skills personalizzate.

Agent Skills precostruite: Queste Skills funzionano già in background quando crei documenti. Claude le usa senza richiedere alcuna configurazione.

Skills personalizzate: Carica le tue Skills come file zip tramite Impostazioni > Funzionalità. Disponibile 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'utilizzo delle Skills in Claude.ai, consulta le seguenti risorse nel Centro assistenza di Claude:

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

Struttura delle 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 parole riservate: "anthropic", "claude"

description:

• Deve essere non vuota
• Massimo 1024 caratteri
• Non può contenere tag XML

La description dovrebbe includere sia cosa fa la Skill che quando Claude dovrebbe usarla. Per una guida completa alla creazione, consulta la guida alle best practice.

Considerazioni sulla sicurezza

Raccomandiamo vivamente di usare Skills solo da fonti attendibili: quelle che hai creato tu stesso o ottenuto da Anthropic. Le Skills forniscono a Claude nuove capacità tramite istruzioni e codice, e sebbene questo le renda potenti, significa anche che una Skill malevola può dirigere Claude a invocare strumenti o eseguire codice in modi che non corrispondono allo scopo dichiarato della Skill.

Considerazioni chiave sulla sicurezza:

• Verifica accuratamente: Esamina tutti i file raggruppati nella Skill: SKILL.md, script, immagini e altre risorse. Cerca pattern insoliti come chiamate di rete inaspettate, 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 potrebbe 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 a sistemi esterni
• Trattala come l'installazione di software: Usa Skills solo da fonti attendibili. Sii particolarmente attento quando integri Skills in sistemi di produzione con accesso a dati sensibili o operazioni critiche

Skills disponibili

Agent Skills precostruite

Le seguenti Agent Skills precostruite 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 PDF formattati e report

Queste Skills sono disponibili sull'API di Claude e su claude.ai. Consulta il tutorial di avvio rapido per iniziare a usarle nell'API.

Esempi di Skills personalizzate

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

Conservazione dei dati

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

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

Limitazioni e vincoli

Comprendere queste limitazioni ti aiuta a pianificare efficacemente il deployment delle tue Skills.

Disponibilità cross-surface

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 sul filesystem e separate sia da Claude.ai che dall'API

Dovrai gestire e caricare 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
• API di Claude: A livello di workspace; tutti i membri del workspace possono accedere alle Skills caricate
• Claude Code: Personale (~/.claude/skills/) o basato su progetto (.claude/skills/); può anche essere condiviso tramite Claude Code Plugins

Claude.ai attualmente non supporta la gestione centralizzata da parte degli amministratori o 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 del prodotto in cui la usi.

• Claude.ai:
  • Accesso di rete variabile: A seconda delle impostazioni utente/amministratore, le Skills possono avere accesso di rete completo, parziale o nessuno. Per maggiori dettagli, consulta l'articolo di supporto Crea e modifica file.
• API di Claude:
  • Nessun accesso di rete: Le Skills non possono effettuare chiamate API esterne o accedere a Internet
  • Nessuna installazione di pacchetti in 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 di rete completo: Le Skills hanno lo stesso accesso di rete di qualsiasi altro programma sul computer dell'utente
  • Installazione globale dei pacchetti sconsigliata: Le Skills dovrebbero installare i pacchetti solo localmente per evitare di interferire con il computer dell'utente

Pianifica le tue Skills per funzionare entro questi vincoli.

Prossimi passi