skill-issue — auditor de ativação de skill

Visão Geral

Um agente de codificação decide qual skill executar a partir do name + description "sempre ativo" de cada skill. Uma skill pode ser implementada perfeitamente e ainda assim nunca ser acionada porque sua descrição é muito vaga para corresponder à forma como as pessoas formulam solicitações, ou porque uma skill irmã mais específica vence silenciosamente. skill-issue audita exatamente essa superfície, avaliando cada skill de A a F, simulando qual skill é acionada para um determinado prompt e relatando clusters de colisão onde uma skill ofusca outra.

Quando Usar Esta Skill

• Use quando uma skill que você escreveu nunca parece ser acionada e você não sabe por quê
• Use quando o usuário disser "por que minha skill não está funcionando", "qual skill é acionada para X" ou "audite minhas skills"
• Use após escrever ou instalar um novo SKILL.md, para confirmar que ele será realmente selecionado
• Use em CI para falhar um PR que adiciona uma skill com metadados vazios/duplicados/colidindo

Como Funciona

Instale a CLI (npm i -g @misha_misha/skill-issue, brew install mishanefedov/skill-issue/skill-issue ou npx @misha_misha/skill-issue), então:

skill-issue ~/.claude/skills                       # grade every skill A–F (+ collisions summary)
skill-issue ~/.codex/skills --why "deploy to prod" # which skill fires for this prompt, and why
skill-issue <dir> --collisions                     # clusters of skills that shadow each other
skill-issue <dir> --fix                            # append a "Use when …" clause to weak descriptions
skill-issue <dir> --json                           # machine-readable; exits non-zero on errors

Heurística offline por padrão; adicione --llm para julgar com uma CLI claude/codex local.

Exemplos

Exemplo 1: Auditar skills instaladas

skill-issue ~/.claude/skills
# F  deploy-helper  ✗ no description — can never fire
# C  shipit         ! no "use when …" trigger clause
# A  rollback-prod  ✓ will fire on its triggers

Exemplo 2: Diagnosticar uma colisão

skill-issue ~/.claude/skills --why "deploy the app to prod"
#  1. shipit       0.74  ← would fire
#  2. land-deploy  0.69  (margin 0.05 — ambiguous, likely collision)

Limitações

• A pontuação offline é heurística e deve ser tratada como um sinal de triagem, não como um veredito final de qualidade.
• Relatórios de colisão destacam prováveis ofuscações, mas roteadores específicos do agente podem ponderar metadados de forma diferente.
• O modo --fix pode melhorar a redação de gatilhos fracos, mas as edições geradas ainda precisam de revisão do mantenedor antes de serem confirmadas.