Pular para o conteúdo principal

​
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 governados por settingSources (TypeScript) ou setting_sources (Python)
  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. 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.
Skills são descobertas através das fontes de configuração do sistema de arquivos. Com opções padrão de query(), o SDK carrega fontes de usuário e projeto, portanto skills em ~/.claude/skills/, <cwd>/.claude/skills/ e .claude/skills/ em qualquer diretório pai de <cwd> até a raiz do repositório estão disponíveis. Se você definir settingSources explicitamente, inclua 'user' ou 'project' para manter a descoberta de skills, ou use a opção plugins para carregar skills de um caminho específico.

​
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 adiciona a ferramenta Skill a allowedTools automaticamente. Se você também passar uma lista explícita de tools, inclua "Skill" nessa lista para que Claude possa invocar skills. 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())
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"])
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 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 criação de Skills, incluindo estrutura SKILL.md, Skills multi-arquivo e exemplos, consulte:

​
Restrições de Ferramenta

O campo frontmatter allowed-tools em SKILL.md é suportado apenas ao usar Claude Code CLI diretamente. Ele não se aplica ao usar Skills através do SDK.Ao usar o SDK, controle o acesso à ferramenta através da opção principal allowedTools na sua configuração de query.
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:
As instruções de importação do primeiro exemplo são assumidas nos seguintes trechos de código.
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)

​
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)
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)
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",
)
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 de .claude/skills/ na opção cwd e em todos os diretórios pai até a raiz do repositório. Certifique-se de que cwd aponta para ou abaixo do diretório contendo .claude/skills/, dentro do mesmo repositório: 
# 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",
)
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

​
Recursos SDK