Agent Skills no SDK
Estenda Claude com capacidades especializadas usando Agent Skills no Claude Agent SDK
Visão Geral
Agent Skills estendem Claude com capacidades especializadas que Claude invoca autonomamente quando relevante. Skills são empacotadas como arquivos SKILL.md contendo instruções, descrições e recursos de suporte opcionais.
Para informações abrangentes sobre Skills, incluindo benefícios, arquitetura e diretrizes de autoria, consulte a visão geral de Agent Skills.
Como Skills Funcionam com o SDK
Ao usar o Claude Agent SDK, Skills são:
- Definidas como artefatos do sistema de arquivos: Criadas como arquivos
SKILL.mdem diretórios específicos (.claude/skills/) - Carregadas do sistema de arquivos: Skills são carregadas de locais do sistema de arquivos governados por
settingSources(TypeScript) ousetting_sources(Python) - Descobertas automaticamente: Uma vez que as configurações do sistema de arquivos são carregadas, os metadados de Skill são descobertos na inicialização a partir de diretórios de usuário e projeto; conteúdo completo carregado quando acionado
- Invocadas pelo modelo: Claude escolhe autonomamente quando usá-las com base no contexto
- Filtradas via opção
skills: Skills descobertas são habilitadas por padrão. Passe uma lista de nomes de skills,"all", ou[]para controlar quais estão disponíveis na sessão
Diferentemente de subagentes (que podem ser definidos programaticamente), Skills devem ser criadas como artefatos do sistema de arquivos. O SDK não fornece uma API programática para registrar Skills.
Usando Skills com o SDK
Defina a opção skills em query() para controlar quais Skills estão disponíveis para a sessão. Quando omitida, Skills descobertas são habilitadas e a ferramenta Skill está disponível, correspondendo ao comportamento da CLI. Passe "all" para habilitar cada Skill descoberta, uma lista de nomes de Skill para habilitar apenas aquelas, ou [] para desabilitar todas. Quando você define skills, o SDK habilita a ferramenta Skill automaticamente, portanto você não precisa listá-la em allowedTools.
Uma vez configurado, Claude descobre automaticamente Skills do sistema de arquivos e as invoca quando relevante para a solicitação do usuário.
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);
}
Para habilitar apenas Skills específicas, passe seus nomes. Os nomes correspondem ao campo name em SKILL.md ou ao nome do diretório da Skill. Use plugin:skill para Skills fornecidas por plugin.
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
A opção skills é um filtro de contexto, não uma sandbox. Skills não listadas são ocultadas do modelo e rejeitadas pela ferramenta Skill, mas seus arquivos permanecem no disco e são acessíveis através de Read e Bash.
Locais de Skill
Skills são carregadas de diretórios do sistema de arquivos com base na sua configuração settingSources/setting_sources:
- Project Skills (
.claude/skills/): Compartilhadas com sua equipe via git - carregadas quandosetting_sourcesinclui"project" - User Skills (
~/.claude/skills/): Skills pessoais em todos os projetos - carregadas quandosetting_sourcesinclui"user" - Plugin Skills: Agrupadas com plugins Claude Code instalados
Criando Skills
Skills são definidas como diretórios contendo um arquivo SKILL.md com frontmatter YAML e conteúdo Markdown. O campo description determina quando Claude invoca sua Skill.
Exemplo de estrutura de diretório:
.claude/skills/processing-pdfs/
└── SKILL.md
Para orientação completa sobre criação de Skills, incluindo estrutura SKILL.md, Skills multi-arquivo e exemplos, consulte:
- Agent Skills no Claude Code: Guia completo com exemplos
- Agent Skills Best Practices: Diretrizes de autoria e convenções de nomenclatura
Restrições de Ferramenta
Para controlar o acesso à ferramenta para Skills em aplicações SDK, use allowedTools para pré-aprovar ferramentas específicas. Sem um callback canUseTool, qualquer coisa não na lista é negada:
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);
}
Descobrindo Skills Disponíveis
Para ver quais Skills estão disponíveis em sua aplicação SDK, simplesmente pergunte 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 listará as Skills disponíveis com base no seu diretório de trabalho atual e plugins instalados.
Testando Skills
Teste Skills fazendo perguntas que correspondam às suas descrições:
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 invoca automaticamente a Skill relevante se a descrição corresponder à sua solicitação.
Solução de Problemas
Skills Não Encontradas
Verifique a configuração settingSources: Skills são descobertas através das fontes de configuração user e project. Se você definir settingSources/setting_sources explicitamente e omitir essas fontes, skills não são carregadas:
# 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"
};
Para mais detalhes sobre settingSources/setting_sources, consulte a referência TypeScript SDK ou referência Python SDK.
Verifique o diretório de trabalho: O SDK carrega Skills relativo à opção cwd. Certifique-se de que aponta para um diretório contendo .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"], # Loads skills from these sources
skills="all",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // Must contain .claude/skills/
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
Consulte a seção "Usando Skills com o SDK" acima para o padrão completo.
Verifique o local do sistema de arquivos:
# Check project Skills
ls .claude/skills/*/SKILL.md
# Check personal Skills
ls ~/.claude/skills/*/SKILL.md
Skill Não Sendo Usada
Verifique a opção skills: Se você passou uma lista skills, confirme que o nome da skill está incluído. Passar [] desabilita todas as skills.
Verifique a descrição: Certifique-se de que é específica e inclui palavras-chave relevantes. Consulte Agent Skills Best Practices para orientação sobre como escrever descrições eficazes.
Solução de Problemas Adicional
Para solução de problemas geral de Skills (sintaxe YAML, depuração, etc.), consulte a seção de solução de problemas de Skills do Claude Code.
Documentação Relacionada
Guias de Skills
- Agent Skills no Claude Code: Guia completo de Skills com criação, exemplos e solução de problemas
- Agent Skills Overview: Visão geral conceitual, benefícios e arquitetura
- Agent Skills Best Practices: Diretrizes de autoria para Skills eficazes
- Agent Skills Cookbook: Skills de exemplo e templates
Recursos SDK
- Subagents no SDK: Agentes similares baseados em sistema de arquivos com opções programáticas
- Slash Commands no SDK: Comandos invocados pelo usuário
- Visão Geral do SDK: Conceitos gerais do SDK
- Referência TypeScript SDK: Documentação completa da API
- Referência Python SDK: Documentação completa da API