Escolher uma skill entre 182 para um agente

Um agente de código tem 182 skills instaladas. Cada turno começa com ele lendo um índice: uma linha por skill, com a descrição cortada para não engolir a conversa. No harness do experimento, o corte é em 60 caracteres.

Nessa largura, a skill que edita arquivos .pptx e a que cria arquivos .pptx parecem a mesma coisa. Pede-se um deck de apresentação e o agente carrega a errada. E num turno em que nenhuma skill serve, ele carrega uma de todo jeito — porque uma lista de nomes convida ao chute.

Por que a solução ingênua falha

Existem duas saídas óbvias, e as duas cobram caro.

Carregar tudo. Colocar as 182 skills inteiras no contexto resolve a ambiguidade e cria três problemas: custo por turno, piora na própria seleção (mais texto, mais distração) e context rot para o resto da sessão. É exatamente o efeito que a documentação descreve como state grande cheio de detalhe irrelevante.

Aumentar o corte. Passar de 60 para 200 caracteres por linha multiplica o índice por três e empurra o problema alguns metros para frente, sem resolver o caso das skills vizinhas.

O que falta não é mais texto no contexto do agente: é uma decisão antes da decisão.

O desenho das perguntas

A receita usa divulgação progressiva: ler tudo de forma barata, depois ler pouco com profundidade. Duas requisições na frente do turno.

Requisição 1, varrer as 182. Um Choice com uma opção por skill, usando como critério a mesma linha do índice que o agente recebe. As probabilidades são a ordenação. Junto, três Noul que perguntam, de três ângulos, se o turno pede ação e não explicação:

PERGUNTAS_DE_NECESSIDADE = {
    "age_no_sistema": (
        "Está sendo pedido ao assistente que atue nos arquivos, contas, dispositivos ou "
        "serviços do usuário, em vez de apenas explicar ou aconselhar?"
    ),
    "segue_procedimento": (
        "Um especialista cuidadoso consultaria um procedimento documentado específico "
        "para responder isto, em vez de responder pelo entendimento geral?"
    ),
    "texto_basta": (
        "Um generalista competente atenderia isto inteiramente por escrito, sem "
        "ferramentas, sem documentação e sem acesso aos arquivos do usuário?"
    ),
}

A terceira conta invertida. A média das três decide se vale sugerir algo: abaixo de 0,30, o sistema fica calado. E a razão de perguntar sobre ação em vez de assunto é fina e importante: uma pergunta sobre tema não separa “explique o que é uma mônada” de um pedido que precisa de skill, porque os dois são software.

Requisição 2, ler três com calma. Um Choice sobre a lista curta, agora com a descrição completa e o começo das instruções de cada skill como critério. Mais um Noul por candidato: esta skill faz exatamente a coisa pedida? Como cada Noul é absoluto, todos podem vir baixos — e uma lista curta cujo melhor encaixe fica abaixo de 0,30 é descartada inteira.

O resultado entra como uma linha no prompt do sistema, depois do catálogo, dizendo qual entrada olhar primeiro e deixando claro que pode ser ignorada. O catálogo em si não muda, então o cache de prefixo continua valendo.

O que o experimento oficial mediu

A avaliação usa 488 pedidos de um turno: 315 cobertos por exatamente uma skill (171 skills distintas) e 173 cobertos por nenhuma, escritos de propósito para punir o chute. Os números são da TypeSafe, com o jev-1.12 na seleção e claude-haiku-4-5-20251001 como agente medido, publicados em 31 de julho de 2026:

Três leituras honestas. A primeira: a terceira linha não é um concorrente, é o piso — um agente a quem se entrega a resposta certa ainda erra 2,5% das vezes, e nenhum método de seleção passa disso. A segunda: a sugestão também estraga casos. Dos 315 pedidos cobertos, ela corrigiu 37 e quebrou 7, porque uma sugestão errada e confiante convence mais que nenhuma. A terceira: dos 36 primeiros palpites errados do agente sozinho, 10 vinham da categoria certa — o agente já estava procurando no lugar certo, e o problema era distinguir vizinhos.

O caso das duas skills de apresentação mostra as duas requisições trabalhando: na varredura ampla, a skill de edição ficou na frente (0,700 contra 0,300); na segunda leitura, com o texto completo de cada uma, a escolha virou para a de criação, que era a correta para o pedido.

E o cookbook publica um fracasso, o que dá credibilidade ao resto: um pedido para publicar no Mastodon, num catálogo que tem skill para X e nada para Mastodon, passou pelos dois filtros e recebeu a sugestão do X, com encaixe 0,56. A segunda passagem só pode rejeitar o que a primeira entrega, e ali ela recebeu três quase-acertos.

O que muda em português

O catálogo e os pedidos do experimento são em inglês. Duas consequências práticas para um agente que atende em português:

As descrições do catálogo provavelmente estão em inglês mesmo quando o pedido vem em português, porque skills são pacotes de terceiros. Isso mistura idiomas na mesma pergunta, e vale testar se o casamento por significado atravessa bem essa fronteira no seu catálogo.

As três perguntas de necessidade precisam de tradução cuidadosa, não literal. “Me ajuda a resolver isso aqui” é pedido de ação em português falado, sem verbo de ação explícito. Como a TypeSafe declara que o inglês é a língua principal de treino, e como sentido implícito foi onde vimos o modelo hesitar com texto brasileiro — no nosso teste de ironia a confiança caiu para 0,72 —, calibre a média de 0,30 com o seu próprio tráfego.

Onde isso quebra

• Catálogo muito maior. Um Choice acomoda 182 opções com folga, e o próprio cookbook de classificação por confiança sugere que a confiabilidade vai até cerca de 240. Acima disso, divida em blocos, ordene cada um e rode a etapa de lista curta sobre os vencedores.
• Skill ausente do catálogo. Nenhuma ordenação inventa o que não existe. O caso do Mastodon é a prova.
• Sugestão confiante e errada. É o efeito colateral medido. O texto que acompanha a sugestão precisa dizer que ela pode ser ignorada.
• Descrições ruins. A receita lê o que o catálogo escreveu. Se duas skills se descrevem igual, o problema está na fonte — e como escrever isso melhor é assunto de critérios que separam.

Quando a escolha é entre argumentos de uma função, e não entre ferramentas, veja function calling. O índice está em receitas.