Agent Mentor Learn
Claude Code Skills: crie seus próprios fluxos de trabalho com IA · Lição 4 de 6

Lição 4: Testes e depuração: garantindo que sua Skill se comporte

Objetivos de aprendizado:

  • Conhecer as formas básicas de testar uma Skill
  • Diagnosticar as falhas que você vai realmente encontrar
  • Entender o ciclo de iteração
  • Saber como avaliar se uma Skill vale mesmo a pena manter

Pré-requisitos: << Lição 3 | Próxima: Lição 5 >>

Sua primeira Skill não vai sair certa

Você escreveu sua primeira Skill, executou e percebeu coisas assim:

  • Algumas tarefas não foram reconhecidas de jeito nenhum
  • As prioridades saíram erradas
  • O formato de saída ficou uma bagunça
  • Ou o Claude nem chegou a carregar a Skill

Isso é normal.

Skills são como código: fazer rodar uma vez é a linha de largada, não a chegada. Toda Skill realmente útil chegou lá depois de várias rodadas de revisão.1

Esta lição te dá um jeito repetível de encontrar e corrigir esses problemas.

Método de teste 1: invocar diretamente

O teste mais simples é a invocação direta: chame uma vez com /skill-name e observe o que sai.2

Prepare seus casos de teste

Antes de invocar qualquer coisa, escreva de três a cinco entradas.

Casos normais:

Terminar o relatório trimestralRevisar o PR #234, antes de sextaCorrigir o bug de login amanhã

Casos-limite:

(entrada vazia)

Casos de lixo:

Este é um parágrafo de texto completamente sem relação, sem nenhuma tarefa dentroasldfkjasldfj!@#$%

Rode os testes

No Claude Code, forneça uma de cada vez:

/task-organizer
Terminar o relatório trimestralRevisar o PR #234, antes de sextaCorrigir o bug de login amanhã

Observe três coisas:

  1. O Claude chegou a carregar a Skill? (Se não, o problema está na description.)
  2. O formato de saída está correto? (Se estiver bagunçado, o problema está na sua seção de formato de saída.)
  3. O conteúdo é o que você esperava? (Se as categorias estiverem erradas, o problema está nos seus passos de processamento.)

Anote o que aconteceu

Uma tabela pequena já basta:

EntradaEsperadoRealProblema
"Terminar o relatório trimestral\nCorrigir o bug amanhã"2 tarefas; o bug é urgenteSó 1 tarefa encontradaAs quebras de linha não estão sendo tratadas como separadores

Método de teste 2: observar o comportamento de carregamento

Às vezes o problema não está nas instruções — está no frontmatter.

Problema: o Claude não carrega a Skill sozinho

O que você vê: você diz “me ajuda a organizar essas tarefas” e o Claude ignora sua Skill task-organizer.

Causas prováveis:

  1. A description é genérica demais

    Correção: coloque as palavras-gatilho ali.

  2. A description não contém as palavras que você realmente usa

    Se você diz “me ajuda a organizar esses to-dos” mas “to-do” não aparece em lugar nenhum da description, o Claude pode nunca se lembrar da Skill.3

    Correção: escreva na description as palavras que um usuário plausivelmente diria.

Problema: o Claude carrega a Skill errada

O que você vê: você queria a task-organizer, mas o Claude pegou outra coisa.

Causa provável: a description da outra Skill combina melhor com a sua entrada.

Correção: force a chamada com /task-organizer, ou afie sua description para que ela fique mais específica que a da concorrente.

Diagnosticando falhas comuns

Problema 1: o formato de saída está errado

O que você vê: a Skill roda, mas a formatação sai errada.

Exemplo:

Urgente: Corrigir o bug de login - amanhãImportante: Revisar o PR #234 - sexta

Você queria seções agrupadas com emoji e títulos; o Claude te deu uma lista de texto plana.

Causa: a seção de formato de saída não é específica o bastante, ou não tem exemplo.

Correção: coloque um exemplo completo na seção “Formato de saída” do seu SKILL.md:

Diga “deve seguir exatamente este formato” e depois mostre a coisa inteira.

Problema 2: o reconhecimento é impreciso

O que você vê: algumas tarefas passam batido, ou caem na categoria errada.

Exemplo:

Entrada:

Preciso corrigir aquele bug amanhãDeixar a demo pronta antes de sexta

Saída:

### ⚪ Normal- Preciso corrigir aquele bug amanhã - sem prazo declarado- Deixar a demo pronta antes de sexta - sem prazo declarado

As duas têm prazo claro, e as duas foram marcadas como se não tivessem.

Causa: as regras de reconhecimento de tempo nos seus passos de processamento não cobrem casos suficientes.

Correção: complete-as.

A ideia: explicite todas as formulações em que você conseguir pensar.

Problema 3: casos-limite escapam

O que você vê: entradas normais funcionam, mas entradas incomuns fazem a Skill se comportar de forma estranha.

Exemplo:

Entrada: uma string vazia

Saída: o Claude trava, ou produz um monte de texto sem sentido.

Causa: sua seção “Observações” nunca disse o que fazer com entrada vazia.

Correção:

O ciclo de iteração

Boas Skills não são escritas de uma vez. Elas saem de um ciclo testar-corrigir-testar:1

1. Escreva a primeira versão (só o comportamento central)2. Rode contra 3-5 casos de teste3. Anote o que deu errado4. Edite o SKILL.md5. Teste de novo6. Repita 3-5 até todos os casos de teste passarem7. Use de verdade por uma semana8. Encontre problemas novos9. Volte ao passo 4

Não espere que a versão um esteja certa. Faça rodar, depois faça funcionar direito, depois faça ficar bom.

A Skill é realmente útil?

Depois que ela roda corretamente, resta uma pergunta maior: essa Skill está mesmo economizando seu tempo?1

Faça um A/B

A comparação é simples: rode a mesma tarefa várias vezes com e sem a Skill, e cronometre as duas.

Sem a Skill:

Cronometre. Você explica o processo na mão, o Claude executa — quanto tempo isso leva em média?

Com a Skill:

Cronometre. Você invoca a Skill, o Claude executa — quanto tempo em média?

Se a versão com Skill não for mais rápida, ou a qualidade for pior, a Skill ainda precisa de trabalho.

Use por uma semana

O teste de verdade é o uso de verdade.4

Acompanhe estes números:

  • Quantas vezes você a invocou
  • Quantas vezes o resultado foi usável como estava, sem edições manuais
  • Quantas vezes você teve que rodar de novo ou corrigir a saída na mão
  • Quanto tempo ela economizou

Se você a invocou menos de três vezes em uma semana, a tarefa provavelmente não é repetitiva o bastante para justificar uma Skill.

Guia rápido de depuração

Quando uma Skill não funciona, comece por uma checagem de falha de carregamento — percorra a tabela abaixo e descarte o caminho do arquivo, o formato do frontmatter e as palavras-gatilho nessa ordem.

ProblemaComo diagnosticarOnde corrigir
O Claude não carrega a Skill automaticamenteVerifique se a description contém as palavras que você realmente disseAdicione palavras-gatilho, explicite o caso de uso
Formato de saída bagunçadoVerifique se você deu um exemplo completo de saídaAdicione o exemplo, adicione “deve seguir exatamente este formato”
Reconhecimento imprecisoVerifique se os passos de processamento enumeram todos os casosAdicione regras, adicione mais critérios de decisão
Casos-limite se comportam malVerifique se “Observações” cobre esse casoAdicione tratamento explícito para o caso especial
A Skill existe mas não é invocadaVerifique o caminho do arquivo, verifique o formato do frontmatterConfirme que os marcadores --- estão no lugar certo e que a indentação do YAML é válida

Recapitulação

  • Sua primeira Skill não vai sair certa — chegar lá exige um ciclo testar-corrigir-testar
  • Métodos de teste: invocar diretamente, observar o comportamento de carregamento, preparar casos de teste antes
  • Falhas comuns: description genérica demais, formato de saída pouco especificado, regras de reconhecimento incompletas, casos-limite sem tratamento
  • Fluxo de depuração: registre esperado vs. real, diagnostique, edite o SKILL.md, reteste
  • Provando que vale a pena: compare tempo, qualidade e consistência com e sem a Skill, depois use por uma semana e conte as invocações

Na próxima lição vamos percorrer uma Skill completa de code review e ver como lidar com um fluxo de trabalho mais elaborado.

>> Lição 5: Estudo de caso: construindo uma Skill de code review

Footnotes

  1. Claude Code skills: fluxos de trabalho .NET e prompts reutilizáveis — https://codewithmukesh.com/blog/skills-claude-code/ ↩ ↩2 ↩3

  2. Documentação oficial do Claude Code: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩

  3. Building skills for Claude, na prática: frontmatter YAML e testes — https://sjramblings.io/building-skills-for-claude-part-2/ ↩

  4. Skills do Claude como runbooks autodocumentados — https://zackproser.com/blog/claude-skills-internal-training ↩

Exercícios

01

Pegue a Skill que você construiu na Lição 3 e submeta-a a uma passada completa de testes:

Nível 1: Depure sua própria Skill
  1. Prepare 3 casos de teste (um normal, um limite, um de lixo)
  2. Registre a saída esperada e a real de cada um
  3. Encontre pelo menos um problema concreto
  4. Edite o SKILL.md
  5. Teste de novo e confirme que o problema sumiu
Critérios de conclusão · marcado localmente
02

Faça a mesma tarefa duas vezes: uma com sua Skill, outra apenas descrevendo o que você quer direto ao Claude. Depois compare:

Nível 2: Compare com não usar Skill nenhuma
  1. Qual foi mais rápida
  2. Qual produziu resultados melhores
  3. Qual foi mais consistente (mesmo formato de saída em execuções repetidas)
Critérios de conclusão · marcado localmente