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.mdem 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) ousetting_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
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çãoskills 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ê defineskills, 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 subtipoinit. 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 listaskills. 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-checke 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
Descubra comandos disponíveis
Você pode despachar comandos que funcionam sem um terminal interativo através do SDK. A mensagemsystem/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:
.claude/commands/:
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çãoskills. 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 arquivoSKILL.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
.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:
success cujo texto carrega as descobertas da varredura. Contra um pequeno aplicativo Express com problemas semeados, o texto do resultado começa:
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.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:
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çãouser e project. Se você definir settingSources/setting_sources explicitamente e omitir essas fontes, o SDK não carrega skills:
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:
Skill não sendo usada
Verifique a opçãoskills: 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 listaskills 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:*
- TypeScript
- Python
O SDK TypeScript lança um Um nome vazio relata
Error declarando a regra que a entrada quebrou. Por exemplo, skills: ["docs:*"] lança: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:- Referência de frontmatter: cada campo suportado
- Passe argumentos para skills:
$ARGUMENTS,$0,$1e empilhamento de skills. A tabela de substituição completa adiciona argumentos nomeados e as variáveis${CLAUDE_*} - Injete contexto dinâmico: linhas
!`command`que executam antes de Claude ver o conteúdo da skill - Escolha onde skills carregam: cada local de skill, namespacing de plugin e qual skill executa quando dois compartilham um nome
Recursos relacionados
- Comandos em Claude Code: a superfície de comando completa, incluindo cada integrado
- Visão geral de Agent Skills: visão geral conceitual, benefícios e arquitetura
- Práticas recomendadas de Agent Skills: diretrizes de autoria para skills eficazes
- Livro de receitas de Agent Skills: skills de exemplo e templates
- Subagentes no SDK: agentes similares baseados em sistema de arquivos com opções programáticas
- 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