Skip to main content
Agent Skills estendono Claude con capacità specializzate che Claude richiama quando rilevante. Le Skills sono confezionate come file SKILL.md contenenti istruzioni, descrizioni e risorse di supporto opzionali. Questa pagina copre anche i comandi nelle sessioni dell’Agent SDK. Per informazioni complete sulle skill, inclusi vantaggi, architettura e linee guida di authoring, consulta la panoramica di Agent Skills.

Come funzionano le skills con l’Agent SDK

Quando si utilizza l’SDK dell’Agent Claude, le skills sono:
  • Definite come artefatti del filesystem: crei ogni skill come file SKILL.md nella sua directory, ad esempio .claude/skills/<name>/SKILL.md
  • Caricate dal filesystem: l’SDK carica le skills dalle posizioni del filesystem governate da settingSources (TypeScript) o setting_sources (Python)
  • Scoperte automaticamente: una volta caricate le impostazioni del filesystem, l’SDK scopre i metadati della skill all’avvio dalle directory dell’utente e del progetto, e carica il contenuto completo quando Claude richiama la skill
  • Richiamate dal modello: Claude sceglie autonomamente quando utilizzarle in base al contesto
  • Richiamate dall’utente: invii una skill direttamente inviando /<name> in un prompt. Vedi Comandi nelle sessioni dell’Agent SDK
  • Limitate tramite l’opzione skills: le skills scoperte sono abilitate per impostazione predefinita. Passa un elenco di nomi di skills, "all", o [] per controllare quali skills Claude può invocare
A differenza dei subagents, che puoi definire nell’opzione agents, crei le skills come file su disco. L’SDK non fornisce un’API programmatica per registrarle.
Le skills vengono scoperte attraverso le fonti di impostazione del filesystem. Con le opzioni predefinite di query(), l’SDK carica le fonti utente e progetto, quindi le skills in ~/.claude/skills/, <cwd>/.claude/skills/, e .claude/skills/ in qualsiasi directory padre di <cwd> fino alla radice del repository sono disponibili. La fonte del progetto copre anche <dir>/.claude/skills/ in ogni directory che passi attraverso additionalDirectories (TypeScript) o add_dirs (Python), perché l’SDK passa quelle directory a Claude Code come --add-dir. Se imposti settingSources esplicitamente, includi 'project' per mantenere le skills del progetto e della directory aggiunta e 'user' per mantenere le tue skills personali, oppure utilizza l’opzione plugins per caricare le skills da un percorso specifico.

Utilizza le skills con l’Agent SDK

Imposta l’opzione skills su query() per controllare quali skills Claude può invocare nella sessione. Se omessa, le skills scoperte sono abilitate e lo strumento Skill è disponibile, corrispondendo al comportamento della CLI. Passa "all" per consentire a Claude di invocare ogni skill scoperta, un elenco di nomi di skills per consentire solo quelle, o [] per consentire a Claude di non invocarne nessuna. Ad esempio, per consentire a Claude di invocare solo due skills denominate:

Configura le skills in una sessione

Quando imposti skills, l’SDK aggiunge automaticamente lo strumento Skill a allowedTools. Se passi anche un elenco esplicito di tools, includi "Skill" in quell’elenco in modo che Claude possa invocare le skills. Una volta configurato, Claude scopre automaticamente le skills dal filesystem e le richiama quando rilevante per la richiesta dell’utente. L’esempio seguente abilita ogni skill scoperta in una sessione e pre-approva gli strumenti che le skills comunemente necessitano. L’esempio imposta cwd sulla directory di lavoro corrente del processo, quindi eseguilo dall’interno di un progetto che ha una directory .claude/skills/ nella directory corrente o in qualsiasi directory padre fino alla radice del repository:

Conferma che le skills sono caricate

Vicino all’inizio dello stream, l’SDK produce un messaggio di sistema con sottotipo init. Controlla il suo array skills per confermare che le tue skills siano caricate prima che Claude inizi a lavorare. L’array include le skills invocabili dall’utente che hai definito con un campo frontmatter description o when_to_use, insieme alle skills incluse nel bundle con Claude Code. L’array elenca solo le skills invocabili dall’utente. Una skill con user-invocable: false nel suo frontmatter si carica e rimane disponibile per Claude, ma non appare nell’array. L’array elenca le stesse skills indipendentemente dal fatto che siano nel tuo elenco skills.

Consenti solo skills specifiche

Per consentire a Claude di invocare solo skills specifiche, passa i loro nomi nell’elenco skills. I nomi corrispondono al campo name in SKILL.md o al nome della directory della skill. Utilizza plugin:skill per le skills fornite da plugin. L’elenco accetta solo nomi di skills esatti. Se una voce non può funzionare come nome esatto, query() rifiuta l’elenco prima che la sessione inizi. Vedi Errore di nome skill non valido per le regole dei nomi e l’errore che ogni SDK genera. Il modello non vede le skills non elencate e lo strumento Skill le rifiuta, mentre i loro file rimangono su disco e rimangono raggiungibili attraverso Read e Bash. Limitare l’elenco non limita l’invio per nome. Per consentire a Claude di invocare ogni skill scoperta, passa skills: "all" piuttosto che un wildcard.

Comandi nelle sessioni dell’Agent SDK

Questa sezione è la documentazione dei comandi dell’SDK. Un comando è qualsiasi cosa tu esegua inviando /<name> in un prompt. Le voci sulla superficie del comando differiscono in ciò che le supporta:
  • Comandi incorporati: eseguono la logica codificata nel processo Claude Code che l’SDK esegue, ad esempio /compact
  • Skills nel bundle: artefatti prompt inclusi con Claude Code, ad esempio /code-review
  • Le tue skills: artefatti prompt che crei, ognuno una directory che contiene un file SKILL.md. Il nome di una skill invocabile dall’utente si unisce automaticamente alla superficie, quindi inviare il tuo /security-check e eseguire un incorporato funzionano allo stesso modo
  • File di comando personalizzati: una forma di artefatto più vecchia con lo stesso comportamento, file Markdown flat in .claude/commands/ i cui nomi di file diventano nomi di comandi. Le skills sono il loro successore consigliato
Per impostazione predefinita, sia tu che Claude potete invocare qualsiasi skill. Puoi limitare entrambi i percorsi attraverso il frontmatter della skill. Per una definizione dei due termini, vedi le voci del glossario Comando e Skill. Vedi Comandi in Claude Code per ogni incorporato e Estendi Claude con skills per la guida completa a entrambe le forme di artefatto.

Scopri i comandi disponibili

Puoi inviare comandi che funzionano senza un terminale interattivo attraverso l’SDK. Il messaggio system/init elenca quelli disponibili nella tua sessione nel suo campo slash_commands. I comandi che necessitano di un terminale interattivo, come /theme e /terminal-setup, non appaiono nell’elenco. Accedi al campo quando la tua sessione inizia:
L’elenco stampato mescola comandi incorporati, skills nel bundle, le tue skills invocabili dall’utente e file .claude/commands/:
Una skill con user-invocable: false nel suo frontmatter non appare in questo elenco o nell’array skills da Conferma che le skills sono caricate. Le sessioni che configurano server MCP possono anche esporre prompt MCP come comandi.

Invia comandi per nome

Invia un comando includendolo nella tua stringa di prompt, allo stesso modo in cui invii testo regolare. L’invio non dipende dall’opzione skills. Inviare /<name> esegue una skill invocabile dall’utente anche quando il tuo elenco skills l’omette. I comandi che agiscono sulla cronologia della conversazione, come /compact, necessitano di messaggi precedenti con cui lavorare. Un /<name> che non corrisponde né a un comando nella sessione né a un comando Claude Code incorporato non fa fallire la query. Claude Code invia il prompt a Claude come un messaggio ordinario, con una nota che il comando non è stato eseguito, quindi la query spende un turno del modello e restituisce la risposta di Claude. Prima della v2.1.274, un /<name> che non corrispondeva a nulla restituiva Unknown command: /<name> come risultato senza un turno del modello. Un /<name> che corrisponde a un comando Claude Code incorporato che non è disponibile nella sessione, come /theme, restituisce /theme isn't available in this environment. come risultato senza un turno del modello.
Un comando può raggiungere il limite maxTurns / max_turns come qualsiasi altro prompt, terminando la query con un risultato di errore invece di success. Per il contratto del risultato di errore, vedi Gestisci il risultato. Se il tuo comando potrebbe raggiungere il limite, avvolgi il loop in un try/catch in TypeScript o try/except in Python, come mostrato in Input di un singolo messaggio, oppure imposta maxTurns abbastanza alto affinché il lavoro si completi.

Compatta la cronologia con /compact

Il comando /compact riduce la dimensione della tua cronologia di conversazione riassumendo i messaggi più vecchi preservando il contesto importante. La compattazione necessita di una conversazione esistente con abbastanza messaggi precedenti da riassumere. Questo esempio ha prima una conversazione, poi la compatta e legge il messaggio di sistema compact_boundary che riporta il risultato:
Un messaggio compact_boundary arriva solo quando la compattazione è stata eseguita. Quando una sessione continuata ha messaggi ma nulla che /compact possa riassumere, l’esecuzione termina comunque con un risultato success piuttosto che un errore, e nessun messaggio compact_boundary arriva. Il testo del risultato quindi riporta il motivo, ad esempio Not enough messages to compact. quando la sessione contiene un prompt ma nessuna risposta da Claude ancora. Una nuova chiamata query() one-shot inizia con contesto vuoto, quindi utilizza questo modello in una sessione con turni precedenti, ad esempio in modalità input streaming o quando riprendi una sessione.

Reimposta il contesto con /clear

Il comando /clear reimposta la conversazione a un contesto vuoto, quindi i prompt successivi iniziano senza cronologia di conversazione precedente. La conversazione precedente rimane su disco. Puoi tornare a quella conversazione passando il suo ID di sessione all’opzione resume. /clear è utile in modalità input streaming, dove invii più prompt su una singola connessione. Per le chiamate query() one-shot, ogni chiamata inizia già con contesto vuoto, quindi inviare /clear non ha effetto pratico. Avvia una nuova query() invece.

Crea skills

Crea ogni skill come una directory contenente un file SKILL.md con frontmatter YAML e contenuto Markdown. Il campo description determina quando Claude richiama la tua skill. Struttura di directory di esempio:

Scegli un livello di scoperta

Salva le skills a uno dei due livelli di scoperta più comuni:
  • Skills del progetto: .claude/skills/, disponibili solo nel progetto corrente
  • Skills personali: ~/.claude/skills/, disponibili in tutti i tuoi progetti
Se hai file di comando personalizzati esistenti in .claude/commands/, continuano a funzionare. Un file di comando in .claude/commands/deploy.md crea /deploy e funziona allo stesso modo di una skill in .claude/skills/deploy/SKILL.md. Se un file di comando e una skill condividono un nome, vedi Risolvi skills che condividono un nome per quale viene eseguita. L’SDK carica i file .claude/commands/ e ~/.claude/commands/ dagli stessi due ambiti delle skills. Vedi Estendi Claude con skills per la guida completa a entrambe le forme di artefatto.

Crea e invia la tua prima skill

Per vedere il flusso completo, crea .claude/skills/security-check/SKILL.md:
Una volta che il file esiste, la skill è disponibile attraverso l’SDK. Claude la richiama quando una richiesta corrisponde alla sua descrizione, e puoi inviarla direttamente:
Un’esecuzione riuscita termina con un risultato success il cui testo riporta i risultati della scansione. Contro una piccola app Express con problemi seminati, il testo del risultato inizia:
Il nome della skill appare anche nell’array slash_commands del messaggio init.
Claude Code include skills nel bundle code-review e verify. Se denomini un file .claude/commands/ dopo uno di essi, ad esempio .claude/commands/code-review.md, il file del comando oscura la skill nel bundle e slash_commands elenca il nome una volta.

Pre-approva gli strumenti per le skills

Nelle sessioni dell’SDK, puoi pre-approvare gli strumenti per una skill del progetto o personale con il frontmatter allowed-tools della skill oppure con l’opzione allowedTools (allowed_tools in Python) nella tua configurazione di query. Se la tua organizzazione imposta allowManagedPermissionRulesOnly nelle impostazioni gestite, Claude Code li ignora entrambi. Le skill sincronizzate da claude.ai seguono le proprie regole di frontmatter.
Le skills vengono eseguite con gli strumenti della sessione. L’esempio seguente pre-approva Read, Grep e Glob con allowedTools (allowed_tools in Python), quindi Claude può ispezionare i file mentre esegue la skill security-check senza fermarsi per l’approvazione:
Nello stream, l’invocazione della skill appare come un uso dello strumento Skill, seguito da chiamate Read sui file del progetto. L’esecuzione termina con un risultato success il cui testo riporta i risultati. L’elenco pre-approva gli strumenti denominati piuttosto che limitare gli altri. Per il flusso di autorizzazione completo, incluse le modalità di autorizzazione e il callback canUseTool, vedi Autorizzazioni.

Risoluzione dei problemi

Skills non trovate

Controlla la configurazione di settingSources: l’SDK scopre le skills attraverso le fonti di impostazione user e project. Se imposti settingSources/setting_sources esplicitamente e ometti quelle fonti, l’SDK non carica le skills:
Per quale directory di skills ogni fonte carica, vedi la tabella delle fonti del filesystem. Per ulteriori dettagli su settingSources/setting_sources, vedi il riferimento SDK TypeScript o il riferimento SDK Python. Controlla la directory di lavoro: l’SDK carica le skills da .claude/skills/ nell’opzione cwd e in ogni directory padre fino alla radice del repository. Assicurati che cwd punti a o al di sotto della directory contenente .claude/skills/, all’interno dello stesso repository:
Vedi Utilizza le skills con l’Agent SDK per il modello completo. Verifica la posizione del filesystem:

Skill non utilizzata

Controlla l’opzione skills: se hai passato un elenco di skills, conferma che il nome della skill sia incluso. Quando Claude tenta di invocare una skill non elencata, lo strumento Skill restituisce Skill <name> is not in this session's skills allowlist. Aggiungi il nome al tuo elenco, oppure invia la skill direttamente inviando /<name> in un prompt, che funziona senza elencare. Controlla la descrizione: assicurati che sia specifica e includa parole chiave rilevanti. Vedi Best practices di Agent Skills per una guida sulla scrittura di descrizioni efficaci.

Errore di nome skill non valido

Quando un nome nel tuo elenco skills non può funzionare come nome di skill esatto, query() rifiuta l’elenco prima di avviare il processo Claude Code. I nomi che attivano il rifiuto includono:
  • Un nome vuoto
  • Un nome contenente parentesi, virgole o caratteri di controllo
  • Un nome riempito con spazi bianchi
  • Una forma wildcard come un * nudo o un suffisso :*
Ogni SDK presenta il rifiuto diversamente:
L’SDK TypeScript genera un Error che indica la regola che la voce ha violato. Ad esempio, skills: ["docs:*"] genera:
Un nome vuoto riporta Skill names must be non-empty strings.Prima dell’Agent SDK TypeScript 0.3.221, l’SDK non eseguiva questo controllo.

Risoluzione dei problemi aggiuntiva

Per la risoluzione generale dei problemi delle skills, come errori di sintassi YAML e debug, vedi la sezione di risoluzione dei problemi delle skills di Claude Code.

Passaggi successivi

La guida alle skills di Claude Code copre l’authoring in profondità. La sua guida si applica alle sessioni dell’SDK. Inizia con queste sezioni: