Skill Doctor
Diagnostique e melhore qualquer SKILL.md. Uma bússola, não um manual — os padrões concretos estão em references/, leia sob demanda.
Fluxo de diagnóstico após o acionamento (cada passo deve produzir saída visível)
Um passo sem saída visível é silenciosamente ignorado (experimento Seleznov, 2026). Imprima uma linha de confirmação por passo. Sinalizador de auto-revisão: se esta sessão já Editou/Escreveu o SKILL.md alvo, prefixe cada linha de impressão do doctor com
[auto-revisão]e acrescente uma linha ao final do Passo 3: "a conclusão é autoavaliada, recomenda-se reavaliar com um subagente novo."
Passo 1: Leia o SKILL.md alvo, anuncie o início do diagnóstico
Leia o texto completo do SKILL.md que está sendo editado, execute python3 <diretório-deste-skill>/scripts/check_listing_budget.py "<raiz_do_projeto>" (cite o caminho — espaços são comuns), imprima duas linhas:
[skill-doctor] Auditando: <caminho> corpo=<N> linhas descrição=<M> caracteres
[skill-doctor] Orçamento (<plataforma>): <K> skills, <T> caracteres vs ≈<B> → <cabe | EXCEDIDO ×N.N>
Detecta automaticamente a plataforma (CC / Codex / Hermes / OpenClaw). Saída: 0 = cabe; 1 = excedido; 2 = indisponível (sem plataforma / contexto desconhecido → pergunte ao usuário plataforma + janela). Excedido é um AVISO em nível de população, não uma constatação contra o skill auditado: imprima os números para o usuário saber, mas NÃO encurte a descrição deste skill por questões de orçamento — redução é uma ação global, nunca uma correção de skill único.
Passo 2: Julgue contra as dimensões
Escolha as dimensões para carregar do índice de referências (seção Dimensões) — leia apenas as entradas cujo quando-ler for acionado. Após carregar, imprima uma linha:
[skill-doctor] Carregado: <lista>; Ignorado: <lista com motivo de uma palavra>
Passo 2.5: Teste de execução a seco (apenas quando o corpo contém um fluxo de trabalho)
Seguindo references/effect-dry-run.md, pegue o prompt mais típico e percorra as etapas do corpo, verificando se entrada/instrução/saída estão conectadas.
Qualquer link quebrado ou ambiguidade → marque P0 (problema de efeito) e coloque na seção ❌ do Passo 3.
Imprima uma linha:
[skill-doctor] Teste seco Prompt: "<prompt>" links quebrados=<N>
Se o corpo não tiver fluxo de trabalho (skill puramente de regra/referência), imprima:
[skill-doctor] Teste seco: ignorado (sem fluxo de trabalho)
Passo 2.6: Verificação de injeção ao vivo (apenas quando o skill alvo está no escopo da sessão atual)
Verifique se o alvo aparece na lista de skills disponíveis desta sessão com sua descrição (não apenas nome). Os 3 casos (injetado / queda de orçamento apenas-nome / ignorado fora-de-escopo) e a regra de aviso de população estão em references/live-injection-check.md. Imprima uma linha:
[skill-doctor] Injeção ao-vivo: <injetado | CAÍDO (apenas-nome) | ignorado (<motivo>)>
Passo 3: Saída do relatório de diagnóstico
Formate estritamente como abaixo, imprima na conversa:
[skill-doctor] Diagnóstico
❌ Deve corrigir (ordenado P0→P3, definições em references/priority-tiers.md)
[P0 quebra de efeito] <problema>: <porquê> → <correção>
[P1 estrutura] <problema>: <porquê> → <correção>
[P2 especificidade] <problema>: <porquê> → <correção>
[P3 afeta execução] <problema>: <porquê> → <correção>
⚠️ Melhorias sugeridas (incluindo P3 puramente cosmético/verboso)
- <problema>: <porquê> → <correção>
✅ Verificações aprovadas
- <lista>
Regra de posicionamento P3: pergunte "se não corrigido, o próximo LLM executando este skill fará algo errado?" — sim → ❌; apenas feio/verboso → ⚠️. Veja references/priority-tiers.md.
Cada problema deve dar um número de linha ou campo específico — sem vagueza. Quando o mesmo tipo de violação aparece em vários lugares, liste-os separadamente — por exemplo, conteúdo mal categorizado em três subdiretórios deve ser 3 problemas, não 1 entrada mesclada.
Nomeie o modo de falha quando aplicável (veja references/predictability-glossary.md): prefixe a constatação com [sem-op] / [sedimento] / [conclusão-prematura] / [palavra-líder-fraca] / [duplicação] / [expansão]. O nome diz qual tipo; o nível P ainda diz quão grave — ortogonais, então o prefixo nunca substitui o nível.
Passo 4: Aplique com Editar após confirmação do usuário
Nunca Editar sem confirmação. Aguarde o usuário dizer "corrija" antes de agir.
Antes de agir, aplique a porta de tamanho e a verificação pré-exclusão; depois feche o ciclo — procedimento completo em references/apply-safety.md.
Após corrigir, imprima uma linha:
[skill-doctor] Aplicadas <N> correções em <caminho> corpo: <antigo>→<novo> linhas (<+X%>)
Referência rápida de regras rígidas
As regras rígidas quantificadas (uma violação é um erro, não uma sugestão) estão em references/hard-rules.md — consulte em toda auditoria.
Fallback de exceção
Quando um caminho está faltando, YAML não faz parsing, ou um script empacotado (scripts/check_listing_budget.py + scripts/detect_platform.py / scripts/check_routes.py / scripts/eval_retrieval.py / scripts/check_desc_slim.py) está faltando ou sai com código 2 — trate conforme references/exception-fallback.md. Anuncie a exceção ao usuário primeiro; nunca ignore silenciosamente.
Saída e idioma
O texto do relatório segue references/output-style.md (claro, seguro para terminal, conclusão primeiro). Corpo/referências padrão em inglês; sinalize não-inglês injustificado ⚠️ — política + as duas exceções justificadas em references/language-policy.md.
Fora do escopo deste skill
- Se a funcionalidade real está correta (isso é um bug de lógica, não um problema de forma do skill)
- Convenções específicas do projeto (essas vão no CLAUDE.md, não em um skill)
- Scripts de correção única (descartados após executar uma vez, não devem ser um skill)
Por que este skill existe
Por que LLMs escrevem SKILL.md como um manual, e como este skill separa verificações mecânicas de julgamento: references/rationale.md.