Agent Skills no 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:

1. Definidas como artefatos do sistema de arquivos: Criadas como arquivos SKILL.md em diretórios específicos (.claude/skills/)
2. Carregadas do sistema de arquivos: Skills são carregadas de locais do sistema de arquivos configurados. Você deve especificar settingSources (TypeScript) ou setting_sources (Python) para carregar Skills do sistema de arquivos
3. 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
4. Invocadas pelo modelo: Claude escolhe autonomamente quando usá-las com base no contexto
5. Habilitadas via allowed_tools: Adicione "Skill" ao seu allowed_tools para habilitar Skills

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

Para usar Skills com o SDK, você precisa:

1. Incluir "Skill" em sua configuração allowed_tools
2. Configurar settingSources/setting_sources para carregar Skills do sistema de arquivos

Uma vez configurado, Claude descobre automaticamente Skills dos diretórios especificados e os 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
        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())

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
    allowedTools: ["Skill", "Read", "Write", "Bash"]  // Enable Skill tool
  }
})) {
  console.log(message);
}

Locais de Skill

Skills são carregadas de diretórios do sistema de arquivos com base em sua configuração settingSources/setting_sources:

• Project Skills (.claude/skills/): Compartilhadas com sua equipe via git - carregadas quando setting_sources inclui "project"
• User Skills (~/.claude/skills/): Skills pessoais em todos os projetos - carregadas quando setting_sources inclui "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 como criar Skills, incluindo estrutura SKILL.md, Skills com múltiplos arquivos 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 restringir ferramentas para Skills em aplicações SDK, use a opção 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)

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
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(message)

Claude listará as Skills disponíveis com base em 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
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(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 carregadas apenas quando você configura explicitamente settingSources/setting_sources. Este é o problema mais comum:

# 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"]
)

Para mais detalhes sobre settingSources/setting_sources, consulte a referência SDK TypeScript ou referência SDK Python.

Verifique o diretório de trabalho: O SDK carrega Skills em relação à 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"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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 Está Sendo Usada

Verifique se a ferramenta Skill está habilitada: Confirme que "Skill" está em seu allowedTools.

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
• Visão Geral de Agent Skills: 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 modelos

Recursos do SDK

• Subagentes no SDK: Agentes baseados em sistema de arquivos semelhantes 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 SDK TypeScript: Documentação completa da API
• Referência SDK Python: Documentação completa da API