Skill de IA não funciona: por que ela não é acionada e como consertar

Resposta rápida

Se a sua skill de IA não é acionada, o motivo quase sempre está no campo description: é ele que a IA lê para decidir se aquela skill serve para o seu pedido, não o resto do arquivo. Os três erros mais comuns são description vaga demais (“ajuda com documentos”), escrita em primeira pessoa (“eu posso te ajudar com…”), e faltar a parte de “quando usar” (gatilhos concretos, não só o que a skill faz). Corrija a description com as duas partes (o que faz + quando usar), teste com um pedido que use as palavras exatas que você escreveu ali, e na maioria dos casos ela volta a funcionar. Se mesmo assim não acionar, o problema costuma ser colisão de nome com outra skill parecida ou um nome genérico demais. Sigo explicando cada caso abaixo.

Por que a IA ignora a minha skill que eu criei?

Aqui na CPDF (Comunidade Profissionais do Futuro, por Danilo Gato) eu vejo esse problema toda semana em quem está começando a criar as próprias skills: a pessoa escreve uma instrução ótima dentro do arquivo, mas a IA nunca chama aquilo, e o aluno acha que “a skill tá bugada”. Na prática, quase nunca é bug.

O jeito como isso funciona é simples de entender uma vez que você vê o mecanismo. Toda skill tem dois campos obrigatórios no topo do arquivo: name e description. No começo da conversa, a IA carrega só esses dois campos de TODAS as skills instaladas, não o conteúdo inteiro. É um índice, tipo um sumário de livro. Quando você manda um pedido, ela compara o que você escreveu com esse índice e decide se alguma description bate. Só aí, se bater, ela vai ler o arquivo completo.

Isso quer dizer uma coisa importante: a description não é uma explicação para humano lerem depois. Ela é a regra de roteamento que decide se a skill dispara ou fica largada. Se ela for vaga, genérica, ou não citar as palavras que as pessoas realmente usam para pedir aquilo, a skill nunca vai ser encontrada, mesmo que o resto do arquivo esteja perfeito.

Como saber se a skill está sendo acionada na conversa?

Antes de sair reescrevendo tudo, confirme o diagnóstico. Três formas rápidas de testar:

1. Pergunte direto pra IA. Pergunte “quais skills você tem disponíveis agora?” ou “você tem uma skill pra X?”. Se ela não citar a sua, o problema é de descoberta (a description não bateu). Se ela citar mas não usar, o problema é outro (a instrução dentro do arquivo, não a description).
2. Use as palavras exatas da sua própria description. Se você escreveu “processa planilhas Excel e gera relatórios”, peça literalmente isso. Se nem assim ela aciona, a instalação está errada (arquivo no lugar errado, nome de arquivo trocado), não a redação.
3. Teste variações realistas do pedido, não só a frase perfeita. Ninguém pede exatamente como está escrito na description. Se só a frase idêntica funciona, a description está estreita demais e só cobre um jeito de perguntar.

Essa etapa de teste não é opcional: é a diferença entre corrigir o problema certo e ficar reescrevendo o arquivo errado, achando que resolveu, e a skill continuar ignorada na próxima conversa.

O que escrever na descrição para ela ser encontrada?

A regra que funciona na prática: a description precisa responder duas perguntas na mesma frase, o que a skill faz e quando usar ela. Faltar a segunda parte é o erro mais comum que eu vejo.

Nível	Exemplo	Por que funciona ou não
Ruim	“Ajuda com documentos”	Vago demais, nenhuma palavra-gatilho, qualquer pedido de documento é candidato ou nenhum é
Ruim	“Eu posso analisar seus dados de vendas”	Primeira pessoa. A description é injetada dentro do prompt de sistema da IA, e ponto de vista inconsistente atrapalha a IA achar a própria voz na hora de decidir
Bom	“Analisa planilhas de vendas em Excel, calcula ticket médio e gera gráfico de tendência. Use quando o usuário mencionar vendas, planilha, Excel, .xlsx ou pedir relatório de vendas”	Diz o que faz E quando usar, cita as palavras reais que uma pessoa usaria
Bom	“Gera mensagens de commit a partir do diff do git. Use quando o usuário pedir ajuda para escrever mensagem de commit ou revisar mudanças já commitadas”	Mesmo padrão: ação + gatilho concreto

Sempre em terceira pessoa (regra oficial da Anthropic, dona da tecnologia por trás da maioria dos agentes hoje): “processa X” e não “eu processo X” nem “você pode usar isso para X”. E não economize nas palavras-chave: se o seu público às vezes fala “planilha” e às vezes fala “Excel”, os dois termos precisam estar na description, porque a IA não vai adivinhar sinônimo que não está escrito ali.

Minha skill colide com outra parecida: como resolver?

Isso acontece muito em quem instala várias skills prontas ao mesmo tempo, ou em equipe, onde cada pessoa criou a sua sem combinar nome com ninguém. Dois sintomas típicos:

• Nome genérico demais (“helper”, “utils”, “tools”, “dados”). Se duas skills têm nome parecido e descrição parecida, a IA tem que adivinhar qual você quis, e às vezes acerta a errada ou não aciona nenhuma.
• Duas skills cobrindo o mesmo território com descriptions que se sobrepõem (as duas mencionam “planilha”, por exemplo). A saída não é apagar uma: é deixar cada description mais específica, cortando a sobreposição. Se uma é para análise financeira e outra para relatório comercial, isso precisa estar escrito ali, não só implícito no seu conhecimento de qual é qual.

Regra prática de nomenclatura: use nome específico, de preferência descrevendo a ação (“processar-notas-fiscais” em vez de “financeiro”). Nome específico também facilita quando você mesmo, meses depois, está procurando qual skill faz o quê.

Fiz tudo certo e ainda não funciona: o problema pode ser o modelo?

Às vezes sim, mas isso é menos comum do que description malfeita. Um jeito de calibrar: existe um conceito de “grau de liberdade” que a Anthropic usa para escrever instrução dentro da skill. Tarefa com várias formas válidas de resolver (revisão de texto, por exemplo) pede instrução mais aberta, tipo lista de pontos de atenção. Tarefa frágil, onde um passo fora de ordem quebra tudo (migração de banco de dados, preencher um formulário com campos interligados) pede instrução fechada, praticamente um script que a IA segue à risca sem inventar.

Se a sua skill mistura os dois (dá liberdade demais numa etapa que era pra ser travada, ou trava demais uma etapa que precisava de julgamento), o sintoma que aparece não é “não aciona”, é “aciona mas erra o meio do caminho”. Nesse caso o ajuste é na instrução, não na description.

Checklist de 5 minutos para destravar sua skill

1. Abra o arquivo e leia só a description em voz alta. Ela diz o que a skill faz E quando usar, nessa ordem?
2. Ela está em terceira pessoa, sem “eu” nem “você pode”?
3. As palavras que você usou batem com o jeito real que as pessoas pedem aquilo (sinônimos incluídos)?
4. O nome da skill é específico, ou é do tipo “helper”/“tools” que colide com qualquer outra coisa genérica instalada?
5. Teste perguntando à IA “quais skills você tem?” antes de qualquer outro ajuste, pra confirmar se o problema é descoberta ou execução.

Isso resolve a maioria absoluta dos casos que chegam até mim. Segundo o relatório 2026 da McKinsey (Global Survey on AI), 62% das empresas já estão pelo menos testando agentes de IA, mas só 23% conseguiram escalar o uso em alguma área da operação. A distância entre “testei” e “escalei” é quase sempre isso: gente empacotando conhecimento em skill, mas sem a description funcionando como deveria, então o agente nunca acha o que já foi construído.

Se você ainda está no começo de como estruturar uma skill do zero (o que é o arquivo, como criar, quando vale a pena empacotar conhecimento assim), tem o guia completo no nosso artigo sobre skills de IA. E se o problema que você tem não é a skill não ser chamada, mas o agente esquecer regras no meio de uma tarefa longa, o assunto muda de figura, vale ler sobre manutenção de agente de IA.