e9tgldr/skill-router

Roteador de Skills (Skill Router)

Atualmente existem aproximadamente 170 skills instaladas aqui e elas variam enormemente em qualidade e escopo, diversas delas são quase duplicatas umas das outras (três skills de design "não pareça genérico" separadas, duas cópias de impeccable, xlsx ao lado de xlsx-dsh). Escolher mal é o erro mais caro disponível: uma skill errada custa todo o seu corpo em contexto e arrasta a resposta para fora do alvo, enquanto nenhuma skill geralmente é melhor do que a skill errada.

Portanto: roteie primeiro, depois trabalhe. Este arquivo é o procedimento de roteamento. Ele é barato — uma varredura de arquivo, uma ou duas chamadas de ferramenta — e substitui a adivinhação a partir da lista de skills. O procedimento é independente de instalação: as contagens, nomes e famílias abaixo descrevem o catálogo para o qual foi escrito, e a busca normaliza para qualquer catálogo que encontrar.

1. Leia a tarefa antes de tocar em qualquer coisa

Responda a estas perguntas silenciosamente, em uma linha cada. Elas decidem a rota, não o entregável.

• O que é produzido? Um arquivo (docx/xlsx/pdf/pptx/png), código em execução, uma decisão, uma mensagem, um plano.
• Qual domínio? Frontend web, backend, dados, documentos, design, vídeo/animação, VR, operações.
• Existe um artefato existente? Greenfield vs. modificação do código de alguém — isso inverte a rota de skills de construção para skills de auditoria/revisão e entender-primeiro.
• Quem lê a saída? Investidor, professor, colega de equipe, compilador. O público altera a skill de escrita, não a técnica.

Se a solicitação for uma frase de intenção pura ("faça algo legal para mim"), isso também é um sinal de roteamento: significa que nenhuma skill pode ser escolhida ainda e as perguntas vêm primeiro (passo 6).

2. Caminho rápido — verifique a tabela de roteamento

Leia references/task-types.md (relativo ao diretório desta skill). A primeira tabela mapeia aproximadamente 40 formatos de tarefa comuns para uma cadeia de skills verificada em uma tela; a segunda lista ferramentas estreitas com nomes difíceis de adivinhar (animation-vocabulary, cdn-caching, vercel-connect) que ninguém procura, então verifique-a antes de concluir que nada se encaixa.

• Correspondência encontrada → vá para o passo 4 com essa cadeia. Não pesquise também; a tabela é a resposta e pesquisar novamente apenas queima tokens.
• Sem correspondência, ou a correspondência é parcial → passo 3.
• A tabela nomeia skills que você não tem (uma instalação diferente, um harness diferente, uma máquina nova) → pule a tabela inteiramente e vá para o passo 3. A tabela é o mapeamento de uma instalação; a pesquisa funciona em qualquer catálogo. Verifique com --doctor.

3. Pesquise no catálogo

Um comando, nenhum modelo necessário:

# o caminho é relativo ao diretório desta skill
node scripts/find_skills.mjs "página de destino parece genérica" -n 8
node scripts/find_skills.mjs --doctor      # quais raízes foram escaneadas, o que foi encontrado

Ele pontua todas as skills instaladas com base no nome + descrição (ponderação IDF, então palavras raras vencem sobre usuário/código/quando) mais uma camada de conceitos curada para frases que não compartilham vocabulário com a skill de que precisam. Imprime as melhores correspondências com seus caminhos SKILL.md, ou NENHUMA BOA CORRESPONDÊNCIA quando nada se encaixa.

Como consultá-lo bem:

• Use os substantivos da tarefa, não a frase do usuário: planilhas gráficos csv, não "você pode transformar isso em algo com um gráfico".
• Execute 2–3 ângulos diferentes em vez de uma consulta longa — o ângulo do artefato (pitch deck), o ângulo do domínio (captação de recursos investidores), o ângulo do problema (texto parece modelado). Agrupe-os em uma chamada bash, se preferir.
• --explain imprime por que cada resultado foi classificado, token por token — use-o quando um resultado parecer errado em vez de adivinhar a causa.
• Cada resultado é marcado como [forte], [provável] ou [fraco]. [fraco] significa que o roteador está adivinhando a partir de uma palavra incidental — trate-o como uma sugestão, não como uma resposta, e prefira seu próprio julgamento. Se todos os resultados forem fracos, o script informa.
• --all despeja o catálogo completo, --nome pdf resolve um nome para um caminho, --json dá saída legível por máquina, -n 20 amplia a lista quando você quiser ver os vice-campeões (muitas vezes a resposta certa é a #4 para uma consulta mal formulada).
• Os resultados são classificados, não autoritativos. Você ainda escolhe.
• O script reside no diretório scripts/ desta skill. Se o harness expuser um caminho absoluto, use-o; caso contrário, cd para o diretório da skill primeiro.
• Ele indexa o que quer que exista, não uma lista fixa: ele escaneia os diretórios de skills usuais por usuário e por projeto em todos os harnesses (~/.pi, ~/.claude, ~/.codex, ~/.agents, ~/.cursor, mais <cwd>/skills e node_modules de plugins. Aponte-o para qualquer outro lugar com SKILL_ROUTER_ROOTS=/a/skills:/b/skills ou --root /a/skills. Em uma máquina desconhecida, execute --doctor primeiro: ele lista cada raiz, se ela existe, quantas skills contribuiu, nomes duplicados e arquivos SKILL.md que não conseguiu analisar. Nenhum conceito ou porta é necessário para um novo catálogo — eles são impulsos opcionais sobre a classificação lexical; com zero deles, a pesquisa ainda classifica por nome e descrição.

Se o script em si estiver indisponível ou uma pesquisa não retornar nada plausível duas vezes, recorra a ler as descrições de ~/.pi/agent/skills/ da lista do prompt do sistema. Não pare, e não abra cinco arquivos SKILL.md na esperança de que um se destaque.

4. Escolha — regras que mantêm a cadeia curta

1. Processo antes da implementação. Skills que definem como o trabalho é executado (brainstorming, escrever-planos, depuração-sistemática, desenvolvimento-orientado-a-testes, escrever-skills) carregam antes de skills que definem como a saída se parece (design, docx, nextjs). Skills de processo frequentemente dizem para carregar uma skill de implementação em seguida — deixe-as.

2. Máximo de três skills. Uma é normal, duas é comum, três é o teto. Uma quarta significa que você está colecionando em vez de decidindo.

3. Uma por família. Nunca carregue dois membros da mesma família — pegue a primeira coluna:

   Família	Escolha um
   Gosto de frontend / anti-genérico	design-taste-frontend, ui-craft, impeccable, frontend-design, craft
   Cópias duplicadas	impeccable (agents/) sobre impeccable-dsh; xlsx sobre xlsx-dsh; kimi/* sobre dsh/* a menos que o dsh seja claramente mais específico
   Formato de documento	exatamente o que corresponde ao arquivo: docx, pdf, pptx, xlsx
   Movimento	animate (web), animate-expo (React Native) — não ambos
   Backend	backend-patterns, create-a-backend, api-design — no máximo dois
   Quest / VR	família hz-* + metavr-cli; sempre comece com hz-quest-verify-first

4. Respeite as portas de plataforma. hz-*, portal, metavr-cli precisam de um contexto Quest/VR; cloudbase precisa de CloudBase; kimi-webbridge / kimi-cu precisam de um navegador real ou GUI de desktop. Se a tarefa não nomear a plataforma, a skill não se aplica, não importa o quanto as palavras correspondam.

5. Justifique ou rejeite. Para cada candidato, uma cláusula: por que este. Se a cláusula for "ele menciona as mesmas palavras", rejeite-o. Duas skills podem compartilhar vocabulário e ainda assim ser para máquinas diferentes.

6. Nenhum é uma resposta válida. Se nada passar do sarrafo, diga em poucas palavras e faça a tarefa com seu próprio julgamento. Uma skill faltando não é motivo para iniciar uma skill meio relevante.

7. Re-roteie apenas em pivôs. Uma nova sub-tarefa dentro do mesmo fluxo de trabalho não dispara uma nova pesquisa. Uma mudança de domínio (o usuário diz "na verdade, faça disso uma apresentação") dispara.

5. Anuncie em uma linha, depois prossiga

Antes de fazer o trabalho, declare a rota uma vez:

Usando design-taste-frontend (página de destino anti-modelada) → animate para o herói. Nenhuma skill se encaixa na parte de copywriting; escrevendo isso eu mesmo.

Regras para essa linha: uma ou duas frases, apenas nomes + razões. Sem ensaios sobre o inventário de skills, sem "Eu selecionei as seguintes skills para esta tarefa porque…". O usuário quer ver a decisão, não a deliberação. Se a rota for incomum ou você estiver conscientemente se desviando da tabela, essa é a única coisa que vale uma cláusula extra.

6. Pergunte apenas o que bloqueia o trabalho

É aqui que o roteamento se paga: uma skill escolhida diz o que precisa saber, então faça essas perguntas — e apenas essas.

Pergunte quando, e apenas quando:

• a tarefa tem duas ou mais entregas genuinamente diferentes ("um pôster" pode ser PNG ou uma apresentação de slides, e os arquivos diferem),
• o público ou formato é desconhecido e impossível de adivinhar pelo contexto,
• as próprias instruções da skill escolhida exigem uma decisão que o usuário deve possuir (marca, orçamento, credenciais, dados reais vs. fictícios),
• uma rota custaria dinheiro real ou tocaria em produção.

Não pergunte:

• qual skill usar — esse é o trabalho desta skill. Pergunte sobre o resultado, deixe o roteamento seguir a partir da resposta,
• qualquer coisa que a solicitação já responda, qualquer coisa que o código ou arquivos respondam,
• qualquer coisa que um padrão sensato cubra. Escolha o padrão, diga qual padrão você escolheu na linha de anúncio e continue. Este usuário prefere execuções longas e desacompanhadas a confirmação passo a passo.

Forma: uma chamada ask_user_question, no máximo 3 perguntas, 2–4 opções cada, opção recomendada primeiro com "(Recomendado)" no rótulo, uma frase curta por opção dizendo o que ela compromete. Nunca empilhe um segundo questionário logo após o primeiro; se uma resposta levantar uma nova pergunta, prefira um padrão razoável a mais uma viagem de ida e volta.

Se a skill que você carregou tem sua própria fase de descoberta ou perguntas (a maioria das skills de design e planejamento tem), execute essa em vez de inventar a sua própria. Duas rodadas de perguntas consecutivas parecem enrolação.

7. Carregue e execute

• Leia o SKILL.md com a ferramenta read, completamente, no caminho que a pesquisa retornou. Skills lidas superficialmente produzem saída superficial.

• Resolva quaisquer caminhos references/, scripts/, assets/ relativos ao diretório dessa skill — a saída da pesquisa imprime o arquivo, então o diretório pai é a raiz da skill.

• Execute os scripts como escritos. Se um script precisar de um argumento que não documenta, diga em vez de substituir sua própria implementação.

• A skill vence empates. Uma vez carregada, suas instruções substituem as opiniões deste arquivo sobre como fazer o trabalho e substituem a boa prática genérica. Este arquivo apenas a escolheu.

• Se uma skill carregada começar com "pergunte ao usuário primeiro" ou "planeje antes de escrever código", faça isso — rotear para uma skill de processo e depois pular seu processo é pior do que não rotear.

• Se no meio do trabalho você descobrir que a skill estava errada, diga claramente e re-roteie (passo 4). Contornar silenciosamente uma skill ruim é o modo de falha.

• Registre a correção para que o mesmo erro não seja cometido duas vezes:

  node scripts/find_skills.mjs --learn "<a frase que falhou>" <skill-correta>
  node scripts/find_skills.mjs --wrong "<a frase que falhou>" <skill-errada>
  

  Faça isso sempre que o usuário rejeitar uma rota, uma skill carregada se mostrar a ferramenta errada, ou você precisou rotear manualmente porque a pesquisa errou. Correções aprendidas superam a pontuação lexical em consultas futuras semelhantes, e elas viajam com a instalação — é assim que este roteador melhora em um ambiente que nunca viu.

8. Fechamento

Uma linha no final: quais skills foram usadas e onde o artefato foi parar. Depois pare — sem resumo do conteúdo das skills, sem oferta para explicar o roteamento.

Manutenção — alterando o roteador sem quebrá-lo

O roteador é pontuado, não sentido. scripts/eval_routing.mjs contém 80 consultas realistas, cada uma com o conjunto de skills que são respostas genuinamente aceitáveis, mais dúzia de casos de porta (uma consulta genérica de React nunca deve trazer à tona uma skill Quest). Execute-o antes e depois de qualquer alteração:

node scripts/eval_routing.mjs
# pontuação: 80/80 (100.0%)  vazamentos de porta: 0
node ... --verbose      # classificação por caso
node ... quest          # apenas casos correspondentes

node scripts/smoke_portable.mjs   # catálogo estrangeiro + aprendizado + escala de 600 skills

smoke_portable.mjs é o teste de portabilidade: ele inventa 16 skills em domínios que este roteador nunca viu (Kubernetes, Rust, Salesforce, Terraform…), verifica classificação, robustez de paráfrase, a porta portátil, aprendizado, nomes duplicados, catálogos vazios, caminhos com espaços, SKILL_ROUTER_ROOTS e uma execução em escala de 600 skills. Se você alterar a pontuação, ambos os conjuntos devem permanecer verdes — a avaliação protege a qualidade em um catálogo conhecido, a fumaça protege o comportamento em um desconhecido.

Uma alteração que aumenta a pontuação é uma melhoria; uma alteração que a diminui é uma regressão, não importa o quão mais arrumado o código pareça. Casos cujas skills esperadas não estão instaladas são pulados, não falhados, para que o conjunto seja executado em qualquer máquina.

Quando uma tarefa real roteia mal, corrija na camada mais barata que explique:

1. Palavras erradas para a mesma ideia → adicione uma regra CONCEPTS curada em find_skills.mjs (when regex → boost pontuações, unless veto opcional e demote). Esta é a camada para intenção que não compartilha vocabulário com a skill: "ideia vaga, sem especificação" → brainstorming. Único? Não recorra a isso — registre-o em vez disso (--learn). CONCEPTS é para comportamento geral; memória é para "esta frase, esta skill".
2. Um formato de tarefa recorrente → adicione uma linha a references/task-types.md. Não custa nada no momento da consulta e o caminho rápido pula a pesquisa completamente.
3. Uma skill que continua perdendo para vizinhos barulhentos → adicione-a a DEMOTE, ou dê ao vizinho barulhento um demote em um conceito (por exemplo, dashboard sozinho não deve vencer ui-craft com ui-craft-dense-dashboard).
4. Uma skill de plataforma vazando para consultas genéricas → estenda GATES com as palavras que devem estar presentes para que ela seja elegível.
5. Uma rota que o usuário corrigiu → --learn / --wrong, depois siga em frente. Verifique --memory ocasionalmente: se a mesma skill continua sendo corrigida para o mesmo tipo de redação, promova o padrão para CONCEPTS e --forget as entradas.

Adicione a consulta com falha a CASES primeiro, veja-a falhar, depois corrija. Não ajuste a pontuação em consultas que você não anotou — é assim que o roteador acaba bom nos seus exemplos e ruim nos do usuário.

Bandeiras vermelhas — você está racionalizando, pare

Pensamento	Realidade
"Isso é simples, não precisa de roteamento"	Roteie rápido, implemente rápido. O caminho rápido

...

[truncado para tradução]