⚠️ Por que auditar
Skills acumulam problemas silenciosamente. Uma instrução que foi adicionada em um momento de frustração pode conflitar com outra adicionada seis meses depois. Um gatilho que era preciso ficou vago à medida que você criou mais skills no mesmo domínio. Uma seção inteira de uma skill deixou de ser relevante mas nunca foi removida. Sem auditoria, você só descobre esses problemas quando a skill falha de forma visível — e para cada falha visível, há provavelmente dez falhas sutis que você nunca percebeu.
⚠️ Tipos de Problemas que Auditoria Detecta
Problemas estruturais
Problemas de gatilho
🤖 O agente claude-code-guide
O claude-code-guide é um agente especializado pré-configurado com conhecimento detalhado sobre estrutura de skills, boas práticas do Claude Code SDK e padrões de qualidade. Diferente de pedir ao Claude genérico para auditar, o agente tem critérios específicos e consistentes que tornam a análise comparável entre diferentes skills e entre diferentes sessões. É o equivalente de ter um revisor experiente que aplica o mesmo padrão de qualidade toda vez.
🤖 Por que usar o agente especializado
Critérios padronizados: a mesma checklist aplicada a toda skill, sem variação por sessão
Conhecimento de SDK: sabe quais práticas funcionam especificamente no Claude Code, não apenas em LLMs em geral
Score objetivo: gera um número comparável (0-100) que permite priorizar quais skills precisam de atenção primeiro
Relatório acionável: não apenas aponta problemas — propõe correções concretas para cada um
📋 O prompt de auditoria
O prompt de auditoria é uma instrução estruturada que você passa ao agente para obter uma análise completa de uma skill. A estrutura do prompt determina a qualidade do relatório — um prompt bem formatado gera diagnóstico preciso com pontuação e prioridades; um prompt vago gera impressões subjetivas sem direção. Use o prompt padrão abaixo e apenas substitua o conteúdo da skill.
📋 O Prompt Padrão de Auditoria
Audite a skill abaixo e retorne um relatório estruturado com:
SCORE: [0-100] — nota geral de qualidade estrutural
PROBLEMAS (em ordem de impacto):
P1. [problema mais crítico] — impacto: [alto/médio/baixo] — correção: [o que fazer]
P2. [segundo problema] — ...
P3. [terceiro problema] — ...
CHECKLIST:
[ ] Gatilho na primeira frase da descrição
[ ] Seções organizadas com cabeçalhos
[ ] Sem instruções conflitantes
[ ] Seção de avaliação presente
[ ] Sem dead code (instruções obsoletas)
[ ] Exemplos de input/output quando necessário
VERSÃO CORRIGIDA: [skill reescrita com os problemas resolvidos]
[COLAR CONTEÚDO DA SKILL AQUI]"
☑️ Checklist estrutural
O checklist estrutural são os seis pontos que o agente verifica em toda auditoria. Conhecer esses critérios não serve apenas para entender o relatório — serve para aplicar os critérios você mesmo antes mesmo de chamar o agente. Um checklist rápido manual antes da auditoria formal reduz o tempo da sessão de auditoria e aumenta a qualidade do relatório (o agente pode focar em problemas menos óbvios).
☑️ Os 6 Pontos do Checklist Estrutural
A primeira frase da descrição contém "Use quando", "Acione para" ou equivalente com casos de uso específicos?
O arquivo tem cabeçalhos claros (## PROIBIDO, ## ENTREVISTA, ## GERAÇÃO, ## AVALIAÇÃO) que organizam o conteúdo?
Há alguma instrução que contradiz outra dentro da mesma skill? (Ex: "seja formal" em um lugar e "use gírias" em outro)
A skill tem a seção ## AVALIAÇÃO com as perguntas de rating ao final?
Há instruções que nunca são executadas, seções obsoletas ou contexto que não se aplica mais ao uso atual?
Para skills complexas, há exemplos de input/output esperado que ancorem o entendimento do modelo?
🎯 O que fazer com os resultados
O relatório de auditoria vai listar problemas em várias skills. A tentação é tentar corrigir tudo de uma vez — o que leva à paralisia ou ao trabalho de baixa qualidade. A priorização inteligente maximiza o retorno do tempo investido. Skills com score baixo e uso frequente são as mais críticas. Skills com score médio podem esperar. Skills pouco usadas com problemas menores podem ser ignoradas até a próxima auditoria trimestral.
🎯 Matriz de Priorização
Score <60
+
Uso alto
Estas skills estão causando problemas hoje. Corrija imediatamente após a auditoria.
Score 60-80
+
Uso médio
Funcionam razoavelmente mas têm potencial significativo de melhoria.
Score >80
ou
Uso baixo
Podem esperar. Revisão no próximo ciclo trimestral.
💡 Dica Prática
Antes de começar as correções, crie um arquivo de registro da auditoria: data, skills auditadas, scores, problemas identificados, correções aplicadas. Esse registro torna o histórico de evolução da biblioteca visível e comparável entre auditorias.
📅 Cadência de auditoria
A auditoria não deve ser um evento de crise — deve ser uma prática de manutenção regular. Sem uma cadência definida, ela sempre vai ser adiada em favor de trabalho mais urgente. Uma cadência em três níveis garante que a biblioteca se mantenha saudável sem exigir esforço concentrado em momentos difíceis: auditoria completa trimestral, revisão rápida mensal das mais usadas, e correção imediata quando uma skill gera output abaixo de 7.
A cada
3
meses
Auditoria Completa
Todas as skills passam pelo prompt de auditoria completo com o agente claude-code-guide. Score calculado para cada skill. Priorização e execução das correções mais críticas.
Tempo estimado: 2-3 horas para uma biblioteca de 10-20 skills
A cada
1
mês
Revisão Rápida
As 3-5 skills mais usadas passam pelo checklist manual de 6 pontos. Ajustes pontuais aplicados. Sem auditoria completa pelo agente.
Tempo estimado: 30-45 minutos
Nota
≤6
imediato
Correção Imediata
Qualquer skill que recebe nota 6 ou abaixo no sistema de avaliação do módulo anterior é revisada imediatamente com o feedback coletado. Não espera o ciclo programado.
Tempo estimado: 15-20 minutos por skill
🔍 Resumo do Módulo
Trilha Concluída!
Você completou todas as 8 dicas técnicas da Trilha 2. Você agora sabe como testar, otimizar, personalizar e manter uma biblioteca de skills de alta performance.