5 Proven Design Patterns to Supercharge Your AI Agent Skills

When authoring SKILL.md files, the main difficulty is not YAML syntax or directory layout but how to structure the skill logic. Surveying Anthropic’s repository, Vercel’s guides, and Google’s internal documentation reveals five reusable design patterns that make agent skills reliable and maintainable.

Pattern 1: Tool Wrapper

Goal: let an agent become an expert on any library without hard‑coding API specifications into the system prompt. The skill loads a references/ document only when a relevant keyword appears (e.g., FastAPI).

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions.
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

Goal: produce structured output by filling a template. Two directories are used: assets/ holds output templates, and references/ holds style guides. The skill loads the style guide, asks the user for missing fields, then fills the template.

# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown.
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 missing information (Topic, Key findings, Target audience).
Step 4: Fill the template following the style guide.
Step 5: Return the completed report as a single Markdown document.

Pattern 3: Reviewer

Goal: separate “what to check” from “how to check”. The skill stores a checklist (e.g., references/review-checklist.md) and, when code is submitted, loads the checklist, iterates through each rule, classifies severity (error, warning, info), explains why the issue matters, and suggests a concrete fix.

# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs.
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 and understand its purpose before critiquing.
Step 3: Apply each rule from the checklist to the code. For every violation:
- 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 sections:
- **Summary**: overall quality assessment
- **Findings**: grouped by severity (errors first, then warnings, then info)
- **Score**: rate 1‑10 with brief justification
- **Top 3 Recommendations**: most impactful improvements

Pattern 4: Inversion

Goal: flip the usual flow so the agent interviews the user before producing output. A strict gating instruction (e.g., “do not start building until all phases are complete”) forces the agent to ask one question, wait for the answer, then proceed.

# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions before producing a plan.
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
- 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
- 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
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

Goal: handle complex, multi‑step tasks by embedding hard checkpoints in the instruction set. The agent cannot skip a step or proceed without explicit approval (e.g., user must approve generated docstrings before assembly).

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates 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 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 and 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': ensure every public symbol is documented, every parameter has a type and description, and each function includes at least one usage example. Report results and fix issues before presenting the final document.

Choosing a Pattern

Inject library or framework knowledge → Tool Wrapper

Generate documents or code from a fixed template → Generator

Standardized code or content review → Reviewer

Collect requirements before producing output → Inversion

Complex multi‑step workflows with checkpoints → Pipeline

Patterns are composable. For example, a Pipeline can end with a Reviewer step for double‑checking, or a Generator can start with an Inversion phase to gather variables before filling the template.

Implementation Aid

The ADK SkillToolset adds progressive disclosure, ensuring the agent only consumes context tokens for the patterns actually used at runtime.

Repository with a skill optimizer that analyses a skill, suggests the most suitable design pattern based on best practices, and can automatically apply the recommended optimization after user confirmation:

https://github.com/chujianyun/skills/tree/main/skills/skill-optimizer