Agent Skills

Perché usare Skills

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

Vantaggi principali:

• Specializza Claude: Personalizza le capacità per attività specifiche di dominio
• Riduci la ripetizione: Crea una volta, usa automaticamente
• Componi capacità: Combina Skills per costruire flussi di lavoro complessi

Utilizzo di Skills

Anthropic fornisce Agent Skills pre-costruite per attività comuni di documenti (PowerPoint, Excel, Word, PDF), e puoi creare le tue Skills personalizzate. Entrambe funzionano allo stesso modo. Claude le utilizza automaticamente quando rilevante per la tua richiesta.

Agent Skills pre-costruite sono disponibili per tutti gli utenti su claude.ai e tramite l'API Claude. Vedi la sezione Available Skills di seguito per l'elenco completo.

Custom Skills ti permettono di racchiudere 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

Skills sfruttano l'ambiente VM di Claude per fornire capacità oltre ciò che è possibile con i soli prompt. Claude opera in una macchina virtuale con accesso al filesystem, permettendo 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 progressive disclosure: Claude carica le informazioni in fasi secondo le necessità, piuttosto che consumare il contesto in anticipo.

Tre tipi di contenuto Skill, tre livelli di caricamento

Skills possono contenere tre tipi di contenuto, ognuno 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 conosce solo l'esistenza di ogni Skill 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 guida:

# 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 (caricate secondo le necessità)

Tipi di contenuto: Istruzioni, codice e risorse. 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 guida specializzata 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 referenziati. Il modello filesystem significa che ogni tipo di contenuto ha diversi punti di forza: istruzioni per guida flessibile, codice per affidabilità, risorse per ricerca fattuale.

La progressive disclosure assicura che solo il contenuto rilevante occupi la finestra di contesto in qualsiasi momento.

L'architettura delle Skills

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

Come Claude accede al contenuto Skill:

Quando una Skill è attivata, Claude usa bash per leggere SKILL.md dal filesystem, portando le sue istruzioni nella finestra di contesto. Se quelle istruzioni referenziano 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 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 dozzine di file di riferimento, ma se il tuo compito ha bisogno solo dello schema di vendita, Claude carica solo quel file. Il resto rimane sul filesystem consumando zero token.

Esecuzione efficiente dello script: Quando Claude esegue validate_form.py, il codice dello script non si carica 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 che avere Claude generi codice equivalente al volo.

Nessun limite pratico al contenuto raggruppato: Poiché i file non consumano contesto fino a quando non vengono accessati, 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 usato.

Questo modello basato su filesystem è ciò che rende possibile la progressive disclosure. Claude naviga la tua Skill come faresti riferimento a sezioni specifiche di una guida di onboarding, accedendo esattamente a ciò che ogni compito richiede.

Esempio: Caricamento di una skill di elaborazione PDF

Ecco come Claude carica e usa una skill di elaborazione PDF:

1. Avvio: Il prompt di sistema include: PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. Richiesta dell'utente: "Extract the text from this PDF and summarize it"
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 il compito

Il diagramma mostra:

1. Stato predefinito con prompt di sistema e metadati skill pre-caricati
2. Claude attiva la skill leggendo SKILL.md tramite bash
3. Claude legge opzionalmente file raggruppati aggiuntivi come FORMS.md secondo le necessità
4. Claude procede con il compito

Questo caricamento dinamico assicura che solo il contenuto skill rilevante occupi la finestra di contesto.

Dove funzionano le Skills

Skills sono disponibili su tutti i prodotti agente di Claude:

Claude API

L'API Claude supporta sia Agent Skills pre-costruite che Custom Skills. Entrambe funzionano in modo identico: specifica il skill_id rilevante nel parametro container insieme allo strumento di esecuzione del codice.

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

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

Usa Agent Skills pre-costruite referenziando il loro skill_id (ad es. pptx, xlsx), o crea e carica le tue tramite l'API Skills (/v1/skills endpoint). Le Custom Skills sono condivise a livello di organizzazione.

Per saperne di più, vedi Use Skills with the Claude API.

Claude Code

Claude Code supporta solo Custom Skills.

Custom Skills: Crea Skills come directory con file SKILL.md. Claude le scopre e le utilizza automaticamente.

Le Custom Skills in Claude Code sono basate su filesystem e non richiedono caricamenti API.

Per saperne di più, vedi Use Skills in Claude Code.

Claude Agent SDK

L'Claude Agent SDK supporta Custom Skills tramite configurazione basata su filesystem.

Custom Skills: Crea Skills come directory con file SKILL.md in .claude/skills/. Abilita 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ù, vedi Agent Skills in the SDK.

Claude.ai

Claude.ai supporta sia Agent Skills pre-costruite che Custom Skills.

Agent Skills pre-costruite: Queste Skills stanno già funzionando dietro le quinte quando crei documenti. Claude le utilizza senza richiedere alcuna configurazione.

Custom Skills: Carica le tue Skills come file zip tramite Settings > Features. Disponibile su piani Pro, Max, Team ed Enterprise con esecuzione del codice abilitata. Le Custom Skills 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 di Skills in Claude.ai, vedi le seguenti risorse nel Claude Help Center:

• What are Skills?
• Using Skills in Claude
• How to create custom Skills
• Teach Claude your way of working using Skills

Struttura 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 vuoto
• 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 di authoring completa, vedi la guida alle best practice.

Considerazioni sulla sicurezza

Consigliamo vivamente di usare Skills solo da fonti affidabili: quelle che hai creato tu stesso o ottenuto da Anthropic. Skills forniscono a Claude nuove capacità tramite istruzioni e codice, e mentre questo le rende 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:

• Controlla accuratamente: Rivedi 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: Skills che recuperano dati da URL esterni pongono rischio particolare, poiché il contenuto recuperato potrebbe contenere istruzioni malevolole. Anche Skills affidabili possono essere compromesse se le loro dipendenze esterne cambiano nel tempo
• Abuso di strumenti: Le Skill malevolole possono invocare strumenti (operazioni su file, comandi bash, esecuzione di codice) in modi dannosi
• Esposizione di dati: Skills con accesso a dati sensibili potrebbero essere progettate per perdere informazioni a sistemi esterni
• Tratta come installazione di software: Usa Skills solo da fonti affidabili. Sii particolarmente attento quando integri Skills in sistemi di produzione con accesso a dati sensibili o operazioni critiche

Available Skills

Agent Skills pre-costruite

Le seguenti Agent Skills pre-costruite sono disponibili per l'uso immediato:

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

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

Esempi di Custom Skills

Per esempi completi di Custom Skills, vedi il Skills cookbook.

Limitazioni e vincoli

Comprendere questi limiti ti aiuta a pianificare efficacemente il tuo deployment di Skills.

Disponibilità cross-surface

Le Custom Skills non si sincronizzano tra le superfici. Le Skills caricate su una superficie non sono automaticamente disponibili su 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 che dall'API

Dovrai gestire e caricare le Skills separatamente per ogni superficie dove vuoi usarle.

Ambito di condivisione

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

• Claude.ai: Solo utente individuale; ogni membro del team deve caricare separatamente
• Claude API: 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 non supporta attualmente la gestione centralizzata dell'amministratore o la distribuzione a livello di organizzazione di Custom Skills.

Vincoli dell'ambiente di runtime

L'esatto ambiente di runtime disponibile per la tua skill dipende dalla superficie del prodotto dove la usi.

• Claude.ai:
  • Accesso di rete variabile: A seconda delle impostazioni dell'utente/amministratore, le Skills possono avere accesso di rete completo, parziale o nessuno. Per più dettagli, vedi l'articolo di supporto Create and Edit Files.
• Claude API:
  • Nessun accesso di rete: Le Skills non possono effettuare chiamate API esterne o accedere a Internet
  • Nessuna installazione di pacchetti di runtime: Solo i pacchetti pre-installati sono disponibili. Non puoi installare nuovi pacchetti durante l'esecuzione.
  • Solo dipendenze pre-configurate: 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 di pacchetti globali sconsigliata: Le Skills dovrebbero installare pacchetti solo localmente per evitare di interferire con il computer dell'utente

Pianifica le tue Skills per funzionare all'interno di questi vincoli.

Prossimi passi