Skills: Problemas Comuns e Solução de Problemas
Última atualização: 2026-08-31
Não entre em pânico ao encontrar problemas — 90% dos problemas de Skills têm soluções padronizadas. Este guia de referência rápida ajuda a localizar e resolver problemas rapidamente.
1. Referência Rápida de Categorias de Problemas
(1) Problemas de Carregamento
| Sintoma | Possível Causa | Solução |
|---|---|---|
| Skill não carrega | Caminho de arquivo errado | Verificar diretório e nome do arquivo |
| Skill não carrega | Erro de formato do frontmatter | Verificar sintaxe YAML |
| Skill não carrega | Trigger incompatível | Verificar palavras-chave e condições de trigger |
| Múltiplas Skills em conflito | Mesma prioridade | Definir prioridades ou usar triggers mais precisos |
(2) Problemas de Execução
| Sintoma | Possível Causa | Solução |
|---|---|---|
| Ferramenta não chamada | Prompt não requer explicitamente | Especificar etapas de uso da ferramenta no fluxo |
| Ferramenta não chamada | Ferramenta não vinculada | Verificar lista de tools no frontmatter |
| Formato de saída errado | Descrição do prompt não é específica | Fornecer template de saída e exemplos |
| Saída alucinada | Prompt falta restrições | Adicionar "apenas gerar saída com base no conteúdo efetivamente lido" |
(3) Problemas de Qualidade
| Sintoma | Possível Causa | Solução |
|---|---|---|
| Itens de revisão perdidos | Dimensões de revisão incompletas | Adicionar itens de verificação; usar enumeração ao invés de descrição |
| Correção introduz novo bug | Etapa de verificação ausente | Adicionar etapa "executar testes após correção" |
| Saída inconsistente | Prompt ambíguo | Usar tabelas e listas ao invés de linguagem natural |
| Overflow de contexto | Muita informação do projeto | Adicionar regras de corte de contexto |
2. Métodos de Diagnóstico
(1) Método de Diagnóstico em Camadas
TEXT
📖 Somente leitura
Quatro Camadas de Diagnóstico de Problema
├── Camada 1: Camada de Arquivo
│ ├── O arquivo existe?
│ ├── O caminho está correto?
│ └── O frontmatter é válido?
├── Camada 2: Camada de Configuração
│ ├── O trigger corresponde?
│ ├── As ferramentas estão vinculadas?
│ └── As permissões são suficientes?
├── Camada 3: Camada de Prompt
│ ├── As instruções são claras?
│ ├── Os exemplos são suficientes?
│ └── As restrições são explícitas?
└── Camada 4: Camada de Execução
├── As ferramentas foram chamadas como esperado?
├── A saída corresponde ao formato?
└── O resultado atende ao objetivo?
(2) Método de Teste A/B
TEXT
📖 Somente leitura
Teste A/B de Prompt
1. Manter todas as outras condições iguais
2. Apenas modificar uma parte do prompt
3. Comparar qualidade da saída
4. Manter a versão melhor
5. Registrar o motivo da mudança
(3) Reprodução Mínima
TEXT
📖 Somente leitura
Passos de Reprodução do Problema
1. Criar um arquivo de Skill mínimo
2. Manter apenas o prompt principal
3. Confirmar se o problema se reproduz
4. Adicionar conteúdo gradualmente para localizar a condição disparadora
5. Correção direcionada
3. Técnicas Comuns de Correção
(1) Ajuste Fino de Prompt
TEXT
📖 Somente leitura
Técnicas Comuns de Ajuste Fino
├── Adicionar exemplos: Formato de saída errado → Adicionar exemplo de saída esperada
├── Adicionar restrições: Saída muito verbosa → Adicionar "conciso, no máximo N linhas"
├── Adicionar etapas: Ferramenta não chamada → Adicionar "Etapa N: Usar ferramenta XX"
├── Adicionar condições: Comportamento incorreto → Adicionar "Se X, então Y; caso contrário Z"
└── Adicionar negação: Fazendo coisas que não deveria → Adicionar "Não faça X"
(2) Ajustes de Vinculação de Ferramenta
TEXT
📖 Somente leitura
Correções de Problemas de Ferramenta
├── Ferramenta não chamada: Especificar explicitamente no fluxo "Usar Read para ler arquivo"
├── Ferramenta errada usada: Declarar no prompt "Usar Edit não Write para modificar arquivos"
├── Permissões insuficientes: Verificar configuração allow/deny no settings.json
└── Timeout de ferramenta: Estreitar escopo de busca, reduzir volume de dados
(3) Correções de Trigger
TEXT
📖 Somente leitura
Correções de Problemas de Trigger
├── Não dispara: Palavra-chave muito obscura → Adicionar sinônimos comuns
├── Falso disparo: Palavra-chave muito ampla → Estreitar escopo de correspondência
├── Conflitos: Múltiplas Skills competindo → Ajustar prioridades
└── Disparo frequente: Condição muito frouxa → Adicionar condições AND
4. Checklist de Depuração
(1) Checklist de Depuração de Skills
MARKDOWN
## Checklist de Depuração
### Verificações Básicas
- [ ] Caminho de arquivo correto
- [ ] Sintaxe YAML do frontmatter correta
- [ ] name e description preenchidos
- [ ] triggers configurados
### Verificações Funcionais
- [ ] Vinculações de ferramenta completas
- [ ] Prompt tem etapas de execução claras
- [ ] Tem exemplo de formato de saída
- [ ] Tem restrições e condições de contorno
### Verificações de Qualidade
- [ ] Verificado em projeto de teste
- [ ] Formato de saída estável
- [ ] Chamadas de ferramenta razoáveis
- [ ] Sem riscos de segurança
(2) Nota de Diferenças entre Plataformas
| Nota | Claude Code | Cursor | OpenCode |
|---|---|---|---|
| Localização do arquivo | .claude/skills/ |
.cursor/rules/ |
skills/ |
| Auto-load | Suportado | Suportado | Precisa de config |
| Sintaxe de trigger | YAML | Markdown frontmatter | Markdown |
| Permissões de ferramenta | settings.json | Config do projeto | Arquivo de config |
❓ Perguntas Frequentes
P: Skill funciona de forma inconsistente? R: Saída de IA tem aleatoriedade inerente. Adicione restrições e exemplos no prompt para reduzir o espaço de saída e melhorar consistência. Adicione "por favor confirme antes de executar" para decisões críticas. P: Como determinar se é um problema da Skill ou da plataforma de IA? R: Teste uma Skill simples na mesma plataforma. Se a Skill simples também tem problemas, é um problema da plataforma; se apenas a Skill específica tem problemas, é um problema da Skill. P: Como evitar que problemas se repitam após corrigir? R: Adicione condições de restrição no prompt da Skill e verifique em projetos de teste. Registre experiência de correção no CHANGELOG.
📖 Resumo
- Três categorias de problemas: carregamento, execução, qualidade — cada uma com tabelas de referência rápida
- Três métodos de diagnóstico: diagnóstico em camadas, teste A/B, reprodução mínima
- Técnicas de correção: Ajuste fino de prompt (adicionar exemplos/restrições/etapas/condições/negações)
- Checklist de depuração: Verificações básicas → Verificações funcionais → Verificações de qualidade
📝 Exercícios
- Básico (⭐): Siga o checklist de depuração para verificar todas as suas Skills criadas e corrigir quaisquer problemas encontrados.
- Intermediário (⭐⭐): Escreva um manual de solução de problemas de Skills para sua equipe com pelo menos 10 problemas e soluções.
- Avançado (⭐⭐⭐): Crie uma Skill de diagnóstico que pode verificar automaticamente outras Skills quanto a problemas comuns e fornecer sugestões de correção.
