Google’s Five Core Agent Skill Design Patterns: Elevating Agent Skills to a New Design Paradigm

Agent Skill Core Status

Developers of enterprise AI applications often focus on the SKILL.md format: correct YAML, directory layout, and strict compliance with official specifications. With more than 30 mainstream Agent tools (Claude Code, Gemini CLI, Cursor, etc.) adopting the same layout, format issues are now fully resolved. The remaining bottleneck is the lack of guidance on designing the internal logic of a Skill. Identical external formats can lead to vastly different execution behavior across scenarios such as tool wrapping, content generation, code review, requirement gathering, and workflow orchestration.

Five Core Skill Design Patterns

1. Tool Wrapper

The most basic and easiest‑to‑implement pattern. It provides an Agent with on‑demand access to a specific library’s context, removing hard‑coded API specifications from system prompts.

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions. Used for building, reviewing, or debugging FastAPI apps, REST APIs, or Pydantic models.
metadata:
  pattern: tool-wrapper
  domain: fastapi
---
You are a FastAPI expert. Apply the following conventions to the user’s code or question.
## Core Conventions
Load `references/conventions.md` to obtain the full FastAPI best‑practice checklist.
## During Code Review
1. Load the convention reference file.
2. Compare each rule against the user’s code.
3. For every violation, cite the specific rule and suggest a fix.
## When Writing Code
1. Load the convention reference file.
2. Strictly follow all conventions.
3. Add type annotations to every function signature.
4. Use the <em>Annotated</em> style for dependency injection.

Typical scenarios

Framework convention injection (FastAPI, Spring Boot, React, etc.)

Automatic synchronization of internal coding standards

Third‑party API usage rule encapsulation

2. Generator

This pattern solves the inconsistency problem of free‑form generation by using a template + style guide to produce fill‑in‑the‑blank, standardized output.

It relies on two directories: assets/ for output templates and references/ for formatting rules. The Skill only orchestrates the workflow and does not embed concrete content.

# skills/report-generator/SKILL.md
---
name: report-generator
description: Generate a Markdown‑formatted structured technical report. Used when the user asks to write, draft, or summarize a report or analysis document.
metadata:
  pattern: generator
  output-format: markdown
---
You are a technical report generator. Follow these steps strictly:
Step 1: Load `references/style-guide.md` for tone and format rules.
Step 2: Load `assets/report-template.md` for the required output structure.
Step 3: Ask the user for all missing information (topic, key conclusions, audience, etc.).
Step 4: Fill the template according to the style guide, ensuring every section appears.
Step 5: Return the completed report as a single Markdown document.

Typical scenarios

Automatic technical report generation

Standardized API documentation

Unified commit message creation

Project scaffolding

3. Reviewer

The Reviewer pattern separates “check rules” from the “review process”. Rules live in references/review-checklist.md, while the Skill executes a standardized review workflow and outputs structured findings with severity levels.

Switching the checklist instantly changes the review capability (code style, security scanning, architectural audit, etc.).

# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Review Python code quality, style, and common defects. Used when a user submits code for feedback or audit.
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---
You are a Python code reviewer. Follow this strict process:
Step 1: Load `references/review-checklist.md` for the full review criteria.
Step 2: Read the user’s code and understand its purpose before judging.
Step 3: Apply each checklist rule. For every violation, record:
- Line number (or approximate location)
- Severity (error = must fix, warning = suggest fix, info = optional improvement)
- Root cause explanation
- Concrete fix suggestion and corrected code
Step 4: Output a structured review containing:
**Overview** of functionality and overall quality
**Issue list** grouped by severity
**Score** (1‑10) with brief rationale
**Top three optimization suggestions**

Typical scenarios

Automated PR code review

Pre‑emptive security vulnerability detection

Documentation compliance checking

Technical solution scoring

4. Inversion

Traditional Agents execute immediately after receiving an instruction, which often leads to hallucination due to insufficient information. Inversion flips the flow: the Agent acts as an interviewer, collecting required details through multi‑turn dialogue before any final task execution.

Strong constraint commands (e.g., “Do not start building until all phases are completed”) enforce a strict gate that prevents execution with incomplete data.

Typical scenarios

Software project planning

System architecture design

Requirement gathering and decomposition

Complex task pre‑evaluation

# skills/project-planner/SKILL.md
---
name: project-planner
description: Conduct structured requirement interviews, then plan a new software project. Triggered when the user says “I want to build…”, “Help me design a system”, etc.
metadata:
  pattern: inversion
  interaction: multi-turn
---
You are conducting a structured requirement interview. **Do not start building or designing before all phases are completed.**
## Phase 1 – Problem Discovery (ask one question, wait for answer)
1. What problem does the project solve?
2. Who are the primary users and what is their technical proficiency?
3. What scale is expected? (DAU, data volume, request rate)
## Phase 2 – Technical Constraints (only after Phase 1 is fully answered)
4. Which deployment environment will be used?
5. Any preferred tech stack?
6. Hard constraints (latency, availability, compliance, budget)
## Phase 3 – Solution Generation (only after all questions answered)
7. Load `assets/plan-template.md` as output format.
8. Fill the template with collected requirements.
9. Present the full plan to the user.
10. Ask: “Does this plan accurately reflect your needs? What needs adjustment?”
11. Iterate based on feedback until the user confirms.

5. Pipeline

Pipeline is designed for high‑reliability complex tasks. It inserts hard checkpoints that must be satisfied before moving to the next step, supporting exception handling and optional human confirmation.

The pattern heavily uses the assets/ and references/ directories, loading resources only when needed to keep the context window minimal.

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generate API documentation from Python source code through a multi‑step pipeline.
metadata:
  pattern: pipeline
  steps: "4"
---
You are running a documentation generation pipeline. Execute each step in order; **do not skip any step, and abort on failure**.
## Step 1 – Parse and List
Analyze the user’s Python code, extract all public classes, functions, and constants, and present a checklist. Ask: “Is this the complete set of public interfaces you need documented?”
## Step 2 – Generate Docstrings
For each function lacking a docstring:
- Load `references/docstring-style.md` for the required format.
- Strictly follow the style guide to generate a docstring.
- Show the generated result and request user confirmation.
**Do not proceed to Step 3 without user confirmation.**
## Step 3 – Assemble Documentation
Load `assets/api-doc-template.md` as the output structure and combine all classes, functions, and docstrings into a single API reference document.
## Step 4 – Quality Check
Compare against `references/quality-checklist.md`:
- All public symbols documented?
- All parameters typed and described?
- Each function includes at least one usage example?
Output the check results; after fixing any issues, present the final document.

Typical scenarios

Automated code‑to‑documentation pipeline

End‑to‑end data collection → cleaning → analysis → reporting workflow

Multi‑stage development automation (code → review → test → package)

Pattern Combination and Engineering Best Practices

The five patterns are not mutually exclusive; they can be flexibly combined, which is key to enterprise‑grade Agent engineering:

Append a Reviewer at the end of a Pipeline for self‑validation.

Use Inversion to gather information before a Generator produces output.

Chain multiple Tool Wrappers inside a Pipeline for stepwise library access.

Trigger a Generator automatically after Inversion completes its interview.

Following these principles markedly improves stability:

Context minimization : Load reference files only when needed.

Flow‑gate enforcement : Require confirmation or validation at critical steps.

Rule‑command separation : Keep rules in files, workflow in the Skill.

Graceful degradation : Allow a single step failure without crashing the whole pipeline.

How to Quickly Choose the Right Skill Pattern

Need the Agent to master a specific library/framework → Tool Wrapper

Require fixed format and stable output → Generator

Need code/document review and scoring → Reviewer

Requirements are vague or information is incomplete → Inversion

Task involves multiple steps, strict flow, and cannot skip steps → Pipeline

Practical Recommendations

After standardizing SKILL.md format, the competitive edge shifts from “writing the format” to “designing reliable workflows”. Google’s ADK provides the five patterns to decompose long, fragile prompts into structured, reusable, maintainable modules.

For developers, a concrete adoption path is:

Match a single pattern to the immediate scenario and build a usable Skill quickly.

Gradually introduce pattern combinations to construct more complex workflows.

Centralize management of references/ and assets/ to create shared team assets.

Establish versioning and evaluation mechanisms for continuous iteration and optimization.

Stop stuffing complex logic into a single system prompt; leverage the five Skill design patterns to build stable, reliable, and scalable enterprise‑level AI Agents.