Agent Skills nell'SDK

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 di Claude Agent, le Skills sono:

1. Definite come artefatti del filesystem: Create come file SKILL.md in directory specifiche (.claude/skills/)
2. Caricate dal filesystem: Le Skills vengono caricate da posizioni del filesystem configurate. Devi specificare settingSources (TypeScript) o setting_sources (Python) per caricare le Skills dal filesystem
3. Scoperte automaticamente: Una volta caricate le impostazioni del filesystem, i metadati delle Skill vengono scoperti all'avvio dalle directory utente e progetto; il contenuto completo viene caricato quando attivato
4. Richiamate dal modello: Claude sceglie autonomamente quando utilizzarle in base al contesto
5. Abilitate tramite allowed_tools: Aggiungi "Skill" al tuo allowed_tools per abilitare le Skills

A differenza dei subagenti (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

Per utilizzare le Skills con l'SDK, devi:

1. Includere "Skill" nella tua configurazione allowed_tools
2. Configurare settingSources/setting_sources per caricare le Skills dal filesystem

Una volta configurato, Claude scopre automaticamente le Skills dalle directory specificate 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
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

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

asyncio.run(main())

Posizioni delle Skills

Le Skills vengono caricate dalle directory del filesystem in base alla tua configurazione settingSources/setting_sources:

• Project Skills (.claude/skills/): Condivise con il tuo team tramite git - caricate quando setting_sources include "project"
• User Skills (~/.claude/skills/): Skills personali su tutti i progetti - caricate quando setting_sources include "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 limitare gli strumenti per le Skills nelle applicazioni SDK, utilizza l'opzione allowedTools:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(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
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(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
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(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 caricate solo quando configuri esplicitamente settingSources/setting_sources. Questo è il problema più comune:

# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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 relative all'opzione cwd. Assicurati che punti a una directory contenente .claude/skills/:

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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 che lo strumento Skill sia abilitato: Conferma che "Skill" sia nel tuo allowedTools.

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 sulle 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 template

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