🐛 Tipos de Problemas em Skills
Antes de debugar, e importante entender os tipos de problemas que podem ocorrer. Cada categoria tem suas proprias tecnicas de diagnostico.
Skill Nao Carrega
Skill nunca e ativada
- • Frontmatter invalido (YAML)
- • Descricao nao faz match
- • Diretorio errado
- • Nome de arquivo incorreto
Comportamento Errado
Carrega mas faz coisa errada
- • Instrucoes ambiguas
- • Conflito com outras skills
- • Falta de contexto
- • Interpretacao incorreta
Erros de Execucao
Tools falham durante uso
- • Permissoes insuficientes
- • Arquivos nao encontrados
- • Comandos com sintaxe errada
- • APIs indisponiveis
Problemas de Performance
Funciona mas e lento
- • Skill muito longa
- • Muitas tools em sequencia
- • Loops desnecessarios
- • Contexto saturado
💡 Primeira Pergunta
Sempre comece com: "A skill esta sendo carregada?" Se nao, o problema e de descoberta. Se sim, e de comportamento ou execucao.
🔎 Tecnicas de Diagnostico
Siga um processo sistematico para identificar a causa raiz do problema.
Verificar se Skill Carrega
Use o comando /skills ou pergunte ao agente
/skills
# ou
"Quais skills voce tem carregadas agora?"Validar Frontmatter
YAML invalido impede carregamento
# Use um validador YAML online ou:
python3 -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])"Testar Descricao
A descricao faz match com o pedido do usuario?
# Pergunte ao agente:
"Que skill voce usaria para [tarefa especifica]?"Isolar o Problema
Desative outras skills, simplifique o input, teste passo a passo
📋 Checklist Rapido de Diagnostico
- ☐ Arquivo e SKILL.md (nao skill.md)?
- ☐ Esta no diretorio correto?
- ☐ Frontmatter tem --- no inicio e fim?
- ☐ name: e description: estao presentes?
- ☐ YAML e valido (sem tabs, espacos corretos)?
- ☐ Descricao contem palavras-chave relevantes?
📝 Implementando Logging
Logging nao e automatico em skills - voce precisa instruir o agente a reportar acoes. Bom logging facilita debugging futuro.
📋 Niveis de Log
- DEBUG: Detalhes internos (so para desenvolvimento)
- INFO: Operacoes normais (arquivo criado, analise completa)
- WARN: Algo inesperado mas nao bloqueante
- ERROR: Falha que impede conclusao
Instrucoes de Logging na Skill
## Logging
Ao executar esta skill, reporte progresso no formato:
[INFO] Descricao da acao executada
[WARN] Descricao do alerta
[ERROR] Descricao do erro
Exemplo de execucao:
[INFO] Iniciando analise de codigo em /projeto/src
[INFO] Encontrados 23 arquivos .js
[WARN] Arquivo muito grande ignorado: bundle.min.js
[INFO] Analise completa: 5 issues encontrados
[INFO] Relatorio gerado em /projeto/report.md✓ Logar
- ✓ Inicio e fim de operacoes
- ✓ Arquivos criados/modificados
- ✓ Decisoes importantes
- ✓ Erros e como foram tratados
✗ Evitar Logar
- ✗ Dados sensiveis (senhas, tokens)
- ✗ Conteudo completo de arquivos
- ✗ Detalhes excessivos que poluem
- ✗ Informacoes pessoais do usuario
🔧 Corrigindo Problemas Comuns
Alguns problemas aparecem repetidamente. Aqui estao solucoes rapidas para os mais comuns.
Skill Nunca Carrega
Problema mais comum
Causas:
- • Arquivo nao e SKILL.md (case-sensitive)
- • Diretorio errado
- • Frontmatter YAML invalido
Solucao: Verifique nome, local e valide YAML
Carrega mas Nao Ativa
Descricao nao faz match
Causas:
- • Descricao muito especifica ou generica
- • Faltam palavras-chave
- • Outra skill mais relevante
Solucao: Melhore descricao com sinonimos e casos de uso
Tool Nao Permitida
allowed-tools restrito demais
Causas:
- • Tool necessaria nao listada
- • Pattern de permissao incorreto
Solucao: Adicione tools necessarias ao frontmatter
Comportamento Inconsistente
Funciona as vezes, falha outras
Causas:
- • Instrucoes ambiguas
- • Falta de exemplos
- • Contexto insuficiente
Solucao: Adicione exemplos claros e seja mais especifico
🧪 Testando Skills Sistematicamente
Criar um suite de testes para sua skill previne regressoes e facilita manutencao.
📋 Framework de Testes Manual
Crie um documento com cenarios de teste:
# Testes da Skill: minha-skill
## Cenario 1: Caso basico
Input: "faz X com Y"
Esperado: Cria arquivo Z com conteudo A
Status: [ ] Passou [ ] Falhou
## Cenario 2: Input invalido
Input: "faz X" (sem Y)
Esperado: Pede esclarecimento sobre Y
Status: [ ] Passou [ ] Falhou
## Cenario 3: Arquivo nao existe
Input: "analisa /path/inexistente"
Esperado: Erro claro sobre arquivo
Status: [ ] Passou [ ] Falhou🟢 Happy Path
Cenario ideal funciona
- • Input valido
- • Arquivos existem
- • Permissoes OK
🟡 Edge Cases
Limites e excecoes
- • Input vazio
- • Arquivos grandes
- • Caracteres especiais
🔴 Error Cases
Falhas esperadas
- • Arquivo inexistente
- • Sem permissao
- • Tool indisponivel
💡 Dica de Manutencao
Execute os testes apos cada modificacao da skill. Isso pega regressoes antes de afetar usuarios.
📊 Monitoramento em Producao
Mesmo skills testadas podem falhar em producao. Monitoramento continuo ajuda a identificar problemas cedo.
📈 Metricas de Uso
- • Quantas vezes ativada por dia
- • Taxa de sucesso vs falha
- • Tempo medio de execucao
- • Usuarios unicos
🔴 Metricas de Erro
- • Tipos de erro mais comuns
- • Taxa de erro por versao
- • Erros por horario/dia
- • Tempo medio para resolver
🚨 Configurando Alertas
Defina alertas para situacoes criticas:
- 🔴 Taxa de erro > 10% - investigar imediatamente
- 🟡 Tempo de execucao > 30s - verificar performance
- 🔵 Queda de 50% no uso - mudanca de comportamento?
🚀 Proximo Passo
Com debugging e logging dominados, o proximo modulo aborda Performance e Otimizacao - como criar skills rapidas e eficientes.
📚 Resumo do Modulo
Proximo Modulo:
1.7 - Performance e Otimizacao