Skills do Claude não carregam em subagentes? Veja o que verificar
Diagnostique skills em subagentes do Claude Code: pré-carregamento, chamadas dinâmicas, diretórios e permissões, com um projeto de diagnóstico para baixar.
Se uma skill do Claude funciona na conversa principal, mas não em um subagente personalizado, verifique descoberta, pré-carregamento, chamada e execução separadamente. Adicionar Skill à lista de ferramentas não pré-carrega as instruções. Adicionar um nome a skills: também não libera todas as ferramentas de que essas instruções precisam.
A documentação atual do Claude Code permite tanto o pré-carregamento na inicialização quanto a chamada dinâmica de skills dentro de subagentes. Por isso, orientações antigas de que subagentes nunca podem chamar skills devem ser interpretadas no contexto da versão, e não como uma regra universal atual. O campo skills carrega instruções na inicialização; a ferramenta Skill oferece outro caminho durante a execução.
Este guia trata de agentes personalizados locais e skills de projeto no Claude Code. As informações foram conferidas na documentação oficial em 18 de novembro de 2026. Os exemplos para download são arquivos de diagnóstico criados pela redação: validamos localmente os arquivos e o verificador de resultados, mas não executamos inferência de modelo nem medimos uma taxa de sucesso. As respostas esperadas abaixo são critérios de verificação, não saídas capturadas do Claude. Os documentos dos fornecedores e os exemplos de configuração estão em inglês.
Identifique a etapa da falha antes de mudar a configuração
| O que você observa | Primeira etapa a investigar | Evidência útil |
|---|---|---|
| A skill também está indisponível na sessão principal | Descoberta ou controle de chamada | Nome efetivamente resolvido, localização do arquivo, frontmatter e política |
| O agente principal consegue usá-la, mas o agente personalizado ignora suas regras | Pré-carregamento ou chamada dinâmica | Definição do agente realmente selecionado; aviso de pré-carregamento ou chamada de Skill |
| A chamada da skill é negada | Acesso às ferramentas e regras de permissão | Ferramenta exata que foi negada e regra correspondente |
| As instruções estão presentes, mas uma operação de script ou arquivo falha | Execução | Caminho do arquivo, diretório de trabalho, operação negada e erro do script |
| Funciona em uma pasta, mas não em outra | Escopo ou conflito de nomes | Diretório inicial, raiz do repositório e origem da skill efetivamente usada |
Mantenha uma entrada que reproduza a falha e altere apenas uma variável por execução. Teste cada variante em uma nova sessão principal e com um novo subagente, para que resultados anteriores não sejam repassados à próxima delegação. Não inclua o marcador nem a resposta esperada na tarefa delegada ou nas instruções do projeto carregadas automaticamente. Mover arquivos, liberar ferramentas e reescrever a descrição ao mesmo tempo pode esconder qual mudança resolveu o problema. Para uma visão geral, consulte o guia de Hooks, Subagents e Skills (em inglês); este artigo se concentra em isolar as falhas.
1. Crie uma skill pequena com resultado verificável
Use um diretório local separado para o teste. Você precisa ter o Claude Code instalado e uma conexão já autorizada com um modelo. Antes de executar inferência, registre claude --version e o modelo/provedor utilizado. Uma solicitação ao modelo pode consumir sua cota habitual ou seu saldo de API; baixar este projeto não faz uma solicitação.
Baixe o projeto de diagnóstico ou crie os arquivos abaixo. O arquivo compactado inclui os mesmos arquivos, prompts, um verificador de resultados e instruções. Extraia-o em uma pasta nova, confira o conteúdo e inicie o Claude Code a partir dessa pasta. O projeto não contém hooks, chamadas de rede ou arquivos de credenciais.
skill-diagnostic/
├── .claude/
│ ├── agents/
│ │ ├── audit-preloaded.md
│ │ └── audit-dynamic.md
│ └── skills/
│ └── sample-audit/
│ └── SKILL.md
├── sample.csv
└── check_result.py
Salve o conteúdo a seguir em .claude/skills/sample-audit/SKILL.md. O marcador torna visível a instrução de formato da skill; ele não é um mecanismo de segurança nem prova de como a instrução chegou ao agente.
---
name: sample-audit
description: Audit the synthetic sample.csv fixture and report missing amounts.
---
Read sample.csv in the working directory. Do not change any files.
Return exactly four lines, with no Markdown fences:
SKILL_MARKER=sample-audit-v1
ROWS=<number of data rows, excluding the header>
MISSING_AMOUNT_IDS=<comma-separated IDs, or none>
TOTAL_KNOWN_AMOUNT=<sum of nonempty amounts, two decimal places>
Keep IDs as text. A blank amount is missing, not zero.
A entrada sample.csv é pequena de propósito:
id,amount
0007,12.50
0008,
0009,7.50
Não cole as quatro linhas da resposta esperada no prompt de delegação: isso permitiria que o agente as reproduzisse sem usar a skill. O experimento só é útil se a resposta exigir a combinação da instrução da skill com o arquivo de entrada.
2. Verifique o pré-carregamento com um agente personalizado
Salve .claude/agents/audit-preloaded.md:
---
name: audit-preloaded
description: Audit sample.csv using the preloaded sample-audit instructions.
tools: Read
skills:
- sample-audit
---
Follow the preloaded audit instructions on sample.csv.
Do not read SKILL.md yourself. If the audit instructions are absent,
report PRELOAD_MISSING rather than inventing a format.
A lista de pré-carregamento atual considera os primeiros 32 nomes distintos. O pré-carregamento fornece o corpo da skill, não todos os arquivos de apoio da pasta. Nenhum desses limites afeta este projeto com uma única skill.
Depois de preparar os arquivos, inicie uma sessão nova e envie:
Use the audit-preloaded subagent to audit sample.csv.
Return its result verbatim. Do not perform the audit in the parent.
Confirme no registro da conversa que audit-preloaded foi selecionado. Esse agente tem apenas Read de propósito: a ausência de uma chamada à ferramenta Skill é normal neste teste de pré-carregamento. Uma leitura direta de SKILL.md, ou a execução da tarefa pelo agente principal, invalidaria a comparação pretendida. Esses seriam outros caminhos para obter a resposta, não evidências de que o pré-carregamento na inicialização funcionou.
A resposta esperada é:
SKILL_MARKER=sample-audit-v1
ROWS=3
MISSING_AMOUNT_IDS=0008
TOTAL_KNOWN_AMOUNT=20.00
Copie apenas a resposta desse agente para result.txt e execute python3 check_result.py result.txt. O verificador valida as quatro linhas do resultado. Ele não comprova o caminho de carregamento; por isso, confira também o registro da conversa e as evidências de depuração.
Para uma contraprova com falha intencional, substitua sample-audit na lista skills: do agente por um nome inexistente, como sample-audit-missing. Em seguida, inicie um novo agente em uma nova sessão principal. O diagnóstico esperado é PRELOAD_MISSING; a redação exata não é garantida. A documentação atual informa que entradas de pré-carregamento ausentes ou desativadas são ignoradas e geram um aviso no log de depuração. Restaure o nome original antes de continuar. Se o agente ainda produzir o resultado normal, verifique se o agente principal forneceu as instruções, se foi selecionado o agente errado ou se outro arquivo continha o marcador.

Documentação oficial capturada para este artigo. A imagem mostra a documentação, não uma execução de inferência bem-sucedida.
3. Compare com a chamada dinâmica sem pré-carregamento
Salve .claude/agents/audit-dynamic.md:
---
name: audit-dynamic
description: Audit sample.csv by invoking the sample-audit skill.
tools: Read, Skill
---
First invoke the sample-audit skill using the Skill tool.
Then follow it on sample.csv. Do not read SKILL.md directly.
If the skill cannot be invoked, report INVOCATION_FAILED and the reason.
Essa definição não tem o campo skills:. Peça ao agente principal que delegue a tarefa a audit-dynamic e devolva a resposta sem alterações. Para considerar esse caminho validado, o registro do subagente precisa mostrar uma chamada de sample-audit pela ferramenta Skill, seguida do mesmo resultado de quatro linhas. O marcador, sozinho, não basta.
Agora remova Skill da lista tools: desse agente e mantenha todo o restante igual. O resultado esperado é uma falha na chamada, pois a definição exige uma ferramenta que deixou de estar disponível. Restaure Skill depois. Não acrescente skills: durante essa contraprova: isso introduziria o caminho separado de pré-carregamento.
Esse teste explícito verifica se a chamada é possível; ele não verifica se o Claude escolhe a skill por conta própria. Para testar a seleção separadamente, use uma nova definição de agente que mantenha tools: Read, Skill, mas remova a instrução explícita sobre sample-audit e use uma descrição neutra, como Audit local CSV files. Dê uma tarefa comum de auditoria sem nomear a skill e confira se ocorre uma chamada de Skill. Se a chamada explícita funcionar, mas essa verificação separada de seleção não, examine a descrição da skill e sua relação com a tarefa. Uma chamada explícita bem-sucedida não comprova seleção automática.
4. Confira os controles de chamada e as permissões de execução
Aplique cada alteração abaixo individualmente no projeto de teste e restaure a configuração original depois de cada verificação:
| Uma alteração | Diferença esperada | Como corrigir |
|---|---|---|
Adicionar disable-model-invocation: true à skill | Nem a chamada dinâmica iniciada pelo modelo nem o pré-carregamento devem utilizá-la | Preserve a opção nos fluxos intencionalmente manuais; use uma skill adequada, que o modelo possa chamar, neste experimento |
Adicionar user-invocable: false no lugar dela | Oculta o comando manual; por si só, não proíbe a chamada pelo modelo | Não confunda ausência no menu de comandos com indisponibilidade para o modelo |
Remover Skill da lista explícita de ferramentas do agente dinâmico | O caminho dinâmico fica indisponível; isso não determina o comportamento do agente com pré-carregamento | Disponibilize Skill apenas onde a chamada dinâmica for necessária |
| Remover o acesso ao arquivo de entrada | As instruções podem estar presentes, mas a leitura dos dados falha | Corrija a permissão específica de arquivo/ferramenta ou sua localização |
As duas opções de chamada têm funções diferentes; consulte quem pode chamar uma skill. Não remova uma restrição intencional a chamadas manuais de uma skill de implantação ou de operações destrutivas apenas para permitir que um agente a use automaticamente.
Uma ferramenta estar listada não significa que todo uso dela seja permitido. Examine as regras de permissão do Claude Code, incluindo proibições, políticas gerenciadas e regras para o nome exato da skill. O campo allowed-tools de uma skill não pode restaurar uma ferramenta excluída do conjunto do agente nem anular uma regra de negação. Se a skill real chama um script Python, investigue Bash e o caminho do script depois de confirmar que as instruções foram carregadas. Nosso exemplo só precisa de Read para a auditoria em si, evitando essa variável adicional.
Não use bypassPermissions como correção de diagnóstico. Ele altera as condições que você está tentando investigar e é desnecessário para um exemplo somente de leitura com três linhas de dados.
5. Resolva problemas de diretório e de nomes
Confira o projeto antes de mover uma skill para seu diretório pessoal global:
pwd
claude --version
ls -l .claude/skills/sample-audit/SKILL.md
ls -l .claude/agents/audit-preloaded.md
ls -l .claude/agents/audit-dynamic.md
O arquivo do agente e o arquivo da skill têm funções diferentes e ficam em diretórios diferentes. Um arquivo em .claude/agents/ não vira uma skill só porque seu texto menciona “skill”. Neste projeto de teste, mantenha iguais o nome da pasta, o nome no frontmatter e a entrada de pré-carregamento. Não coloque um caminho do sistema de arquivos nem /sample-audit na lista skills:.
Em um monorepositório, uma skill em packages/web/.claude/skills/ não equivale a uma skill na raiz. A descoberta em subdiretórios depende da área que o Claude acessa. Comece com o projeto de teste na raiz para eliminar essa incerteza e, depois, reintroduza o subdiretório real. Se um comando carregar instruções inesperadas, procure conflitos entre nomes de skills pessoais e de projeto, além dos namespaces de plugins. As regras oficiais de descoberta e nomes de skills explicam qual origem tem prioridade. Mover todas as skills para o diretório global pode criar um novo conflito em vez de corrigir o original.
Se o arquivo estiver em ../shared/.claude/skills/sample-audit/SKILL.md, inicie com claude --add-dir ../shared e verifique se a skill aparece na nova sessão. Definir apenas permissions.additionalDirectories concede acesso aos arquivos, mas não carrega as skills daquela pasta. Para uma skill em um subdiretório, inicie a sessão no diretório ao qual ela pertence ou use /add-dir em uma versão compatível; depois repita a chamada pelo nome. Registre o diretório inicial e todos os argumentos --add-dir no relatório de erro. Para arquivos de apoio com caminhos relativos, identifique se o caminho parte do diretório da skill ou do diretório de trabalho; nossa sample.csv usa explicitamente o segundo.
Se você criou o diretório principal de skills depois de iniciar a sessão, reinicie-a antes de diagnosticar uma skill ausente. Este projeto inicia uma sessão nova depois da criação dos arquivos de propósito.
6. Reúna evidências se o exemplo mínimo continuar falhando
Use uma nova sessão local com um arquivo privado de depuração, conforme a referência atual da CLI:
claude --debug-file ./claude-skill-debug.log
Reproduza uma variante. Confira o agente selecionado, o nome efetivamente resolvido da skill, os avisos de skill ausente ou desativada, a chamada de Skill no teste do caminho dinâmico e qualquer operação Read ou Bash negada. Revise os logs antes de compartilhá-los: eles podem conter caminhos, prompts e outros dados da sessão. Não publique credenciais nem histórico de conversas sem relação com o problema.
Use este modelo compacto de relatório:
Claude Code version / OS:
Model / provider (no secrets):
Working directory / repository root:
Agent name and definition:
Skill name, path and frontmatter:
Route: preload OR dynamic invocation
Exact prompt and synthetic input:
Expected result / actual result:
Selected-agent evidence / relevant tool call or warning:
Single change made / result after restoring baseline:
Uma falha de inicialização, autenticação, TLS ou limite de requisições ocorre antes de esta auditoria conseguir verificar o comportamento da skill. Para esses sintomas, consulte o guia de erros de TLS no Claude Code (em inglês) ou a solução de problemas de limite de requisições (em inglês). Repetir uma solicitação rejeitada pelo modelo não corrige um nome errado na lista de pré-carregamento, e editar uma skill não resolve um erro de certificado.
E context: fork, o SDK e o Ofox?
Uma skill com context: fork inicia um agente para executar a tarefa da skill. Um agente com skills: começa pelas instruções do próprio agente e recebe conteúdo adicional de skills. Escolha a direção que corresponde ao seu fluxo; esses campos de frontmatter não são intercambiáveis. Consulte como executar skills em um subagente.
Não presuma que os agentes personalizados usados aqui recebem tudo o que você discutiu com o agente principal. Passe explicitamente as entradas necessárias para a tarefa. O Claude Code também documenta outros comportamentos de fork; não generalize o isolamento deste exemplo para todos os tipos de agente ou de bifurcação de conversa.
Se você inicia a execução pelo Claude Agent SDK, confira separadamente as configurações do sistema de arquivos e da ferramenta Skill na documentação de skills do SDK. Uma sessão de terminal encontrar uma skill local não comprova que um processo do SDK iniciado em outro diretório carregue a mesma configuração.
Se você já conecta o Claude Code pelo Ofox, consulte a documentação de integração com o Claude Code em português para configurar a conexão e a referência de tratamento de erros em português para falhas da API. A conectividade com o provedor e o carregamento local de skills são verificações separadas. Trocar o endpoint da API não libera, por si só, recursos da conta Claude nem corrige uma definição local de agente.
Um critério útil de conclusão é concreto: o agente pretendido inicia, o caminho de carregamento escolhido fica visível, as quatro linhas de saída correspondem ao exemplo e a contraprova de falha apresenta um comportamento diferente. Guarde esses registros antes de remontar o fluxo de trabalho real.


