Skip to main content
Agent Skills estendem Claude com capacidades especializadas que Claude invoca quando relevante. Skills são empacotadas como arquivos SKILL.md contendo instruções, descrições e recursos de suporte opcionais. Esta página também cobre comandos em sessões do Agent SDK. 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 Agent SDK

Ao usar o Claude Agent SDK, skills são:
  • Definidas como artefatos do sistema de arquivos: você cria cada skill como um arquivo SKILL.md em seu próprio diretório, como .claude/skills/<name>/SKILL.md
  • Carregadas do sistema de arquivos: o SDK carrega skills dos locais do sistema de arquivos governados por settingSources (TypeScript) ou setting_sources (Python)
  • Descobertas automaticamente: uma vez que as configurações do sistema de arquivos são carregadas, o SDK descobre metadados de skill na inicialização a partir de diretórios de usuário e projeto, e carrega o conteúdo completo quando Claude invoca a skill
  • Invocadas pelo modelo: Claude escolhe autonomamente quando usá-las com base no contexto
  • Invocadas pelo usuário: você despache uma skill diretamente enviando /<name> em um prompt. Consulte Comandos em sessões do Agent SDK
  • Escopo via opção skills: skills descobertas são habilitadas por padrão. Passe uma lista de nomes de skills, "all" ou [] para controlar quais skills Claude pode invocar
Diferentemente de subagentes, que você pode definir na opção agents, você cria skills como arquivos em disco. O SDK não fornece uma API programática para registrá-las.
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. A fonte de projeto também cobre <dir>/.claude/skills/ em cada diretório que você passa através de additionalDirectories (TypeScript) ou add_dirs (Python), porque o SDK passa esses diretórios para Claude Code como --add-dir. Se você definir settingSources explicitamente, inclua 'project' para manter skills de projeto e diretório adicionado e 'user' para manter suas skills pessoais, ou use a opção plugins para carregar skills de um caminho específico.

Use skills com o Agent SDK

Defina a opção skills em query() para controlar quais skills Claude pode invocar na sessão. Quando omitida, skills descobertas são habilitadas e a ferramenta Skill está disponível, correspondendo ao comportamento da CLI. Passe "all" para deixar Claude invocar cada skill descoberta, uma lista de nomes de skills para permitir apenas aquelas, ou [] para deixar Claude invocar nenhuma. Por exemplo, para deixar Claude invocar apenas duas skills nomeadas:

Configure skills em uma sessão

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. O exemplo a seguir habilita cada skill descoberta em uma sessão e pré-aprova as ferramentas que skills comumente precisam. O exemplo define cwd para o diretório de trabalho atual do processo, portanto execute-o dentro de um projeto que tenha um diretório .claude/skills/ no diretório atual ou em qualquer pai até a raiz do repositório:

Confirme skills carregadas

Perto do início do stream, o SDK produz uma mensagem de sistema com subtipo init. Verifique seu array skills para confirmar que suas skills foram carregadas antes de Claude começar a trabalhar. O array inclui as skills invocáveis pelo usuário que você definiu com um campo frontmatter description ou when_to_use, junto com skills agrupadas incluídas com Claude Code. O array lista apenas skills invocáveis pelo usuário. Uma skill com user-invocable: false em seu frontmatter carrega e permanece disponível para Claude, mas não aparece no array. O array lista as mesmas skills independentemente de estarem ou não em sua lista skills.

Permita apenas skills específicas

Para deixar Claude invocar apenas skills específicas, passe seus nomes na lista skills. 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. A lista leva apenas nomes de skills exatos. Se uma entrada não puder funcionar como um nome exato, query() rejeita a lista antes da sessão começar. Consulte Erro de nome de skill inválido para as regras de nome e o erro que cada SDK levanta. O modelo não vê skills não listadas e a ferramenta Skill as rejeita, enquanto seus arquivos permanecem em disco e permanecem acessíveis através de Read e Bash. Restringir a lista não restringe despacho por nome. Para deixar Claude invocar cada skill descoberta, passe skills: "all" em vez de um curinga.

Comandos em sessões do Agent SDK

Esta seção é a documentação de comando do SDK. Um comando é qualquer coisa que você executa enviando /<name> em um prompt. As entradas na superfície de comando diferem no que as respalda:
  • Comandos integrados: executam lógica codificada no processo Claude Code que o SDK executa, por exemplo /compact
  • Skills agrupadas: artefatos de prompt incluídos com Claude Code, por exemplo /code-review
  • Suas skills: artefatos de prompt que você cria, cada um um diretório contendo um arquivo SKILL.md. O nome de uma skill invocável pelo usuário se une à superfície automaticamente, portanto despachar seu próprio /security-check e executar um integrado funcionam da mesma forma
  • Arquivos de comando personalizados: uma forma de artefato mais antiga com o mesmo comportamento, arquivos Markdown simples em .claude/commands/ cujos nomes de arquivo se tornam nomes de comando. Skills são seu sucessor recomendado
Por padrão, tanto você quanto Claude podem invocar qualquer skill. Você pode restringir qualquer caminho através do frontmatter da skill. Para uma definição dos dois termos, consulte as entradas Comando e Skill do glossário. Consulte Comandos em Claude Code para cada integrado e Estenda Claude com skills para o guia completo de ambas as formas de artefato.

Descubra comandos disponíveis

Você pode despachar comandos que funcionam sem um terminal interativo através do SDK. A mensagem system/init lista os disponíveis em sua sessão em seu campo slash_commands. Comandos que precisam de um terminal interativo, como /theme e /terminal-setup, não aparecem na lista. Acesse o campo quando sua sessão começar:
A lista impressa mistura comandos integrados, skills agrupadas, suas skills invocáveis pelo usuário e arquivos .claude/commands/:
Uma skill com user-invocable: false em seu frontmatter não aparece nesta lista ou no array skills de Confirme skills carregadas. Sessões que configuram servidores MCP também podem expor prompts MCP como comandos.

Despache comandos por nome

Envie um comando incluindo-o em sua string de prompt, da mesma forma que você envia texto regular. O despacho não depende da opção skills. Enviar /<name> executa uma skill invocável pelo usuário mesmo quando sua lista skills a omite. Comandos que atuam no histórico de conversa, como /compact, precisam de mensagens anteriores para trabalhar.
Um comando pode atingir o limite maxTurns / max_turns como qualquer outro prompt, terminando a query com um resultado de erro em vez de success. Para o contrato de resultado de erro, consulte Manipule o resultado. Se seu comando pode atingir o limite, envolva o loop em um try/catch em TypeScript ou try/except em Python, como mostrado em Entrada de Mensagem Única, ou defina maxTurns alto o suficiente para o trabalho ser concluído.

Compacte histórico com /compact

O comando /compact reduz o tamanho do seu histórico de conversa resumindo mensagens mais antigas enquanto preserva contexto importante. A compactação precisa de uma conversa existente com mensagens anteriores suficientes para resumir. Este exemplo tem uma conversa primeiro, depois a compacta e lê a mensagem de sistema compact_boundary que relata o resultado:
Uma mensagem compact_boundary só chega quando a compactação foi executada. Sem nada para resumir, /compact relata o motivo em vez de levantar. A execução ainda termina com um resultado success e nenhuma mensagem compact_boundary, e o texto do resultado carrega o motivo, por exemplo Not enough messages to compact. após uma única troca curta. Uma chamada query() nova e única começa com contexto vazio, portanto use este padrão em uma sessão com turnos anteriores, por exemplo em modo de entrada de streaming ou ao retomar uma sessão.

Redefina contexto com /clear

O comando /clear redefine a conversa para um contexto vazio, portanto prompts subsequentes começam sem histórico de conversa anterior. A conversa anterior permanece em disco. Você pode retornar a essa conversa passando seu ID de sessão para a opção resume. /clear é útil em modo de entrada de streaming, onde você envia múltiplos prompts sobre uma única conexão. Para chamadas query() únicas, cada chamada já começa com contexto vazio, portanto enviar /clear não tem efeito prático. Comece uma nova query() em vez disso.

Crie skills

Crie cada skill como um diretório 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:

Escolha um nível de descoberta

Salve skills em um dos dois níveis de descoberta mais comuns:
  • Skills de projeto: .claude/skills/, disponíveis apenas no projeto atual
  • Skills pessoais: ~/.claude/skills/, disponíveis em todos os seus projetos
Se você tem arquivos de comando personalizados existentes em .claude/commands/, eles continuam funcionando. Um arquivo de comando em .claude/commands/deploy.md cria /deploy e funciona da mesma forma que uma skill em .claude/skills/deploy/SKILL.md faria. Se um arquivo de comando e uma skill compartilham um nome, consulte Resolva skills que compartilham um nome para qual executa. O SDK carrega arquivos .claude/commands/ e ~/.claude/commands/ dos mesmos dois escopos que skills. Consulte Estenda Claude com skills para o guia completo de ambas as formas de artefato.

Crie e despache sua primeira skill

Para ver o fluxo completo, crie .claude/skills/security-check/SKILL.md:
Uma vez que o arquivo existe, a skill está disponível através do SDK. Claude a invoca quando uma solicitação corresponde à sua descrição, e você pode despachá-la diretamente:
Uma execução bem-sucedida termina com um resultado success cujo texto carrega as descobertas da varredura. Contra um pequeno aplicativo Express com problemas semeados, o texto do resultado começa:
O nome da skill também aparece no array slash_commands da mensagem init.
Claude Code inclui skills agrupadas code-review e verify. Se você nomear um arquivo .claude/commands/ após uma delas, por exemplo .claude/commands/code-review.md, o arquivo de comando sombreia a skill agrupada e slash_commands lista o nome uma vez.

Pré-aprove ferramentas para skills

Para skills de projeto e pessoais, Claude Code aplica o campo frontmatter allowed-tools em sessões do SDK. Você também pode pré-aprovar ferramentas para essas skills através da opção allowedTools (allowed_tools em Python) em sua configuração de query. Skills sincronizadas de claude.ai seguem suas próprias regras de frontmatter.
Skills executam com as ferramentas da sessão. O exemplo abaixo pré-aprova Read, Grep e Glob com allowedTools (allowed_tools em Python), portanto Claude pode inspecionar arquivos enquanto executa a skill security-check sem parar para aprovação:
No stream, a invocação de skill aparece como um uso de ferramenta Skill, seguido por chamadas Read nos arquivos do projeto. A execução termina com um resultado success cujo texto carrega as descobertas. A lista pré-aprova as ferramentas nomeadas em vez de restringir as outras. Para o fluxo de permissão completo, incluindo modos de permissão e o callback canUseTool, consulte Permissões.

Solução de problemas

Skills não encontradas

Verifique a configuração settingSources: o SDK descobre skills através das fontes de configuração user e project. Se você definir settingSources/setting_sources explicitamente e omitir essas fontes, o SDK não carrega skills:
Para qual diretório de skill cada fonte carrega, consulte a tabela de fontes do sistema de arquivos. 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 cada diretório 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:
Consulte Use skills com o Agent SDK para o padrão completo. Verifique o local do sistema de arquivos:

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. Quando Claude tenta invocar uma skill não listada, a ferramenta Skill retorna Skill <name> is not in this session's skills allowlist. Adicione o nome à sua lista, ou despache a skill diretamente enviando /<name> em um prompt, que funciona sem listar. Verifique a descrição: certifique-se de que é específica e inclui palavras-chave relevantes. Consulte Práticas recomendadas de Agent Skills para orientação sobre como escrever descrições eficazes.

Erro de nome de skill inválido

Quando um nome em sua lista skills não pode funcionar como um nome de skill exato, query() rejeita a lista antes de iniciar o processo Claude Code. Os nomes que acionam a rejeição incluem:
  • Um nome vazio
  • Um nome contendo parênteses, vírgulas ou caracteres de controle
  • Um nome preenchido com espaço em branco
  • Uma forma curinga como um * simples ou um sufixo :*
Cada SDK superficializa a rejeição de forma diferente:
O SDK TypeScript lança um Error declarando a regra que a entrada quebrou. Por exemplo, skills: ["docs:*"] lança:
Um nome vazio relata Skill names must be non-empty strings.Antes do TypeScript Agent SDK 0.3.221, o SDK não executava esta verificação.

Solução de problemas adicional

Para solução de problemas geral de skills, como erros de sintaxe YAML e depuração, consulte a seção de solução de problemas de skills do Claude Code.

Próximos passos

O guia de skills do Claude Code cobre autoria em profundidade. Sua orientação se aplica a sessões do SDK. Comece com estas seções: