5 Google-Defined Agent Skill Design Patterns: From Tool Wrapper to Pipeline

Pattern 1: Tool Wrapper – Load Knowledge on Demand

Core logic: Load a specific technology‑stack knowledge base only when the agent detects related keywords (e.g., "FastAPI", "REST API", "Pydantic").

Advantages:

Keeps the context window clean.

Updates to standards require only changing the skill file.

Team guidelines can be packaged as a reusable skill.

Applicable scenarios:

Encapsulating framework or library coding conventions.

Team internal style guides.

Best‑practice documentation for a specific stack.

Code example (FastAPI skill):

---
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.
## 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

The SKILL.md file points the agent to the external reference rather than embedding the full specification.

Pattern 2: Generator – Template‑Driven Document Generation

Core logic: Combine a markdown template with a style guide to force consistent output, eliminating variability in generated documents.

Process:

Load the template ( assets/report-template.md).

Load the style guide ( references/style-guide.md).

Prompt the user for missing variables (topic, key data, target audience).

Fill the template according to the guide.

Advantages:

Fully controllable output format.

Uniform style across collaborators.

Supports complex structures such as API docs, technical reports, and project scaffolds.

Code example (technical report generator):

---
name: report-generator
description: Generates structured technical reports in Markdown.
metadata:
  pattern: generator
  output-format: markdown
---
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 missing information:
- Topic or subject
- Key findings or data points
- Target audience
Step 4: Fill the template following the style guide rules.
Step 5: Return the completed report.

The crucial step is the agent’s proactive ask (Step 3) to ensure sufficient information.

Pattern 3: Reviewer – Automated Code Review

Core logic: Separate "what to check" from "how to check" by keeping a checklist in references/review-checklist.md. The agent scores each item and groups results by severity.

Problems with traditional prompts:

Prompt bloat from long checklists.

Difficult to adapt standards per project.

Mixed logic and policy make maintenance hard.

Advantages:

Modular checklists enable swapping standards.

Structured output grouped by error, warning, info.

Extensible to security scans, style checks, or custom rules.

Code example (Python code reviewer):

---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs.
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---
Step 1: Load 'references/review-checklist.md'.
Step 2: Read the user's code carefully.
Step 3: Apply each rule from the checklist. For every violation:
- Note the line number
- 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 structured review:
- Summary: What the code does, overall quality
- Findings: Grouped by severity
- Score: Rate 1‑10 with justification
- Top 3 Recommendations: Most impactful improvements

The emphasis on "WHY not WHAT" helps developers understand the rationale behind each issue.

Pattern 4: Inversion – Agent Asks First

Core logic: Reverse the usual flow; the agent conducts a multi‑turn interview to collect complete requirements before any generation begins.

Phases:

Phase 1 – Problem Discovery (what problem, who are users, expected scale).

Phase 2 – Technical Constraints (deployment environment, stack preferences, non‑negotiable requirements).

Phase 3 – Synthesis (design after all information is gathered).

Key technique: Include a hard gate in SKILL.md – "DO NOT start building until all phases are complete" – preventing the agent from skipping steps.

Code example (project planner):

---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions.
metadata:
  pattern: inversion
  interaction: multi-turn
---
DO NOT start building or designing until all phases are complete.
## Phase 1 — Problem Discovery
- Q1: "What problem does this project solve?"
- Q2: "Who are the primary users?"
- Q3: "What is the expected scale?"
## Phase 2 — Technical Constraints
- Q4: "What deployment environment?"
- Q5: "Any technology stack preferences?"
- Q6: "What are non‑negotiable requirements?"
## Phase 3 — Synthesis
1. Load 'assets/plan-template.md'
2. Fill in every section using gathered requirements
3. Present the completed plan
4. Ask: "Does this capture your requirements?"
5. Iterate on feedback until user confirms

Serial execution of Phase 1 and Phase 2 ensures no information is missed.

Pattern 5: Pipeline – Multi‑Step Workflow with Gates

Core logic: Decompose a complex task into ordered steps, each with explicit input, output, and a "diamond gate" that requires user confirmation before proceeding.

Example task – API documentation generation:

Parse & Inventory: Analyze code, list public APIs, ask user to confirm completeness.

Generate Docstrings: For each function lacking a docstring, load style guide, generate, and seek approval.

Assemble Documentation: Combine APIs and docstrings using a template.

Quality Check: Verify against a checklist (every public symbol documented, parameters typed, at least one usage example).

Key design: Steps cannot be skipped; the agent must wait for explicit user confirmation (e.g., "Do NOT proceed to Step 3 until user confirms").

Code example (doc‑pipeline):

---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline.
metadata:
  pattern: pipeline
  steps: "4"
---
Execute each step in order. Do NOT skip steps.
## Step 1 — Parse & Inventory
Analyze code to extract all public classes, functions, constants.
Present inventory as checklist.
Ask: "Is this the complete public API?"
## Step 2 — Generate Docstrings
For each function lacking docstring:
- Load 'references/docstring-style.md'
- Generate docstring following style guide
- Present for user approval
Do NOT proceed to Step 3 until user confirms.
## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md'.
Compile all classes, functions, docstrings into single API reference.
## Step 4 — Quality Check
Review against 'references/quality-checklist.md':
- Every public symbol documented
- Every parameter has type and description
- At least one usage example per function
Report results. Fix issues before presenting final document.

The "Do NOT proceed" constraint enforces human quality control before the pipeline advances.

Choosing the Right Pattern

Need the agent to know a specific tech‑stack standard → Tool Wrapper

Require uniformly formatted documents or code → Generator

Automate code review or security scanning → Reviewer

Unclear requirements, need information gathering first → Inversion

Complex tasks that need stepwise execution with human checkpoints → Pipeline

Advanced Tip: Pattern Combinations

Pipeline + Reviewer: Add an automated review as the final pipeline step.

Generator + Inversion: Interview the user before filling the template.

Tool Wrapper + Reviewer: Load team guidelines as the review checklist.

References

Google ADK official documentation: https://google.github.io/adk-docs/

Google Cloud Tech tweet thread: https://x.com/googlecloudtech/status/2033953579824758855

Agent Skills specification: https://agentskills.io/

ADK Python 2.0 Alpha release: https://google.github.io/adk-docs/2.0/