SpyBara
Go Premium

agent-sdk/skills.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 368 additions and 141 deletions.

2026
Wed 9 22:58 Mon 14 22:58 Fri 18 23:58

Estendi gli agenti con skills

Controlla quali skills Claude può invocare nelle sessioni dell'Agent SDK, invia comandi per nome e crea skills che le tue sessioni scoprono

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 su skills, 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.

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:

options = ClaudeAgentOptions(skills=["pdf", "docx"])

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:

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(),  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",  # Let Claude invoke every discovered skill
allowed_tools=["Read", "Write", "Bash"],
)

async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)


asyncio.run(main())

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, 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 riflette ciò che la sessione ha scoperto ed 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:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available commands:", message.slash_commands);
}
}

L'elenco stampato mescola comandi incorporati, skills nel bundle, le tue skills invocabili dall'utente e file .claude/commands/:

Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

Le tue skills invocabili dall'utente appaiono sia in questo elenco che nell'array skills da Conferma che le skills sono caricate. L'elenco slash_commands aggiunge il resto dei comandi disponibili nella tua sessione. Una skill con user-invocable: false nel suo frontmatter non appare in nessuno dei due. 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.

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:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}

// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}

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:

.claude/skills/security-check/
└── SKILL.md

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:

---
name: security-check
description: Run a security vulnerability scan
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations

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:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

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:

**Security scan of `app.js` — 4 findings (most severe first):**

1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...

Il nome della skill appare anche nell'array slash_commands del messaggio init.

Pre-approva gli strumenti per le skills

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:

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)


async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)


asyncio.run(main())

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:

# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)

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:

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Loads skills from these sources
skills="all",
)

Vedi Utilizza le skills con l'Agent SDK per il modello completo.

Verifica la posizione del filesystem:

# Check project skills
ls .claude/skills/*/SKILL.md

# Check personal skills
ls ~/.claude/skills/*/SKILL.md

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:

Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

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: