​
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.
Comportamento predefinito: Per impostazione predefinita, l’SDK non carica alcuna impostazione del filesystem. Per utilizzare le Skills, devi configurare esplicitamente settingSources: ['user', 'project'] (TypeScript) o setting_sources=["user", "project"] (Python) nelle tue opzioni.

​
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:

​
Restrizioni degli strumenti

Il campo frontmatter allowed-tools in SKILL.md è supportato solo quando si utilizza direttamente Claude Code CLI. Non si applica quando si utilizzano le Skills tramite l’SDK.Quando si utilizza l’SDK, controlla l’accesso agli strumenti tramite l’opzione principale allowedTools nella configurazione della tua query.
Per limitare gli strumenti per le Skills nelle applicazioni SDK, utilizza l’opzione allowedTools:
Le istruzioni di importazione dal primo esempio sono assunte nei seguenti frammenti di codice.
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

​
Risorse SDK