Skill

Le skill sono risorse riutilizzabili basate su filesystem che forniscono al tuo agente competenze specifiche del dominio: flussi di lavoro, contesto e best practice che trasformano un agente generico in uno specialista. Ogni skill che aggiungi comporta un costo modesto sulla "context window" (finestra di contesto) della sessione, aggiungendo istruzioni e metadati che aiutano il modello a utilizzare la skill. Scopri di più nella panoramica Agent Skills.

Le skill raggiungono il tuo agente in due modi: collegale tramite l'array skills dell'agente, oppure caricale da un repository GitHub montato sulla sessione. Le skill collegate sono di due tipi. Tutte le skill funzionano allo stesso modo: il tuo agente le invoca automaticamente quando sono rilevanti per l'attività.

• Skill predefinite di Anthropic: Attività comuni sui documenti come la gestione di PowerPoint, Excel, Word e PDF (pptx, xlsx, docx, pdf).
• Skill personalizzate: Skill che crei e carichi nel tuo workspace.

Per imparare a creare skill personalizzate, consulta Agent Skills e Best practice per la creazione di skill. Per caricare una skill personalizzata nel tuo workspace, consulta Creare una skill personalizzata.



Creare una skill personalizzata

Una skill personalizzata è una directory contenente un file SKILL.md più eventuali file di supporto, caricata nel tuo workspace come archivio zip o come file individuali. La creazione della skill restituisce l'ID skill_* a cui fai riferimento quando la colleghi a un agente. Le skill predefinite di Anthropic sono già disponibili in ogni workspace e non richiedono questo passaggio. Per utilizzare solo skill predefinite, passa direttamente a Collegare skill a un agente.

L'API Skills non richiede un header beta. L'esempio cURL invia comunque anthropic-beta: skills-2025-10-02, e i comandi beta della CLI e dell'SDK lo aggiungono automaticamente; le richieste che lo includono continuano a funzionare senza modifiche.

Questi esempi omettono il campo opzionale display_title, quindi il titolo della skill viene derivato da SKILL.md. Un display_title passato esplicitamente deve essere univoco tra le skill personalizzate nel tuo workspace.

ant beta:skills create \
  --file example_skill.zip

Per elencare, recuperare, eliminare e versionare le skill personalizzate, consulta Gestione delle skill personalizzate. Per gli schemi completi di richiesta e risposta, consulta il riferimento API Create Skill. I bundle delle skill vengono caricati direttamente nell'API Skills anziché tramite la Files API.



Collegare skill a un agente

Collega le skill quando crei un agente. Ogni sessione supporta fino a 500 skill, conteggiate come l'insieme deduplicato tra tutti gli agenti nella sessione (consulta Orchestrazione multiagente).

Ogni voce nell'array skills utilizza i seguenti campi:

ant beta:agents create < agent.yaml

name: Financial Analyst
model: claude-opus-5
system: You are a financial analysis agent.
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest



Caricare skill da un repository GitHub

Le skill possono anche risiedere nella tua codebase. Quando una sessione monta un repository tramite la risorsa github_repository, la directory .claude/skills alla radice del repository viene scansionata all'avvio della sessione, e ogni skill trovata lì diventa disponibile per l'agente. Non sono richiesti né un caricamento né una voce nell'array skills dell'agente. L'agente vede il nome, la descrizione e il percorso nella sandbox di ogni skill rilevata, e legge il file SKILL.md della skill quando un'attività corrisponde, inclusi eventuali script e risorse forniti con la skill. Il rilevamento si basa sullo strumento read dell'agente dal set di strumenti dell'agente, che è abilitato per impostazione predefinita; un agente con read disabilitato non carica le skill del repository.

Il rilevamento trova le skill esattamente in .claude/skills/<skill-name>/SKILL.md, a un livello di directory di profondità dalla radice del repository:

• your-repo/
  • .claude/
    • skills/
      • code-review/
        • SKILL.md
      • release-process/
        • SKILL.md
        • scripts/
          • run_checks.sh
  • src/

Le posizioni che non corrispondono a questa struttura non vengono rilevate all'avvio della sessione:

• .claude/skills/SKILL.md: un SKILL.md senza una directory skill che lo contenga
• .claude/skills/tools/code-review/SKILL.md: annidato a più di un livello di directory di profondità
• skills/code-review/SKILL.md: una directory skills al di fuori di .claude

Una directory .claude/skills altrove nel repository, ad esempio all'interno di una sottodirectory di un pacchetto, non viene annunciata all'avvio della sessione; quelle skill possono comunque emergere quando l'agente legge i file in quel sottoalbero.

Le skill del repository utilizzano lo stesso formato SKILL.md delle skill personalizzate che carichi. Per il formato e le indicazioni sulla creazione, consulta Agent Skills e Best practice per la creazione di skill.

Per caricare skill da un repository, crea una sessione che lo monti. Questa è la stessa richiesta mostrata in Accesso a GitHub; mount_path è opzionale e il valore predefinito è /workspace/<repo-name>:

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)

Per i repository privati, l'authorization_token della risorsa deve avere accesso al repository. Questo è lo stesso flusso del personal access token utilizzato per qualsiasi montaggio di repository; consulta Accesso a GitHub.

Le skill rilevate seguono lo stato di checkout del repository: il branch o commit di checkout quando la risorsa ne imposta uno, altrimenti il branch predefinito del repository. La scansione viene eseguita una sola volta, all'avvio della sessione. I commit inviati durante la sessione non vengono rilevati; per caricare skill aggiornate, avvia una nuova sessione.

Le skill del repository funzionano insieme alle skill collegate tramite l'array skills dell'agente. Se una skill del repository condivide un nome con una skill collegata, o con una skill di un altro repository montato, entrambe sono disponibili; ciascuna viene annunciata con il proprio percorso.



Passaggi successivi