← Voltar ao curso
Nível 2 — Ferramenta de trabalho · Módulo 2.4 — Skills de verdade

2.4.6 · Troubleshooting: por que minha skill não dispara

3 min de vídeo TODOS

Objetivo: ao final, o consultor diagnostica os quatro motivos mais comuns de uma skill não acionar quando deveria, e confirma se uma skill carregou corretamente na sessão.

O que você precisa levar desta aula

  1. Os quatro motivos mais comuns de uma skill não disparar: description vaga (sem as palavras reais do dia a dia), frontmatter mal formado, skill salva no diretório errado, e duas skills competindo pelo mesmo gatilho.
  2. A description precisa conter as palavras que o consultor realmente digita ao pedir aquilo — não uma descrição genérica do que a skill faz.
  3. Para confirmar que uma skill carregou corretamente na sessão, digite / no campo de prompt e confira se ela aparece na lista.

Os quatro motivos, em detalhe

# Causa Sintoma Correção
1 Description vaga Só dispara se você chamar pelo nome exato da skill, não pelo jeito natural de pedir Reescrever a description com as palavras reais que você digita no dia a dia
2 Frontmatter mal formado Erro ao carregar a sessão, ou a skill simplesmente não aparece em lugar nenhum Corrigir o YAML no topo do SKILL.md (dois-pontos, indentação)
3 Diretório errado Funciona na sua máquina, não aparece para quem clona o mesmo repositório Mover a pasta da skill para .claude/skills/nome-da-skill/
4 Duas skills competindo O Claude aciona a skill errada, ou nenhuma, diante de um pedido ambíguo Reescrever as descriptions para não se sobreporem

Como confirmar que uma skill carregou

Digite / no campo de prompt da sessão — o mesmo gesto já visto no módulo 2.1.7 para ver comandos e skills disponíveis na extensão. Se a skill esperada não aparecer na lista, o problema é uma das quatro causas acima, quase sempre nessa ordem de probabilidade: description vaga primeiro, diretório errado depois.

📖 Skills — troubleshooting

Quiz — 4 questões

1.Você digita "revisa esse checklist de cutover" e nada acontece. Quando digita o nome exato da skill, ela funciona normalmente. Qual é a causa mais provável?
  • a)Frontmatter mal formado

    Se o frontmatter estivesse quebrado, a skill provavelmente nem carregaria, mesmo chamada pelo nome exato.

  • b)Description vaga, sem as palavras que você realmente digita no dia a dia

    Correto. A skill existe e funciona — o problema é que a description não reconhece o pedido natural.

  • c)Diretório errado

    Se estivesse no diretório errado, ela não funcionaria nem mesmo chamada pelo nome exato.

Ver resposta e por quê
❌a) Se o frontmatter estivesse quebrado, a skill provavelmente nem carregaria, mesmo chamada pelo nome exato.
✅b) Correto. A skill existe e funciona — o problema é que a description não reconhece o pedido natural.
❌c) Se estivesse no diretório errado, ela não funcionaria nem mesmo chamada pelo nome exato.
2.Ao abrir uma sessão, aparece um erro relacionado a interpretar o topo de um SKILL.md. Qual é a causa?
  • a)Description vaga demais

    Description vaga causa não disparar, não um erro de carregamento da sessão.

  • b)Duas skills competindo pelo mesmo gatilho

    Skills competindo gera escolha errada de qual dispara, não erro de carregamento.

  • c)Frontmatter mal formado — YAML quebrado no topo do arquivo

    Correto.

Ver resposta e por quê
❌a) Description vaga causa não disparar, não um erro de carregamento da sessão.
❌b) Skills competindo gera escolha errada de qual dispara, não erro de carregamento.
✅c) Correto.
3.Uma skill funciona perfeitamente na sua máquina, mas um colega que clonou o mesmo repositório do Meridiano não consegue acioná-la de jeito nenhum. Qual é a causa mais provável?
  • a)A description está vaga demais

    Se fosse só a description, o colega ao menos veria a skill disparar ocasionalmente ou ao chamar pelo nome — aqui ela não aparece de forma alguma para ele.

  • b)Duas skills estão competindo pelo mesmo gatilho

    Competição de gatilho faria o Claude escolher a errada, não a skill desaparecer completamente para um colega específico.

  • c)A skill foi salva fora do diretório .claude/skills reconhecido pelo Claude Code

    Correto.

Ver resposta e por quê
❌a) Se fosse só a description, o colega ao menos veria a skill disparar ocasionalmente ou ao chamar pelo nome — aqui ela não aparece de forma alguma para ele.
❌b) Competição de gatilho faria o Claude escolher a errada, não a skill desaparecer completamente para um colega específico.
✅c) Correto.
4.Duas skills da squad têm descriptions muito parecidas — "revisão de spec" e "revisão de documento funcional". Ao pedir "revisa essa spec", o Claude aciona a skill errada. Qual é a causa e a correção?
  • a)Frontmatter mal formado em uma delas — corrigir o YAML

    O sintoma descrito não é erro de carregamento, é escolha entre duas skills válidas.

  • b)Duas skills competindo pelo mesmo gatilho — reescrever as descriptions para não se sobreporem

    Correto.

  • c)Skill salva no diretório errado — mover para .claude/skills

    Ambas as skills já disparam (uma delas, inclusive, é a errada) — o problema não é uma delas estar invisível, é a sobreposição de gatilho.

Ver resposta e por quê
❌a) O sintoma descrito não é erro de carregamento, é escolha entre duas skills válidas.
✅b) Correto.
❌c) Ambas as skills já disparam (uma delas, inclusive, é a errada) — o problema não é uma delas estar invisível, é a sobreposição de gatilho.