enmr10/skill-doctor

O que skill-doctor faz?

Diagnostique uma biblioteca de skills. Encontre skills cujas descrições competem pelos mesmos prompts e corrija o roteamento.

Quando executar

• Você instalou muitas skills e "a skill errada continua sendo acionada"
• Antes de publicar um pacote de skills (para capturar colisões que revisores encontrarão)
• Após adicionar uma skill (ela colide com uma existente?)
• Verificação periódica de saúde em uma biblioteca em crescimento

Entrada

Aponte o motor para UM dos seguintes:

• Um diretório de skills (<raiz>/<nome>/SKILL.md), ou
• Um manifest.json do Claude Code (skills-plugin/.../manifest.json)

Como executar

O motor está em scripts/ ao lado deste arquivo. Zero dependências (Python 3.8+ stdlib).

# A partir do diretório que contém este SKILL.md:
python3 -m scripts <caminho-para-skills-ou-manifest>            # Relatório Markdown
python3 -m scripts <caminho> --format json --out report.json  # Saída para máquina
python3 -m scripts <caminho> --fail-on critical               # Portão CI (código de saída 1)

Opções comuns:

• --merge-at 0.55 — pontuação de colisão que aciona uma recomendação MERGE
• --disambig-at 0.30 — pontuação que aciona uma recomendação DISAMBIGUATE
• --vague-threshold 0.5 — sinaliza descrições mais vagas que isso
• --top 12 — quantas principais colisões listar
• --format md|json|both

O que detecta (códigos de problema)

Código	Severidade	Significado
DUPLICATE_TRIGGER	🔴	Mesma frase de gatilho reivindicada por 2 ou mais skills (principal causa de roteamento incorreto)
DUPLICATE_NAME	🔴	Duas skills compartilham o mesmo nome
MISSING_DESCRIPTION	🔴	Skill nunca pode ser acionada de forma confiável
HIGH_OVERLAP	🔴/🟠	Duas descrições são semanticamente muito próximas
VAGUE_DESCRIPTION	🟠	Cheia de palavras de enchimento, sem "use quando", sem gatilhos
NAME_DIR_MISMATCH	🟠	nome ≠ diretório (quebra a especificação)
BAD_NAME_FORMAT	🟠	nome quebra as regras de minúsculas/hífen
DESC_TOO_SHORT / DESC_TOO_LONG	🟠/🟡	Fora do intervalo de 40–1024 caracteres
NO_BOUNDARY	🟡	Sem referência cruzada "Para X, veja "
BODY_TOO_LONG	🔵	Corpo do SKILL.md > 500 linhas

Como a pontuação funciona (em uma linha)

colisão = 0,50·cosseno(TF-IDF das descrições)
        + 0,35·jaccard(frases de gatilho)
        + 0,15·jaccard(palavras-chave de domínio)

Faixas: <0,22 BAIXA · 0,22 MÉDIA · 0,38 ALTA · 0,55 CRÍTICA. Consulte references/scoring.md para a justificativa completa.

Fluxo de trabalho para o agente

1. Execute o motor no caminho de skills do usuário → leia o relatório Markdown.
2. Resuma a pontuação de saúde, os piores clusters e os gatilhos duplicados.
3. Para cada recomendação principal, proponha a edição concreta:
   • MERGE → elabore uma descrição combinada, sugira o nome sobrevivente.
   • ABSORV → nomeie a skill a ser excluída e para onde seus gatilhos vão.
   • DISAMBIGUATE → escreva as duas linhas de limite espelho ("Para X, veja Y.").
4. Ofereça-se para aplicar as reescritas de descrição (edite o frontmatter de cada SKILL.md).
5. Reexecute para confirmar que a pontuação de saúde melhorou.

Saída

• Um relatório Markdown: pontuação de saúde, principais colisões, clusters confundíveis, tabela de gatilhos duplicados, recomendações, lista completa de problemas, mapa de calor ASCII.
• JSON opcional (--format json) para portões CI ou outras ferramentas.

Regras

• O motor é somente leitura — ele nunca edita skills. As reescritas são aplicadas pelo agente (você) somente após a aprovação do usuário.
• Nunca exclua uma skill sem confirmação explícita.
• Ao reescrever descrições, preserve toda frase de gatilho real em que o usuário confia; apenas mova/desambigue elas — não as descarte.

Consulte references/methodology.md para o algoritmo e references/issue-catalog.md para como corrigir cada tipo de problema.