Skills pequenas ou uma Skill que sabe fazer tudo?

Depois de escrever algumas Skills, uma dúvida de design aparece quase sempre: vale mais a pena um conjunto de Skills pequenas e específicas, ou uma Skill abrangente que tenta cobrir um domínio inteiro de uma vez? Não existe resposta padrão, mas existe um jeito claro de pensar sobre o trade-off.

O que se ganha com Skills pequenas

Uma Skill estreita, cobrindo uma tarefa bem delimitada, tende a ter descrição mais precisa, e descrição precisa é justamente o que o agente usa para decidir se aquela Skill se aplica ao pedido atual. Quanto mais específica a combinação entre o que a Skill faz e quando ela deve ser usada, menor a chance de acionamento incorreto, de uma Skill ser chamada para uma tarefa que ela não cobre bem.

Skills pequenas também são mais fáceis de manter isoladamente. Corrigir ou atualizar uma delas não exige revisar um documento extenso tentando garantir que a mudança não quebrou uma seção completamente diferente do mesmo arquivo.

O que se perde com Skills pequenas demais

O outro lado da mesma escolha é o custo de manutenção agregado. Um domínio dividido em dez Skills muito estreitas significa dez arquivos de metadado competindo por espaço na etapa inicial de carregamento, dez descrições que precisam ser mantidas coerentes entre si para não se sobreporem de forma ambígua, e dez pontos de manutenção separados quando uma regra transversal ao domínio inteiro precisa mudar.

Existe também o risco de fragmentação artificial: dividir uma tarefa que naturalmente pertence junto só para manter cada arquivo pequeno, produzindo Skills que dependem umas das outras para fazer sentido completo, quando poderiam ser uma unidade só.

Por que uma Skill “que sabe fazer tudo” tende a falhar de outro jeito

Uma Skill abrangente, tentando cobrir um domínio inteiro de uma vez, sofre do problema oposto. A descrição precisa ser vaga o suficiente para caber tudo que a Skill promete cobrir, e descrição vaga enfraquece justamente o mecanismo de acionamento que deveria decidir quando ela se aplica. O corpo do arquivo cresce, aumentando o custo de contexto pago toda vez que a Skill inteira precisa ser carregada, mesmo quando só uma fração pequena dela é relevante para aquele pedido específico.

Existe uma diretriz prática recorrente em documentação de Skills: manter o corpo do SKILL.md dentro de um limite razoável de tamanho, e dividir em arquivos de referência quando esse limite é ultrapassado. Isso não resolve sozinho o problema de escopo amplo demais, mas indica que até quem projeta o formato reconhece o custo de deixar uma única Skill crescer sem limite.

Um critério prático para decidir o corte

Um jeito razoável de decidir onde cortar é perguntar se a Skill continua descritível numa frase clara de “o que faz e quando usar”, sem depender de “e também” repetido várias vezes. Quando a descrição começa a acumular ressalvas e exceções para caber tudo que a Skill cobre, é sinal de que ela cresceu além do que uma descrição única consegue comunicar com precisão para o mecanismo de acionamento.

Outro sinal prático aparece durante o uso real: se a mesma Skill é acionada com frequência para pedidos que só usam uma fração pequena das instruções nela contidas, provavelmente ela cobre mais território do que deveria estar junto num único arquivo.

Granularidade é decisão de manutenção, não só de design

No fim, a escolha entre Skills pequenas e uma Skill abrangente não é sobre qual abordagem é tecnicamente superior, é sobre que tipo de custo de manutenção faz mais sentido assumir: muitos arquivos pequenos e coordenação entre eles, ou poucos arquivos grandes e o risco de descrição imprecisa demais para acionamento confiável. Observar como a Skill de fato se comporta em uso real tende a revelar qual dos dois custos está pesando mais naquele caso específico.