5 Padrões de Design de Habilidades de Agente que todo Desenvolvedor ADK deve conhecer

Quando se trata de 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍, os desenvolvedores tendem a se concentrar no formato — acertar o YAML, estruturar diretórios e seguir a especificação. Mas com mais de 30 ferramentas de agente (como Claude Code, Gemini CLI e Cursor) padronizando no mesmo layout, o problema de formatação está praticamente obsoleto.

O desafio agora é o design do conteúdo. A especificação explica como empacotar uma habilidade, mas não oferece nenhuma orientação sobre como estruturar a lógica dentro dela. Por exemplo, uma habilidade que envolve convenções do FastAPI opera de forma completamente diferente de um pipeline de documentação de quatro etapas, mesmo que seus arquivos 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 pareçam idênticos por fora.

Ao estudar como as habilidades são construídas em todo o ecossistema — desde os repositórios da Anthropic até as diretrizes internas da Vercel e do Google — existem cinco padrões de design recorrentes que podem ajudar os desenvolvedores a construir agentes.

Por @Saboo_Shubham_ e @lavinigam

Este artigo aborda cada um deles com código ADK funcional:

• Wrapper de Ferramenta: Torne seu agente um especialista instantâneo em qualquer biblioteca
• Gerador: Produza documentos estruturados a partir de um modelo reutilizável
• Revisor: Avalie o código contra uma lista de verificação por gravidade
• Inversão: O agente entrevista você antes de agir
• Pipeline: Imponha um fluxo de trabalho multi-etapas rigoroso com pontos de verificação

Padrão 1: O Wrapper de Ferramenta

Um Wrapper de Ferramenta fornece ao seu agente contexto sob demanda para uma biblioteca específica. Em vez de codificar convenções de API no seu prompt de sistema, você as empacota em uma habilidade. Seu agente só carrega esse contexto quando realmente trabalha com essa tecnologia.

É o padrão mais simples de implementar. O arquivo 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 escuta palavras-chave específicas da biblioteca no prompt do usuário, carrega dinamicamente sua documentação interna do diretório 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ e aplica essas regras como verdade absoluta. Esse é o mecanismo exato que você usa para distribuir as diretrizes de codificação internas da sua equipe ou as melhores práticas específicas de um framework diretamente nos fluxos de trabalho dos seus desenvolvedores.

Aqui está um exemplo de um Wrapper de Ferramenta que ensina um agente a escrever código FastAPI. Observe como as instruções dizem explicitamente ao agente para carregar o arquivo 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 somente quando ele começar a revisar ou escrever código:

1# skills/api-expert/SKILL.md
2---
3name: api-expert
4description: Melhores práticas e convenções de desenvolvimento FastAPI. Use ao construir, revisar ou depurar aplicações FastAPI, APIs REST ou modelos Pydantic.
5metadata:
6  pattern: tool-wrapper
7  domain: fastapi
8---
9
10Você é um especialista em desenvolvimento FastAPI. Aplique estas convenções ao código ou pergunta do usuário.
11
12## Convenções Principais
13
14Carregue 'references/conventions.md' para a lista completa de melhores práticas do FastAPI.
15
16## Ao Revisar Código
171. Carregue a referência de convenções
182. Verifique o código do usuário em relação a cada convenção
193. Para cada violação, cite a regra específica e sugira a correção
20
21## Ao Escrever Código
221. Carregue a referência de convenções
232. Siga exatamente cada convenção
243. Adicione anotações de tipo a todas as assinaturas de função
254. Use o estilo Annotated para injeção de dependência

Padrão 2: O Gerador

Enquanto o Wrapper de Ferramenta aplica conhecimento, o Gerador impõe uma saída consistente. Se você luta para que um agente gere estruturas de documento diferentes a cada execução, o Gerador resolve isso orquestrando um processo de preencher lacunas.

Ele aproveita dois diretórios opcionais: 𝚊𝚜𝚜𝚎𝚝𝚜/ contém seu modelo de saída, e 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ contém seu guia de estilo. As instruções atuam como um gerente de projeto. Elas dizem ao agente para carregar o modelo, ler o guia de estilo, perguntar ao usuário pelas variáveis ausentes e preencher o documento. Isso é prático para gerar documentação de API previsível, padronizar mensagens de commit ou estruturar arquiteturas de projeto.

Neste exemplo de gerador de relatório técnico, o arquivo de habilidade não contém o layout real ou as regras gramaticais. Ele simplesmente coordena a recuperação desses ativos e força o agente a executá-los passo a passo:

1# skills/report-generator/SKILL.md
2---
3name: report-generator
4description: Gera relatórios técnicos estruturados em Markdown. Use quando o usuário pedir para escrever, criar ou rascunhar um relatório, resumo ou documento de análise.
5metadata:
6  pattern: generator
7  output-format: markdown
8---
9
10Você é um gerador de relatórios técnicos. Siga estes passos exatamente:
11
12Passo 1: Carregue 'references/style-guide.md' para regras de tom e formatação.
13
14Passo 2: Carregue 'assets/report-template.md' para a estrutura de saída necessária.
15
16Passo 3: Pergunte ao usuário por qualquer informação ausente necessária para preencher o modelo:
17- Tópico ou assunto
18- Principais descobertas ou pontos de dados
19- Público-alvo (técnico, executivo, geral)
20
21Passo 4: Preencha o modelo seguindo as regras do guia de estilo. Cada seção do modelo deve estar presente na saída.
22
23Passo 5: Retorne o relatório completo como um único documento Markdown.

Padrão 3: O Revisor

O padrão Revisor separa o que verificar de como verificar. Em vez de escrever um longo prompt de sistema detalhando cada cheiro de código, você armazena uma rubrica modular dentro de um arquivo 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍.

Quando um usuário envia código, o agente carrega esta lista de verificação e avalia metodicamente a submissão, agrupando suas descobertas por gravidade. Se você trocar uma lista de verificação de estilo Python por uma lista de verificação de segurança OWASP, obterá uma auditoria completamente diferente e especializada usando a mesma infraestrutura de habilidade. É uma forma altamente eficaz de automatizar revisões de PR ou detectar vulnerabilidades antes que um humano olhe para o código.

A seguinte habilidade de revisor de código demonstra essa separação. As instruções permanecem estáticas, mas o agente carrega dinamicamente os critérios de revisão específicos de uma lista de verificação externa e força uma saída estruturada baseada em gravidade:

1# skills/code-reviewer/SKILL.md
2---
3name: code-reviewer
4description: Revisa código Python quanto à qualidade, estilo e bugs comuns. Use quando o usuário enviar código para revisão, pedir feedback sobre seu código ou quiser uma auditoria de código.
5metadata:
6  pattern: reviewer
7  severity-levels: error,warning,info
8---
9
10Você é um revisor de código Python. Siga este protocolo de revisão exatamente:
11
12Passo 1: Carregue 'references/review-checklist.md' para os critérios de revisão completos.
13
14Passo 2: Leia o código do usuário com atenção. Entenda seu propósito antes de criticar.
15
16Passo 3: Aplique cada regra da lista de verificação ao código. Para cada violação encontrada:
17- Anote o número da linha (ou local aproximado)
18- Classifique a gravidade: error (deve corrigir), warning (deveria corrigir), info (considere)
19- Explique POR QUE é um problema, não apenas O QUE está errado
20- Sugira uma correção específica com código corrigido
21
22Passo 4: Produza uma revisão estruturada com estas seções:
23- **Resumo**: O que o código faz, avaliação geral de qualidade
24- **Descobertas**: Agrupadas por gravidade (erros primeiro, depois avisos, depois informações)
25- **Pontuação**: Avalie de 1 a 10 com breve justificativa
26- **Top 3 Recomendações**: As melhorias de maior impacto

Padrão 4: Inversão

Os agentes tendem a querer adivinhar e gerar imediatamente. O padrão Inversão inverte essa dinâmica. Em vez de o usuário conduzir o prompt e o agente executar, o agente atua como um entrevistador.

A Inversão depende de instruções de bloqueio explícitas e não negociáveis (como "NÃO comece a construir até que todas as fases estejam completas") para forçar o agente a reunir contexto primeiro. Ele faz perguntas estruturadas sequencialmente e aguarda suas respostas antes de passar para a próxima fase. O agente se recusa a sintetizar uma saída final até ter uma imagem completa dos seus requisitos e restrições de implantação.

Para ver isso em ação, veja esta habilidade de planejador de projeto. O elemento crucial aqui é o faseamento estrito e o prompt de bloqueio explícito que impede o agente de sintetizar o plano final até que todas as respostas do usuário sejam coletadas:

1# skills/project-planner/SKILL.md
2---
3name: project-planner
4description: Planeja um novo projeto de software coletando requisitos através de perguntas estruturadas antes de produzir um plano. Use quando o usuário disser "quero construir", "ajude-me a planejar", "projete um sistema" ou "inicie um novo projeto".
5metadata:
6  pattern: inversion
7  interaction: multi-turn
8---
9
10Você está conduzindo uma entrevista estruturada de requisitos. NÃO comece a construir ou projetar até que todas as fases estejam completas.
11
12## Fase 1 — Descoberta do Problema (faça uma pergunta de cada vez, aguarde cada resposta)
13
14Faça estas perguntas em ordem. Não pule nenhuma.
15
16- Q1: "Que problema este projeto resolve para seus usuários?"
17- Q2: "Quem são os usuários principais? Qual é o nível técnico deles?"
18- Q3: "Qual é a escala esperada? (usuários por dia, volume de dados, taxa de solicitações)"
19
20## Fase 2 — Restrições Técnicas (somente após a Fase 1 ser totalmente respondida)
21
22- Q4: "Qual ambiente de implantação você usará?"
23- Q5: "Você tem requisitos ou preferências de stack tecnológico?"
24- Q6: "Quais são os requisitos não negociáveis? (latência, tempo de atividade, conformidade, orçamento)"
25
26## Fase 3 — Síntese (somente após todas as perguntas serem respondidas)
27
281. Carregue 'assets/plan-template.md' para o formato de saída
292. Preencha cada seção do modelo usando os requisitos coletados
303. Apresente o plano completo ao usuário
314. Pergunte: "Este plano captura com precisão seus requisitos? O que você mudaria?"
325. Itere com base no feedback até o usuário confirmar

Padrão 5: O Pipeline

Para tarefas complexas, você não pode se dar ao luxo de pular etapas ou ignorar instruções. O padrão Pipeline impõe um fluxo de trabalho sequencial estrito com pontos de verificação rígidos.

As próprias instruções servem como definição do fluxo de trabalho. Ao implementar condições de portão de diamante explícitas (como exigir aprovação do usuário antes de passar da geração de docstrings para a montagem final), o Pipeline garante que um agente não possa ignorar uma tarefa complexa e apresentar um resultado final não validado.

Este padrão utiliza todos os diretórios opcionais, puxando diferentes arquivos de referência e modelos apenas na etapa específica onde são necessários, mantendo a janela de contexto limpa.

Neste exemplo de pipeline de documentação, observe as condições de portão explícitas. O agente está explicitamente proibido de passar para a fase de montagem até que o usuário confirme as docstrings geradas na etapa anterior:

1# skills/doc-pipeline/SKILL.md
2---
3name: doc-pipeline
4description: Gera documentação de API a partir de código-fonte Python através de um pipeline de múltiplas etapas. Use quando o usuário pedir para documentar um módulo, gerar docs de API ou criar documentação a partir de código.
5metadata:
6  pattern: pipeline
7  steps: "4"
8---
9
10Você está executando um pipeline de geração de documentação. Execute cada etapa em ordem. NÃO pule etapas nem prossiga se uma etapa falhar.
11
12## Etapa 1 — Analisar e Inventariar
13Analise o código Python do usuário para extrair todas as classes, funções e constantes públicas. Apresente o inventário como uma lista de verificação. Pergunte: "Esta é a API pública completa que você deseja documentar?"
14
15## Etapa 2 — Gerar Docstrings
16Para cada função sem docstring:
17- Carregue 'references/docstring-style.md' para o formato necessário
18- Gere uma docstring seguindo exatamente o guia de estilo
19- Apresente cada docstring gerada para aprovação do usuário
20Não prossiga para a Etapa 3 até que o usuário confirme.
21
22## Etapa 3 — Montar Documentação
23Carregue 'assets/api-doc-template.md' para a estrutura de saída. Compile todas as classes, funções e docstrings em um único documento de referência de API.
24
25## Etapa 4 — Verificação de Qualidade
26Revise contra 'references/quality-checklist.md':
27- Todo símbolo público documentado
28- Todo parâmetro tem um tipo e descrição
29- Pelo menos um exemplo de uso por função
30Relate os resultados. Corrija problemas antes de apresentar o documento final.

Escolhendo o padrão de habilidade de agente certo

Cada padrão responde a uma pergunta diferente. Use esta árvore de decisão para encontrar o padrão certo para o seu caso de uso:

E, finalmente, os padrões se compõem

Esses padrões não são mutuamente exclusivos. Eles se compõem.

Uma habilidade Pipeline pode incluir uma etapa Revisor no final para verificar seu próprio trabalho. Um Gerador pode contar com Inversão logo no início para reunir as variáveis necessárias antes de preencher seu modelo. Graças ao 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 do ADK e à divulgação progressiva, seu agente só gasta tokens de contexto nos padrões exatos de que precisa no momento da execução.

Pare de tentar enfiar instruções complexas e frágeis em um único prompt de sistema. Divida seus fluxos de trabalho, aplique o padrão estrutural correto e construa agentes confiáveis.

Comece hoje mesmo

A especificação Agent Skills é open-source e suportada nativamente em todo o ADK. Você já sabe como empacotar o formato. Agora você sabe como projetar o conteúdo. Vá construir agentes mais inteligentes com o Google Agent Development Kit.