Agent Skills chega ao Genkit Go: expertise sob demanda sem estourar o contexto

Quando um agente de LLM cresce em responsabilidades, o gerenciamento do contexto vira gargalo. Despejar todo procedimento operacional, guia de referência e documento numa janela de contexto persistente não escala: consome tokens caros, dilui o foco do modelo e aumenta a chance de resposta errada. É esse problema que o Agent Skills ataca, agora com suporte oficial no Genkit Go, conforme anunciado no Google Developers Blog por Daniela Petruzalek.

O princípio: progressive disclosure

A mecânica central é a revelação progressiva. Em vez de carregar tudo de uma vez, o agente só recebe a informação completa quando ela é necessária. Cada skill é um pacote de arquivos markdown organizado em disco, com um arquivo SKILL.md na raiz e diretórios opcionais para scripts/, references/ e assets/.

O SKILL.md tem duas partes: um frontmatter (com name, description e metadados) e o body (as instruções de fato). O truque é que, inicialmente, o harness do agente só injeta o frontmatter no system prompt. É o suficiente para o modelo decidir se aquela skill é relevante para a tarefa atual. Só quando a conversa chega num ponto em que a skill faz sentido é que o corpo completo é carregado, e a partir dele o agente pode ainda puxar referências extras ou executar scripts empacotados.

Na prática, isso rende três ganhos concretos, segundo o texto: eficiência de tokens (metadados primeiro, instruções detalhadas só na ativação), implementação enxuta (skills são markdown distribuído como código, sem infraestrutura extra) e empacotamento de recursos (a skill carrega seus próprios scripts em Python, Node.js ou Bash).

Como funciona no Genkit Go

O suporte se apoia na arquitetura de middleware do Genkit, um pipeline de hooks que envolve fases do ciclo de vida do modelo (WrapModel, WrapTool, WrapGenerate). O middleware de Skills monitora os prompts de entrada, casa descrições e ativa skills dinamicamente.

O ciclo tem três estágios: descoberta (o sistema varre os SkillPaths procurando SKILL.md e injeta os metadados no system prompt), ativação (quando o pedido bate com a descrição de uma skill, o Genkit chama a tool use_skill) e execução (o conteúdo completo, mais os recursos empacotados, entra no contexto ativo).

Adicionar skills a um flow é direto. Depois de go get github.com/firebase/genkit/go, basta registrar o middleware via a opção funcional ai.WithUse:

resp, err := genkit.Generate(ctx, g,
  ai.WithPrompt("How do I run tests in this repo?"),
  ai.WithUse(&middleware.Skills{SkillPaths: []string{"./skills"}}),
)

No exemplo introdutório da fonte, uma CLI de receitas mapeia ./skills com duas capacidades (banana-bread e cheese-bread). Rodar go run main.go cheese ativa a skill de pão de queijo e devolve a receita formatada em ASCII para o terminal. Vale a ressalva da própria autora sobre o output: a receita foi gerada pelo Gemini e, por mais que o instinto brasileiro dela diga que está correta, o teste fica por conta e risco de quem for à cozinha.

Um caso menos trivial

O exemplo que mostra o potencial real é uma aplicação multimodal de restauração de arte, construída com Genkit Go e o Gemini 3.1 Flash Image (Nano Banana 2). Ela carrega três skills, uma para cada estilo (drawings, paintings e photography), cada um com seu protocolo próprio de restauração.

O SKILL.md de paintings, por exemplo, define mandatos de conservação bem específicos: fidelidade absoluta (proibido adicionar novos elementos), anti-modernização (preservar pinceladas originais) e respeito ao craquelê como parte da história da obra. Ao receber uma imagem, o system prompt instrui o modelo a primeiro classificar o tipo de imagem e só então invocar a skill correspondente.

O teste usa a icônica "Ecce Homo" de Elías García Martínez, célebre pela restauração amadora que virou meme. O agente identificou corretamente a obra como pintura, ativou a skill paintings e reportou no output textual exatamente quais técnicas aplicou e qual skill usou.

Por que isso importa para quem constrói

Para devs backend no Brasil que já vêm adotando o Genkit, o Agent Skills resolve uma dor prática de arquitetura: separar conhecimento especializado da lógica do agente, versionando skills como qualquer outro artefato de código. É um padrão comum às quatro linguagens suportadas, o que facilita padronizar entre times poliglotas.

O trade-off honesto: a ativação depende do matching entre o pedido e a description da skill, ou seja, escrever boas descrições vira parte crítica do design. E, como a própria fonte lembra, a natureza não determinística dos LLMs significa que pode levar algumas tentativas até obter um bom resultado. O código completo dos exemplos está disponível a partir do post original.

Fonte: Google Developers Blog