5 Padrões de Design de Habilidades de Agentes 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 o mesmo layout, o problema de formatação está praticamente obsoleto.

O desafio agora é o design de conteúdo. A especificação explica como empacotar uma skill, mas não oferece nenhuma orientação sobre como estruturar a lógica dentro dela. Por exemplo, uma skill que encapsula convenções do FastAPI opera de maneira 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 skills 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:

• Tool Wrapper: Torne seu agente um especialista instantâneo em qualquer biblioteca
• Generator: Produza documentos estruturados a partir de um modelo reutilizável
• Reviewer: Pontue o código com base em uma lista de verificação por gravidade
• Inversion: O agente entrevista você antes de agir
• Pipeline: Imponha um fluxo de trabalho rigoroso de várias etapas com pontos de verificação

Padrão 1: O Tool Wrapper

Um Tool Wrapper fornece ao seu agente contexto sob demanda para uma biblioteca específica. Em vez de codificar as convenções da API no seu prompt de sistema, você as empacota em uma skill. 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. Este é o mecanismo exato que você usa para distribuir as diretrizes de codificação interna da sua equipe ou as melhores práticas específicas de framework diretamente nos fluxos de trabalho dos seus desenvolvedores.

Aqui está um exemplo de um Tool Wrapper 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ça 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 cada convenção exatamente
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 Generator

Enquanto o Tool Wrapper aplica conhecimento, o Generator impõe uma saída consistente. Se você luta com um agente gerando estruturas de documentos diferentes a cada execução, o Generator resolve isso orquestrando um processo de preenchimento de lacunas.

Ele aproveita dois diretórios opcionais: 𝚊𝚜𝚜𝚎𝚝𝚜/ armazena seu modelo de saída, e 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ armazena 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 sobre 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 skill 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 redigir 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 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 no modelo deve estar presente na saída.
22
23Passo 5: Retorne o relatório completo como um único documento Markdown.

Padrão 3: O Reviewer

O padrão Reviewer 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 pontua 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, você obtém uma auditoria especializada completamente diferente usando a mesma infraestrutura de skill. É uma forma altamente eficaz de automatizar revisões de PR ou detectar vulnerabilidades antes que um humano olhe para o código.

A seguinte skill 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 cuidado. 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 localização aproximada)
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 inerentemente querem adivinhar e gerar imediatamente. O padrão Inversion inverte essa dinâmica. Em vez do 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 coletar contexto primeiro. Ele faz perguntas estruturadas sequencialmente e espera 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 skill de planejador de projetos. O elemento crucial aqui é o faseamento estrito e o prompt explícito de controle de acesso 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", "me ajude 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- P1: "Qual problema este projeto resolve para seus usuários?"
17- P2: "Quem são os usuários principais? Qual é o nível técnico deles?"
18- P3: "Qual é a escala esperada? (usuários por dia, volume de dados, taxa de requisições)"
19
20## Fase 2 — Restrições Técnicas (somente após a Fase 1 ser totalmente respondida)
21
22- P4: "Qual ambiente de implantação você usará?"
23- P5: "Você tem algum requisito ou preferência de pilha tecnológica?"
24- P6: "Quais são os requisitos inegociá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 ter etapas puladas ou instruções ignoradas. 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 a definição do fluxo de trabalho. Ao implementar condições de portão 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 várias etapas. Use quando o usuário pedir para documentar um módulo, gerar documentação 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 — Análise e Inventário
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 o guia de estilo exatamente
19- Apresente cada docstring gerada para aprovação do usuário
20NÃO prossiga para a Etapa 3 até o usuário confirmar.
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 em relação a 'references/quality-checklist.md':
27- Cada símbolo público documentado
28- Cada 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 skill 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 skill Pipeline pode incluir uma etapa Reviewer no final para verificar seu próprio trabalho. Um Generator pode depender da Inversão no início para coletar 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 em tempo de 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 crie agentes confiáveis.

Comece hoje

A especificação Agent Skills é open-source e tem suporte nativo 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.