Guia prático para construir agentes ADK com Skills e progressive disclosure

Quando a gente fala em agente de IA bem feito, não basta ele só seguir instrução. Um bom agente precisa conseguir carregar conhecimento sob demanda e, em alguns casos, até criar novas instruções sozinho. É exatamente aqui que entra o Agent Development Kit (ADK) do Google e o seu SkillToolset.

Em vez de tentar jogar todo o conhecimento no system prompt, o ADK trabalha com o conceito de Skills: blocos de especialização que o agente pode listar, carregar e combinar de forma dinâmica. Com a configuração certa, o próprio agente consegue gerar uma nova Skill em tempo de execução, salvar o conteúdo e começar a usar esse novo conhecimento em seguida.

O fluxo fica simples:

• gerar a Skill;
• carregar a Skill;
• usar a Skill na tarefa do usuário.

Tanto faz se você quer um checklist de segurança, uma rotina de auditoria de compliance ou um validador de pipeline de dados: a arquitetura é a mesma. A diferença está só no tipo de instrução que você embala dentro de cada Skill.

O problema dos prompts monolíticos

Muita gente ainda constrói agente com um único prompt gigante. Junta tudo em um bloco só: regras de compliance, guias de estilo, documentação de API, manual de troubleshooting, padrões de código, políticas internas e por aí vai.

Isso até quebra um galho quando o agente tem duas ou três funções bem simples. Só que, na hora que você começa a escalar para dez, quinze ou vinte tarefas diferentes, esse modelo desanda. Cada chamada para o LLM passa a carregar milhares de tokens de instrução, mesmo quando o usuário faz uma pergunta trivial que não depende de 90% daquele contexto.

A especificação Agent Skills resolve isso com um padrão de arquitetura chamado progressive disclosure. Em vez de despejar tudo de uma vez, ela divide o carregamento de conhecimento em três níveis bem definidos:

• L1 – Metadata (~100 tokens por Skill)
  Nome e descrição da Skill. Esse nível é carregado na inicialização, para todas as Skills. Funciona como um cardápio que o agente consulta para decidir o que é relevante para cada pedido do usuário.
• L2 – Instructions (< 5.000 tokens)
  Corpo completo da Skill, com passos detalhados e fluxo de trabalho. Só é carregado quando o agente ativa explicitamente aquela Skill.
• L3 – Resources (sob demanda)
  Arquivos externos: guias de estilo, especificações de API, anexos de referência, exemplos extensos. Só entram no contexto quando a própria Skill pede, via ferramenta de carregamento de recurso.

Na prática, um agente com 10 Skills deixa de carregar algo na casa de 10.000 tokens em um super prompt e passa a trabalhar com cerca de 1.000 tokens de metadata de L1 na largada, chamando L2 e L3 só quando precisa. Isso representa algo próximo de 90% de redução de contexto base por chamada para o LLM.

No ADK, esse padrão é implementado pela classe SkillToolset, que gera automaticamente três ferramentas alinhadas com esses níveis:

• list_skills – L1, lista de Skills disponíveis;
• load_skill – L2, carrega o corpo da Skill;
• load_skill_resource – L3, carrega recursos externos da Skill.

Pattern 1: Inline skills (o post-it colado no código)

O primeiro padrão é o mais simples: uma Skill definida direto no código Python, em forma de objeto, com name, description e instructions. Serve bem para regras pequenas, estáveis e que quase não mudam.

Um exemplo clássico é uma Skill de checklist de SEO para revisar posts de blog:

seo_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="seo-checklist",
        description="SEO optimization checklist for blog posts. Covers title tags, meta descriptions, heading structure, and readability.",
    ),
    instructions=(
        "When optimizing a blog post for SEO, check each item:\n"
        "1. Title: 50-60 chars, primary keyword near the start\n"
        "2. Meta description: 150-160 chars, includes a call-to-action\n"
        "3. Headings: H2/H3 hierarchy, keywords in 2-3 headings\n"
        "4. First paragraph: Primary keyword in first 100 words\n"
        "5. Images: Alt text with keywords, compressed, descriptive names\n"
        "Review the content against each item and suggest improvements."
    ),
)

Nesse formato:

• o frontmatter (nome e descrição) vira L1, sempre visível como parte da lista de Skills;
• as instructions viram L2, carregadas só quando o agente decide que precisa dessa Skill.

Se o usuário disser algo como Revise meu post de blog para SEO, o agente consulta o L1, identifica que a Skill seo-checklist é relevante, chama load_skill e passa a aplicar o checklist passo a passo no conteúdo recebido.

Pattern 2: File-based skills (a pasta de referência organizada)

Inline skill resolve muito, mas começa a ficar limitada quando aquela competência precisa de documentação de apoio: guias extensos, specs de API, playbooks internos, etc. Nesse cenário, entra o segundo padrão: a Skill baseada em arquivos.

Cada Skill fica em seu próprio diretório, com um arquivo central SKILL.md e subpastas opcionais para referências, assets ou scripts. A estrutura mínima é assim:

skills/blog-writer/
├── SKILL.md           # L2: Instructions
└── references/
    └── style-guide.md # L3: Loaded on demand

O SKILL.md começa com frontmatter em YAML, seguido do corpo em Markdown com as instruções detalhadas. Já os arquivos dentro de references/ trazem o conhecimento denso, como guias de estilo completos ou especificações longas.

A Skill é carregada pelo ADK de forma bem direta:

blog_writer_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "blog-writer"
)

Quando o agente ativa essa Skill, ele puxa o L2 a partir do SKILL.md. Se, dentro das instruções, houver um passo dizendo para ler o guia de estilo, o agente vai chamar load_skill_resource e buscar o arquivo references/style-guide.md apenas naquele momento.

Essa separação é poderosa por dois motivos:

• deixa o L2 mais enxuto e objetivo, com foco no fluxo de ações;
• tira documentos enormes do prompt principal, colocando-os atrás de L3, acessados sob demanda.

Como bônus, qualquer agente compatível com a especificação agentskills.io consegue consumir a mesma pasta. Você escreve uma vez, reaproveita em vários agentes.

Pattern 3: External skills (o import de repositórios de comunidade)

O terceiro padrão é basicamente a evolução natural do anterior. A arquitetura é a mesma de uma Skill baseada em arquivos, só que, em vez de você escrever o SKILL.md do zero, você baixa uma Skill pronta de um repositório externo.

Um exemplo são coleções como o repositório awesome-claude-skills. Você copia a Skill que te interessa para o diretório do seu projeto e carrega com a mesma chamada:

content_researcher_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "content-research-writer"
)

Para o ADK, não faz diferença se quem escreveu o SKILL.md foi você ou a comunidade. A especificação Agent Skills define um formato de diretório universal. Se a pasta segue esse formato, a função load_skill_from_dir simplesmente funciona.

O próprio Google publica Skills oficiais de desenvolvimento para ADK no mesmo padrão, instaláveis via linha de comando, por exemplo com:

npx skills add google/adk-docs -y -g

Com isso, você consegue combinar:

• Skills que você mesmo escreveu;
• Skills internas da sua empresa;
• Skills abertas da comunidade e do Google.

Os três primeiros patterns cobrem tudo o que já existe: o que você cria, o que você importa de arquivo e o que você baixa de terceiros. Falta um passo: deixar o agente criar as próprias Skills.

Pattern 4: Meta skill (a fábrica de Skills em tempo de execução)

O quarto padrão fecha o ciclo. Aqui, você cria uma meta skill: uma Skill cujo objetivo é gerar novas Skills, escrevendo arquivos SKILL.md completos a partir de requisitos em linguagem natural.

Com isso, o agente se torna autoextensível. Quando surge uma necessidade que nenhuma Skill existente cobre bem, o próprio agente consegue ler a especificação, gerar uma nova Skill compatível com o ADK e usar esse novo recurso imediatamente.

Essa meta skill costuma ser definida como uma Inline Skill, mas com um diferencial: ela vem com um conjunto de resources em L3, incluindo:

• o texto da especificação oficial do agentskills.io;
• um exemplo de Skill bem formada, que serve de modelo.

Fica mais ou menos assim:

skill_creator = models.Skill(
    frontmatter=models.Frontmatter(
        name="skill-creator",
        description=(
            "Creates new ADK-compatible skill definitions from requirements."
            " Generates complete SKILL.md files following the Agent Skills"
            " specification at agentskills.io."
        ),
    ),
    instructions=(
        "When asked to create a new skill, generate a complete SKILL.md file.\n\n"
        "Read `references/skill-spec.md` for the format specification.\n"
        "Read `references/example-skill.md` for a working example.\n\n"
        "Follow these rules:\n"
        "1. Name must be kebab-case, max 64 characters\n"
        "2. Description must be under 1024 characters\n"
        "3. Instructions should be clear, step-by-step\n"
        "4. Reference files in references/ for detailed domain knowledge\n"
        "5. Keep SKILL.md under 500 lines, put details in references/\n"
        "6. Output the complete file content the user can save directly\n"
    ),
    resources=models.Resources(
        references={
            "skill-spec.md": "# Agent Skills Specification (agentskills.io)...",
            "example-skill.md": "# Example: Code Review Skill...",
        }
    ),
)

O campo resources usa models.Resources para embutir a especificação e um exemplo funcional como arquivos lógicos de L3. Quando o agente chama load_skill_resource("skill-creator", "references/skill-spec.md"), ele recebe o conteúdo completo da spec e passa a segui-la para gerar o novo SKILL.md.

Boa prática importante: por mais tentador que seja automatizar tudo, vale manter alguém revisando as Skills geradas. Trate cada SKILL.md novo como se fosse uma dependência de código: revise, teste e só então coloque em produção. O próprio ADK oferece mecanismos de avaliação para validar o comportamento das Skills antes de liberar geral.

A fábrica de Skills em ação

Imagina o seguinte pedido: o usuário diz:

Preciso de uma Skill para revisar código Python em busca de vulnerabilidades de segurança.

O agente ativa a skill-creator, lê os recursos de L3 com a spec e o exemplo, e gera um SKILL.md completo, com:

• nome em kebab-case válido;
• instruções organizadas por tipo de risco (validação de entrada, autenticação, criptografia etc.);
• formato de saída baseado em severidade (baixa, média, alta).

Essa nova Skill segue a mesma especificação do agentskills.io. Resultado: ela não funciona só no ADK, mas também em qualquer outro agente compatível com o formato, como:

• Gemini CLI;
• Claude Code;
• Cursor;
• e dezenas de outras ferramentas que já adotaram o padrão.

Conectando tudo com o SkillToolset

Depois de definir as Skills (inline, baseadas em arquivo, externas e a meta skill), o último passo é empacotar tudo em um SkillToolset e entregar para o agente.

skill_toolset = SkillToolset(
    skills=[seo_skill, blog_writer_skill, content_researcher_skill, skill_creator]
)

root_agent = Agent(
    model="gemini-2.5-flash",
    name="blog_skills_agent",
    description="A blog-writing agent powered by reusable skills.",
    instruction=(
        "You are a blog-writing assistant with specialized skills.\n"
        "Load relevant skills to get detailed instructions.\n"
        "Use load_skill_resource to access reference materials.\n"
        "Follow each skill's step-by-step instructions.\n"
        "Always explain which skill you're using and why."
    ),
    tools=[skill_toolset],
)

Nesse exemplo:

• seo_skill cuida do checklist de SEO;
• blog_writer_skill define como estruturar o texto;
• content_researcher_skill faz a parte de pesquisa de conteúdo;
• skill_creator é a fábrica, pronta para criar novas Skills sob demanda.

Se o usuário pedir algo como Crie uma Skill para escrever introduções técnicas de blog, o agente usa a meta skill, gera um novo SKILL.md e responde com o conteúdo pronto para ser salvo em skills/blog-intro-writer/SKILL.md. Na próxima sessão, você consegue carregar esse diretório com load_skill_from_dir e tratar essa Skill como qualquer outra.

Por baixo dos panos, o SkillToolset segue o mesmo modelo de progressive disclosure, gerando automaticamente:

• list_skills – L1, sempre injetado;
• load_skill – L2, chamado quando necessário;
• load_skill_resource – L3, para referências específicas.

Dicas finais para projetar Skills úteis

• Capriche na descrição
  O campo description é, na prática, a documentação de API que o LLM enxerga em L1. Textos como SEO optimization checklist for blog posts ajudam o agente a entender quando ativar a Skill. Já descrições vagas deixam o modelo perdido.
• Comece inline, evolua para arquivos quando fizer sentido
  Não precisa criar diretório e spec completa para tudo. Se a Skill cabe em poucas linhas e não exige referência externa, mantenha inline. Migre para o formato baseado em arquivo quando aparecer necessidade de reaproveitar em vários agentes ou incluir documentação maior em L3.
• Trate Skills geradas como código em produção
  O que a meta skill gera é, na prática, parte do comportamento do seu agente. Vale revisar, validar em cenários reais e, se possível, criar testes automatizados com as ferramentas de avaliação do ADK antes de colocar em rota crítica.

No fim, a jogada do ADK com Skills e SkillToolset é simples: em vez de um prompt gigante e difícil de manter, você ganha um conjunto de blocos de conhecimento modulares, carregados sob demanda, que podem ser escritos por você, pela comunidade ou pelo próprio agente em tempo de execução. Menos tokens, mais controle e uma arquitetura de agentes bem mais próxima das boas práticas de engenharia de software.