Agent Skills nell'SDK
Estendi Claude con capacità specializzate utilizzando Agent Skills nell'SDK dell'Agent Claude
Panoramica
Agent Skills estendono Claude con capacità specializzate che Claude richiama autonomamente quando rilevante. Le Skills sono confezionate come file SKILL.md contenenti istruzioni, descrizioni e risorse di supporto opzionali.
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'SDK
Quando si utilizza l'SDK dell'Agent Claude, le Skills sono:
- Definite come artefatti del filesystem: Create come file
SKILL.mdin directory specifiche (.claude/skills/) - Caricate dal filesystem: Le Skills sono caricate da posizioni del filesystem governate da
settingSources(TypeScript) osetting_sources(Python) - Scoperte automaticamente: Una volta caricate le impostazioni del filesystem, i metadati della Skill vengono scoperti all'avvio dalle directory dell'utente e del progetto; il contenuto completo viene caricato quando attivato
- Richiamate dal modello: Claude sceglie autonomamente quando utilizzarle in base al contesto
- Filtrate tramite l'opzione
skills: Le Skills scoperte sono abilitate per impostazione predefinita. Passa un elenco di nomi di Skills,"all", o[]per controllare quali sono disponibili nella sessione
A differenza dei subagents (che possono essere definiti programmaticamente), le Skills devono essere create come artefatti del filesystem. L'SDK non fornisce un'API programmatica per registrare le Skills.
Utilizzo delle Skills con l'SDK
Imposta l'opzione skills su query() per controllare quali Skills sono disponibili per la sessione. Se omessa, le Skills scoperte sono abilitate e lo strumento Skill è disponibile, corrispondendo al comportamento della CLI. Passa "all" per abilitare ogni Skill scoperta, un elenco di nomi di Skills per abilitare solo quelle, o [] per disabilitare tutte. Quando imposti skills, l'SDK abilita automaticamente lo strumento Skill, quindi non è necessario elencarlo in allowedTools.
Una volta configurato, Claude scopre automaticamente le Skills dal filesystem e le richiama quando rilevante per la richiesta dell'utente.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project", # Project with .claude/skills/
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all", # Enable 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())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
Per abilitare solo Skills specifiche, passa i loro nomi. 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.
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
L'opzione skills è un filtro di contesto, non una sandbox. Le Skills non elencate sono nascoste dal modello e rifiutate dallo strumento Skill, ma i loro file rimangono sul disco e sono raggiungibili tramite Read e Bash.
Posizioni delle Skills
Le Skills vengono caricate dalle directory del filesystem in base alla configurazione di settingSources/setting_sources:
- Project Skills (
.claude/skills/): Condivise con il tuo team tramite git - caricate quandosetting_sourcesinclude"project" - User Skills (
~/.claude/skills/): Skills personali su tutti i progetti - caricate quandosetting_sourcesinclude"user" - Plugin Skills: Fornite con i plugin Claude Code installati
Creazione di Skills
Le Skills sono definite come directory contenenti 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/processing-pdfs/
└── SKILL.md
Per una guida completa sulla creazione di Skills, inclusa la struttura di SKILL.md, Skills multi-file ed esempi, consulta:
- Agent Skills in Claude Code: Guida completa con esempi
- Agent Skills Best Practices: Linee guida di authoring e convenzioni di denominazione
Restrizioni degli strumenti
Per controllare l'accesso agli strumenti per le Skills nelle applicazioni SDK, utilizza allowedTools per pre-approvare strumenti specifici. Senza un callback canUseTool, tutto ciò che non è nell'elenco viene negato:
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)
async for message in query(prompt="Analyze the codebase structure", options=options):
print(message)
for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(message);
}
Scoperta delle Skills disponibili
Per vedere quali Skills sono disponibili nella tua applicazione SDK, chiedi semplicemente a Claude:
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
)
async for message in query(prompt="What Skills are available?", options=options):
print(message)
for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(message);
}
Claude elencherà le Skills disponibili in base alla tua directory di lavoro corrente e ai plugin installati.
Test delle Skills
Testa le Skills ponendo domande che corrispondono alle loro descrizioni:
options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Bash"],
)
async for message in query(prompt="Extract text from invoice.pdf", options=options):
print(message)
for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(message);
}
Claude richiama automaticamente la Skill rilevante se la descrizione corrisponde alla tua richiesta.
Risoluzione dei problemi
Skills non trovate
Controlla la configurazione di settingSources: Le Skills vengono scoperte attraverso le fonti di impostazione user e project. Se imposti settingSources/setting_sources esplicitamente e ometti quelle fonti, le Skills non vengono caricate:
# 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",
)
// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const options = {
settingSources: ["user", "project"],
skills: "all"
};
Per ulteriori dettagli su settingSources/setting_sources, consulta 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",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
Consulta la sezione "Utilizzo delle Skills con l'SDK" sopra 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. Passare [] disabilita tutte le Skills.
Controlla la descrizione: Assicurati che sia specifica e includa parole chiave rilevanti. Consulta Agent Skills Best Practices per una guida sulla scrittura di descrizioni efficaci.
Risoluzione dei problemi aggiuntiva
Per la risoluzione generale dei problemi delle Skills (sintassi YAML, debug, ecc.), consulta la sezione di risoluzione dei problemi delle Skills di Claude Code.
Documentazione correlata
Guide sulle Skills
- Agent Skills in Claude Code: Guida completa delle Skills con creazione, esempi e risoluzione dei problemi
- Agent Skills Overview: Panoramica concettuale, vantaggi e architettura
- Agent Skills Best Practices: Linee guida di authoring per Skills efficaci
- Agent Skills Cookbook: Skills di esempio e modelli
Risorse SDK
- Subagents in the SDK: Agenti basati su filesystem simili con opzioni programmatiche
- Slash Commands in the SDK: Comandi richiamati dall'utente
- SDK Overview: Concetti generali dell'SDK
- TypeScript SDK Reference: Documentazione API completa
- Python SDK Reference: Documentazione API completa