Five Core Design Patterns for Building Robust AI Agents with Google ADK

Google's Agent Development Kit (ADK) standardizes AI agent skills using SKILL.md files, which describe behavior, metadata, and execution patterns. The kit enables reusable, composable, and shareable skills.

ADK Overview

ADK provides a specification and tooling for building structured, maintainable agent skill sets. Skills are defined in SKILL.md, which includes name, description, metadata (e.g., pattern, domain), and step‑by‑step instructions. Official documentation: https://google.github.io/adk-docs/.

Design Challenge

While the SKILL.md format is fixed, guidance on internal logic varies. Analysis of many community and internal repositories identified five recurring architectural patterns for skill design.

Pattern 1: Tool Wrapper

Encapsulates a specific library’s conventions and loads them only when the agent needs that technology, reducing token usage.

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models.
metadata:
  pattern: tool-wrapper
  domain: fastapi
---
You are an expert in FastAPI development. Apply these conventions to the user's code or question.

## Core Conventions
Load 'references/conventions.md' for the complete list of FastAPI best practices.

## When Reviewing Code
1. Load the conventions reference
2. Check the user's code against each convention
3. For each violation, cite the specific rule and suggest the fix

## When Writing Code
1. Load the conventions reference
2. Follow every convention exactly
3. Add type annotations to all function signatures
4. Use Annotated style for dependency injection

Pattern 2: Generator

Orchestrates a fill‑in‑the‑blank process using external template and style assets to produce consistent, structured output such as reports or API documentation.

# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document.
metadata:
  pattern: generator
  output-format: markdown
---
You are a technical report generator. Follow these steps exactly:

Step 1: Load 'references/style-guide.md' for tone and formatting rules.
Step 2: Load 'assets/report-template.md' for the required output structure.
Step 3: Ask the user for any missing information needed to fill the template:
- Topic or subject
- Key findings or data points
- Target audience (technical, executive, general)
Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output.
Step 5: Return the completed report as a single Markdown document.

Pattern 3: Reviewer

Separates "what to check" from "how to check" by loading an external checklist at runtime, enabling flexible audits (e.g., Python style, OWASP security).

# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs. Use when the user submits code for review, asks for feedback, or wants a code audit.
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---
You are a Python code reviewer. Follow this review protocol exactly:

Step 1: Load 'references/review-checklist.md' for the complete review criteria.
Step 2: Read the user's code carefully. Understand its purpose before critiquing.
Step 3: Apply each rule from the checklist to the code. For every violation found:
- Note the line number (or approximate location)
- Classify severity: error (must fix), warning (should fix), info (consider)
- Explain WHY it's a problem, not just WHAT is wrong
- Suggest a specific fix with corrected code
Step 4: Produce a structured review with these sections:
- Summary: What the code does, overall quality assessment
- Findings: Grouped by severity (errors first, then warnings, then info)
- Score: Rate 1-10 with brief justification
- Top 3 Recommendations: The most impactful improvements

Pattern 4: Inversion

The agent acts as an interviewer, gathering requirements through a multi‑turn structured questionnaire before any generation occurs.

# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions before producing a plan. Use when the user says "I want to build", "help me plan", "design a system", or "start a new project".
metadata:
  pattern: inversion
  interaction: multi-turn
---
You are conducting a structured requirements interview. DO NOT start building or designing until all phases are complete.

## Phase 1 — Problem Discovery (ask one question at a time, wait for each answer)
- Q1: "What problem does this project solve for its users?"
- Q2: "Who are the primary users? What is their technical level?"
- Q3: "What is the expected scale? (users per day, data volume, request rate)"

## Phase 2 — Technical Constraints (only after Phase 1 is fully answered)
- Q4: "What deployment environment will you use?"
- Q5: "Do you have any technology stack requirements or preferences?"
- Q6: "What are the non‑negotiable requirements? (latency, uptime, compliance, budget)"

## Phase 3 — Synthesis (only after all questions are answered)
1. Load 'assets/plan-template.md' for the output format
2. Fill in every section of the template using the gathered requirements
3. Present the completed plan to the user
4. Ask: "Does this plan accurately capture your requirements? What would you change?"
5. Iterate on feedback until the user confirms

Pattern 5: Pipeline

Enforces a strict sequential workflow with hard checkpoints, preventing the agent from skipping steps or proceeding on incomplete data. Ideal for complex, multi‑stage tasks such as documentation generation.

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline. Use when the user asks to document a module, generate API docs, or create documentation from code.
metadata:
  pattern: pipeline
  steps: "4"
---
You are running a documentation generation pipeline. Execute each step in order. Do NOT skip steps or proceed if a step fails.

## Step 1 — Parse & Inventory
Analyze the user's Python code to extract all public classes, functions, and constants. Present the inventory as a checklist. Ask: "Is this the complete public API you want documented?"

## Step 2 — Generate Docstrings
For each function lacking a docstring:
- Load 'references/docstring-style.md' for the required format
- Generate a docstring following the style guide exactly
- Present each generated docstring for user approval
Do NOT proceed to Step 3 until the user confirms.

## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md' for the output structure. Compile all classes, functions, and docstrings into a single API reference document.

## Step 4 — Quality Check
Review against 'references/quality-checklist.md':
- Every public symbol documented
- Every parameter has a type and description
- At least one usage example per function
Report results. Fix issues before presenting the final document.

Choosing a Pattern

A decision tree (original article) helps match use cases to patterns. Patterns can be combined, e.g., a Pipeline ending with a Reviewer step or a Generator preceded by an Inversion to collect variables.

ADK’s SkillToolset and progressive disclosure load only the required pattern at runtime, conserving context tokens and improving reliability.