This post extends the 3-part ADK Skills series:

• Part 1: Progressive Disclosure with SkillToolset
• Part 2: File-Based, External Skills & SkillToolset Internals
• Part 3: Skills That Write Skills — Self-Extending ADK Agents
• ADK Core Skills — official skills for building ADK agents

ADK skill design patterns are reusable structural templates for organizing SKILL.md files — the markdown-based instruction format that tells Google ADK agents how to use tools, generate content, or orchestrate multi-step workflows. In Parts 1-3 of this series, I covered the foundations — what agent skills are, how Google ADK’s SkillToolset implements progressive disclosure, and how to build self-extending agents with meta-skills. But one question kept coming up in my own projects: I know how to create a skill, but how should I structure the content inside it?

A skill that wraps FastAPI conventions looks nothing like a skill that runs a 4-step documentation pipeline, yet both use the same SKILL.md format. The Agent Skills specification defines the container — SKILL.md frontmatter, references/, assets/, scripts/ directories — but says nothing about what goes inside. That’s a content design problem, not a format problem.

Five patterns keep surfacing. I’ve seen them across Claude Code’s bundled skills , community repos on skills.sh , real-world projects, and even in a recent arXiv paper that formally catalogued seven system-level skill design patterns. This post names the five most practical ones, shows each in ADK with working code, and helps you pick the right one for your use case.

By the end of this post, you’ll know how to:

• Use a Tool Wrapper to make your agent an instant expert on any library or framework
• Use a Generator to produce consistently structured documents from a reusable template
• Use a Reviewer to have your agent score code against a checklist, grouped by severity
• Use an Inversion to flip the conversation — the agent asks you questions before acting
• Use a Pipeline to enforce a strict step-by-step workflow with checkpoints between stages

Note

• Tool Wrapper — like a cheat sheet for a library; makes your agent apply its conventions only when relevant
• Generator — like a form your agent fills in; produces consistently structured documents every time
• Reviewer — like a rubric; scores submitted code against a checklist with findings grouped by severity
• Inversion — the agent interviews you first; asks structured questions before producing any output
• Pipeline — like a recipe with sign-offs; enforces a strict step-by-step workflow so nothing gets skipped
• All five patterns compose — a Pipeline can include a Reviewer step; a Generator can use Inversion for input gathering

One SKILL.md Format, Many Use Cases#

The Agent Skills standard has been adopted by over 30 agent tools — Claude Code, Gemini CLI, GitHub Copilot, Cursor, JetBrains Junie, and many more. Every skill follows the same directory layout:

skill-name/
├── SKILL.md          ← YAML frontmatter + markdown instructions (required)
├── references/       ← style guides, checklists, conventions (optional)
├── assets/           ← templates and output formats (optional)
└── scripts/          ← executable scripts (optional)

I covered the format in detail in Part 2 , so I won’t repeat it here.

The format tells you how to package a skill. It doesn’t tell you how to design the content. Should the instructions be a checklist? A workflow? A set of questions? Should references hold style guides, templates, or lookup tables? The answer depends on what your skill is trying to do, and that’s where patterns come in.

Each of the five patterns in this post uses the same SKILL.md format but structures the content differently — different instruction styles, different resource types, different relationships between L2 (instructions) and L3 (references/assets). If you need a refresher on the three progressive disclosure levels, see Part 1’s explanation .

Quick Recap: SkillToolset and the Three Levels#

ADK’s SkillToolset implements progressive disclosure through three auto-generated tools. I covered the internals in Part 2 , so here’s just the quick version: list_skills shows skill names and descriptions (L1), load_skill fetches full instructions (L2), and load_skill_resource loads reference files and templates on demand (L3). The agent pays ~100 tokens per skill at startup, then loads the rest only when needed.

For the pattern examples in this post, all five skills are loaded into a single SkillToolset. The agent decides which to activate based on the user’s request.

# agent.py
import pathlib

from google.adk import Agent
from google.adk.skills import load_skill_from_dir
from google.adk.tools.skill_toolset import SkillToolset

SKILLS_DIR = pathlib.Path(__file__).parent / "skills"

skill_toolset = SkillToolset(
    skills=[
        load_skill_from_dir(SKILLS_DIR / "api-expert"),       # Pattern 1: Tool Wrapper
        load_skill_from_dir(SKILLS_DIR / "report-generator"), # Pattern 2: Generator
        load_skill_from_dir(SKILLS_DIR / "code-reviewer"),    # Pattern 3: Reviewer
        load_skill_from_dir(SKILLS_DIR / "project-planner"),  # Pattern 4: Inversion
        load_skill_from_dir(SKILLS_DIR / "doc-pipeline"),     # Pattern 5: Pipeline
    ],
)

root_agent = Agent(
    model="gemini-2.5-flash",
    name="pattern_demo_agent",
    instruction="Load relevant skills before acting on any user request.",
    tools=[skill_toolset],
)

The description field in each skill’s frontmatter is the most important line. It’s the agent’s search index — if the description is vague, the agent won’t activate the skill when it should. Each pattern below shows how to write descriptions that trigger reliably.

Pattern 1: Tool Wrapper — Teach the Agent a Library#

A Tool Wrapper is an agent skill that packages a library or tool’s conventions, best practices, and coding standards into on-demand knowledge the agent loads when working with that technology. It is the simplest SKILL.md pattern — instructions plus reference files, no templates or scripts.

A Tool Wrapper skill packages a library or tool’s conventions into on-demand knowledge. The agent becomes a domain expert when the skill is loaded. Think FastAPI conventions, Terraform patterns, security policies, or database query best practices.

This is the simplest pattern. No templates, no scripts — just instructions telling the agent what rules to follow, plus references/ holding the detailed convention docs.

# 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

The references/conventions.md file holds the actual rules — naming conventions, route definitions, error handling patterns, async vs sync guidance. The agent loads this file only when it activates the skill, keeping the baseline context small.

The description here is critical. It includes specific keywords — “FastAPI”, “REST APIs”, “Pydantic models” — that match what developers actually type. A description like “Helps with APIs” would rarely trigger because it’s too generic.

When to use Tool Wrapper#

When you want your agent to apply consistent, expert-level conventions for a specific library, SDK, or internal system. This is the most widely adopted pattern — several engineering teams have open-sourced theirs as reference:

• Vercel react-best-practices — 40+ React and Next.js performance rules from Vercel Engineering, organized by impact level (CRITICAL → LOW), loaded on demand when the agent works on React or Next.js code
• Supabase supabase-postgres-best-practices — Postgres optimization guidelines across 8 categories (query performance, connection management, RLS, security) structured as on-demand references
• Google gemini-api-dev — Google’s official Tool Wrapper for the Gemini API, encoding best practices for building Gemini-powered apps, installable directly into any skills-compatible agent
• Google adk-core-skills — Google’s official ADK development skills: 6 skills covering the ADK developer guide, cheatsheet, evaluation, deployment, observability, and scaffolding. Installable via npx skills add google/adk-docs -y -g into any coding agent (Gemini CLI, Claude Code, Cursor). These are Tool Wrappers that teach coding agents how to write ADK code correctly — the ADK team dogfooding the same SKILL.md format that SkillToolset uses at runtime.

The pattern works equally well for internal tools: write a google-adk-conventions skill that encodes your team’s ADK patterns — which model to default to, how to name agents, how to wire toolsets, how to handle errors — and every ADK agent your team builds follows the same conventions automatically, without repeating them in every system prompt.

# skills/google-adk-conventions/SKILL.md
---
name: google-adk-conventions
description: Google ADK coding conventions and best practices. Use when building,
  reviewing, or debugging any ADK agent, tool, or multi-agent system.
metadata:
  pattern: tool-wrapper
  domain: google-adk
---

You are an ADK expert. Apply these conventions when writing or reviewing ADK code.

## Agent Naming
- The `name` field must match the agent's directory name exactly (`search-agent/` → `name="search-agent"`)
- Use lowercase, hyphen-separated names: `search-agent`, not `SearchAgent`

## Model Selection
- Default to `gemini-2.5-flash` for most tasks (fast, cost-efficient)
- Use `gemini-2.5-pro` only for complex multi-step reasoning
- Define model as a constant, never hardcode inline: `MODEL = "gemini-2.5-flash"`

## Tool Definitions
Load `references/tool-conventions.md` for the complete rules. Key points:
- Names: verb-noun, snake_case — `get_weather`, `search_documents`, not `run` or `doStuff`
- Always add type hints: `city: str`, `user_id: int`
- No default parameter values — the LLM must derive or request all inputs
- Docstring is the LLM's primary manual — be precise, don't describe `ToolContext`

## Multi-Agent Systems
- The `description` field on sub-agents is your routing API — be specific, not generic
- Only one built-in tool (Google Search, Code Exec) per root agent
- Group related tools into a `BaseToolset` subclass when an agent has 5+ tools

Note

The metadata field in frontmatter is a dict[str, str] — ADK stores it but doesn’t enforce any schema. I use it to tag skills by pattern and domain, which helps when you have 20+ skills and need to audit them.

Pattern 2: Generator — Produce Structured Output#

A Generator skill produces documents, reports, or configurations by filling a reusable template. Unlike Tool Wrapper, it uses both optional directories: assets/ holds the output template (the structure to fill in), and references/ holds the style guide (the quality rules to follow). The instructions orchestrate the process — load the style guide, load the template, gather inputs, fill it in.

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

The template in assets/report-template.md defines the exact sections every report must have — Executive Summary, Background, Methodology, Findings, Summary Table, Recommendations, Next Steps. The style guide in references/style-guide.md controls tone (“third person, active voice”), formatting (“H2 for sections, H3 for subsections”), and quality (“Executive Summary under 150 words, no vague Next Steps”).

The agent loads both files via load_skill_resource when it activates the skill. The template enforces structure, the style guide enforces quality. Swap either file to change the output without touching the instructions.

When to use Generator#

When the output needs to follow a fixed structure every time — consistency matters more than creativity. Common real-world uses:

• Technical reports — Executive Summary, Methodology, Findings, Recommendations, always in the same order regardless of topic
• API documentation — every endpoint documented with the same sections: description, parameters, request/response examples, error codes
• Commit messages — enforce Conventional Commits format (feat:, fix:, docs:) from a template, so every commit in the repo reads consistently
• ADK agent scaffolding — generate the standard agent.py + __init__.py + .env structure for a new ADK project from a template, pre-wired with your team’s model constant and instruction style

Pattern 3: Reviewer — Evaluate Against a Standard#

A Reviewer skill evaluates code, content, or artifacts against a checklist stored in references/, producing a scored findings report grouped by severity. The key design insight: separating WHAT to check (the checklist file) from HOW to check (the review protocol in the instructions). Swap references/review-checklist.md for references/security-checklist.md and you get a completely different review from the same skill structure.

# 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 on their code, 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

The references/review-checklist.md contains the actual rules organized by category — Correctness (severity: error), Style (severity: warning), Documentation (severity: info), Security (severity: error), Performance (severity: info). Each category has specific, checkable items: “No mutable default arguments”, “Functions under 30 lines”, “No wildcard imports.”

When I tested this against a function with three intentional bugs — PascalCase naming, a mutable default argument, and a bare except: — the agent loaded the skill, fetched the checklist, and caught all three. It classified the mutable default as an error (correct — it’s a bug), the naming as a warning (correct — it’s style), and produced a scored report. The checklist drove the behavior, not the agent’s pre-training.

When to use Reviewer#

Anywhere a human reviewer works from a checklist — a Reviewer skill can encode it and apply it consistently. Common real-world uses:

• Code review — catch mutable defaults, missing type hints, bare except: blocks against your team’s style rules; Giorgio Crivellari demonstrated this with an ADK governance skill that lifted code quality scores from 29% to 99%
• Security audit — run OWASP Top 10 checks against submitted code, classifying findings by severity before any human review
• Editorial review — check blog posts or docs against a house style guide (tone, heading structure, word count, forbidden phrases)
• ADK agent review — validate a new agent against your team’s google-adk-conventions: naming, model constant, tool docstrings, description field quality

Pattern 4: Inversion — The Skill Interviews You#

Inversion flips the typical agent interaction: instead of the user driving the conversation, the skill instructs the agent to ask structured questions through defined phases before producing any output. The agent won’t act until it has gathered all the information it needs. No special framework support required — Inversion is purely an instruction-authoring pattern, relying on explicit gates like DO NOT start building until all phases are complete to hold the agent back.

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

Ask these questions in order. Do not skip any.

- 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

The phased structure is what makes Inversion work. Phase 1 must complete before Phase 2 starts. Phase 3 only triggers after all questions are answered. The DO NOT start building or designing until all phases are complete instruction at the top is the critical gate — without it, agents tend to jump to conclusions after the first answer.

The assets/plan-template.md anchors the synthesis step. It defines sections for Problem Statement, Target Users, Scale Requirements, Technical Architecture, Non-Negotiable Requirements, Proposed Milestones, Risks & Mitigations, and Decision Log. The agent fills this template using the interview answers, producing a consistent output regardless of how the conversation went.

When to use Inversion#

Anywhere the agent needs context from the user before it can do useful work — it prevents the most common agent failure mode: generating a detailed plan based on assumptions instead of asking. Common real-world uses:

• Requirements gathering — interview a user about a project before producing a technical design, ensuring the plan reflects actual constraints rather than guesses
• Diagnostic interviews — walk through a structured troubleshooting checklist (environment, version, error message, reproduction steps) before suggesting a fix
• Configuration wizards — gather deployment preferences (cloud provider, region, scaling requirements) before generating infrastructure config
• ADK agent design — before scaffolding a new ADK agent, interview the user: what tools does it need, which model, is it part of a multi-agent system, what are the routing constraints?

Pattern 5: Pipeline — Enforce a Multi-Step Workflow#

A Pipeline skill defines a sequential workflow where each step must complete before the next begins, with explicit gate conditions that prevent the agent from skipping validation. It’s the most complex pattern — unlike Tool Wrapper which just loads references, Pipeline uses all three optional directories (references/, assets/, scripts/) and adds control flow between steps. The instructions themselves are the workflow definition.

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

The gate conditions are the defining feature. “Do NOT proceed to Step 3 until the user confirms” prevents the agent from assembling documentation with unreviewed docstrings. “Do NOT skip steps or proceed if a step fails” at the top enforces the sequential constraint. Without these gates, agents tend to barrel through all steps and present a final result that skipped validation.

Each step loads different resources. Step 2 loads references/docstring-style.md (Google-style docstring format). Step 3 loads assets/api-doc-template.md (the output structure with Table of Contents, Classes, Functions, Constants sections). Step 4 loads references/quality-checklist.md (completeness and quality rules). The agent only pays context tokens for the resources it needs at each step.

When to use Pipeline#

Any multi-step process where steps have dependencies and order matters — if skipping a step would produce incorrect or unvalidated output, use Pipeline. Common real-world uses:

• Documentation generation — parse code → generate docstrings (with user approval) → assemble docs → quality check, with gates between each stage
• Data processing — validate input → transform → enrich → write output, where each step must succeed before the next runs
• Deployment workflows — run tests → build artifact → deploy to staging → smoke test → promote to production, with human confirmation gates
• ADK agent onboarding — interview user (Inversion) → scaffold files (Generator) → validate against conventions (Reviewer), composing three patterns into one Pipeline

Choosing the Right ADK Skill Pattern#

Each pattern answers a different question. Use this table to find the right one, then follow the decision tree below if you’re still unsure.

Patterns compose. A Pipeline can include a Reviewer step — the doc-pipeline’s Step 4 loads quality-checklist.md and evaluates the assembled document against it, which is the Reviewer pattern embedded inside a Pipeline. A Generator can use Inversion to gather inputs before producing output. A Tool Wrapper can be embedded as a reference file inside a Pipeline skill. The arXiv paper “SoK: Agentic Skills” (February 2026) found that production systems typically combine 2-3 patterns, with the most common combination being metadata-driven disclosure (our Tool Wrapper) plus marketplace distribution.

If you’re unsure which pattern fits, start with this decision tree:

The ADK Skills Ecosystem#

You don’t have to write every skill from scratch. The Agent Skills standard means any skill authored for Claude Code, Gemini CLI, Cursor, or 30+ compatible agents loads in ADK with load_skill_from_dir(). Here’s where to find them:

• skills.sh — the largest community marketplace (86,000+ installs); browse and install any skill with npx skills add <owner/repo>
• google-gemini/gemini-skills — Google’s official Tool Wrapper skills for the Gemini API, covering best practices for building Gemini-powered apps
• google/adk-docs/skills — Google’s official ADK development skills (dev guide, cheatsheet, eval, deploy, observability, scaffold) — install via npx skills add google/adk-docs -y -g
• vercel-labs/agent-skills — Vercel’s official skills for React, Next.js, AI SDK, and deployment patterns (22K stars)
• supabase/agent-skills — Supabase’s Postgres optimization guidelines across query performance, RLS, and connection management
• anthropics/skills — production-grade document skills for PowerPoint, Excel, Word, and PDF generation (86,500 stars)
• VoltAgent/awesome-agent-skills — curated collection of official skills from leading engineering teams
• kodustech/awesome-agent-skills — skills focused on architecture and design patterns

To load any of these in ADK, clone or copy the skill directory and point load_skill_from_dir at it:

# Loading a community skill from any skills-compatible source
community_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "community-skill-name"
)

Note

The directory name must match the name field in the skill’s SKILL.md frontmatter — ADK enforces this at load time. Part 2 covers the exact error behavior.

Warning

Use external skills at your own risk. Community and third-party skills are not reviewed or endorsed by Google or the ADK team. Before loading any external skill, review its SKILL.md instructions, reference files, and scripts for unintended behavior, data exfiltration, or prompt injection. You are responsible for auditing any skill you add to your agent.

ADK Core Skills: Google’s Official Development Skills#

Google publishes official skills that teach coding agents how to write ADK code:

Install all six globally with one command:

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

These are Tool Wrapper skills — the same pattern covered above . They follow the agentskills.io specification, which means they work in Gemini CLI, Claude Code, Cursor, and any compatible agent. The ADK team dogfoods the same SKILL.md format that SkillToolset uses at runtime — one spec powering both the development workflow (coding agents writing ADK code) and the production runtime (deployed agents loading skills on demand).

Frequently Asked Questions#

Can I use skills developed in ADK with other coding agents?#

Yes — skills you develop inside ADK follow the agentskills.io specification , the same open standard used by Gemini CLI, Antigravity, Claude Code, and OpenAI Codex. A skill authored in ADK can be loaded by any of these agents. The cross-client convention is to store shared skills in <project>/.agents/skills/ or ~/.agents/skills/. For externally authored skills (from community repos or other teams), check each agent’s documentation for how to import and load them.

How many skills can one agent have?#

No hard limit in the current ADK release (v1.25.0+, marked Experimental). SkillToolset injects skill descriptions (~100 tokens each) on every LLM call via process_llm_request() . At 50 skills, that’s roughly 5,000-7,500 tokens of overhead per call (including XML wrapping) — still manageable for models with 128K+ context windows. Performance degrades gracefully as skill count increases.

Can patterns be combined?#

Yes. A Pipeline skill can include Reviewer steps (the doc-pipeline’s Step 4 is a quality review). A Generator can use Inversion to gather inputs before producing output. The arXiv paper found that production systems use a median of 2 patterns per skill, with the most common combination being metadata-driven disclosure plus marketplace distribution.

What about executable scripts in the scripts/ directory?#

Script execution via the scripts/ directory is not yet supported in the current pip release — the ADK docs list it as a known limitation. When it ships, it will enable Pipeline and Tool Wrapper patterns with executable Python and shell scripts running directly from the skill directory. I previewed this capability in Part 3’s “What’s Next” .

Where should I store skills — project level or user level?#

Project-level (<project>/.agents/skills/) for team-shared skills that live with the codebase. User-level (~/.agents/skills/) for personal skills across all projects. ADK uses explicit load_skill_from_dir() paths — you choose the directory, and the convention from the Agent Skills spec handles cross-client interoperability.

How do I test a skill’s effectiveness?#

The agentskills.io specification defines an evaluation methodology : create test cases in evals/evals.json, run each case with and without the skill, and measure the pass rate delta. The delta tells you exactly what the skill buys versus what it costs in context tokens.

What is the difference between ADK skills and tools?#

Tools give agents the ability to take actions — call APIs, read files, query databases. Skills teach agents when and how to use those tools effectively. A tool is “call the weather API.” A skill is “when the user asks about travel, check weather for each destination, compare results, and format as an itinerary.” Skills compose on top of tools — see Part 1’s explanation for the full distinction.

How do SKILL.md files work in Google ADK?#

SKILL.md files are markdown documents with YAML frontmatter (name, description) and structured instructions. ADK’s SkillToolset loads them via load_skill_from_dir(), auto-generates three tools (list_skills, load_skill, load_skill_resource), and uses progressive disclosure to load full instructions only when relevant to the user’s query. See Part 2 for the complete format reference.

Which SKILL.md design pattern should I start with?#

Start with Tool Wrapper — it’s the simplest pattern (just instructions plus reference files) and the most widely adopted. Wrap your team’s coding conventions or a library’s best practices into a SKILL.md with a references/ directory. Graduate to Generator or Reviewer when you need structured output or evaluation. The decision tree above can help you pick the right pattern.

What are ADK Core Skills and how do they relate to SkillToolset?#

ADK Core Skills are official skills published by Google that teach coding agents (Gemini CLI, Claude Code, Cursor) how to write ADK code correctly. They follow the Tool Wrapper pattern described in this post and use the agentskills.io specification. SkillToolset is the runtime API that equips deployed production agents with skills. Both use the same SKILL.md format: Core Skills help you build ADK agents; SkillToolset helps your agents run with modular knowledge.

What’s Next for ADK Skills#

Clone the companion repo , run adk web . , and try each pattern. Start with the Reviewer — submit some Python code and watch the agent load the checklist and produce a scored review. Then swap references/review-checklist.md for your own team’s coding standards.

If you’re new to ADK Skills, start with Part 1 for foundations. If you want skills that create other skills, Part 3 covers the meta-skill pattern. This post is part of the Agent Engineering series by Lavi Nigam — see more on ADK for related posts.

References#

1. Skills for ADK Agents — Official ADK documentation for SkillToolset and progressive disclosure
2. Agent Skills Specification — The open standard defining SKILL.md format, adopted by 30+ agent tools
3. What Are Agent Skills? — Conceptual overview and adoption list from agentskills.io
4. Part 1: Progressive Disclosure with SkillToolset — Foundations: L1/L2/L3 levels, inline skills
5. Part 2: File-Based, External Skills, and SkillToolset Internals — SKILL.md format, load_skill_from_dir, multi-skill loading
6. Part 3: Skills That Write Skills — Meta-skill pattern, self-extending agents
7. Companion Code Repository — Working code for all five patterns in this post
8. skill_toolset.py — SkillToolset source with auto-generated tools
9. skills_agent sample — Official ADK sample with inline + file-based skills
10. SoK: Agentic Skills — Beyond Tool Use in LLM Agents — arXiv paper (February 2026) identifying 7 system-level skill design patterns
11. skills.sh — Agent Skills Directory — Community marketplace with 86,000+ total installs
12. Anthropic Skills Repository — 86,500 stars, production-grade document skills
13. google-gemini/gemini-skills — Google’s official Tool Wrapper skills for the Gemini API
14. vercel-labs/agent-skills — Vercel’s official skills for React, Next.js, and deployment patterns
15. supabase/agent-skills — Supabase’s Postgres optimization guidelines as a Tool Wrapper skill
16. awesome-agent-skills (VoltAgent) — Curated collection from leading development teams
17. awesome-agent-skills (kodustech) — Architecture and design pattern skills
18. Using Scripts in Skills — Script design patterns for agentic use
19. Evaluating Skills — Eval methodology: test cases, pass rate delta
20. Giorgio Crivellari — I Built an Agent Skill for Google’s ADK — Reviewer pattern achieving 29% to 99% code quality
21. Coding with AI — ADK Core Skills — Official tutorial for using ADK skills with coding agents
22. ADK Core Skills (GitHub) — Source for the official ADK development skills

This is Part 1 of a 3-part series on building ADK agents with reusable skills.

• Part 2: File-Based, External Skills, and SkillToolset Internals →
• Part 3: Skills That Write Skills — Self-Extending ADK Agents →
• 5 SKILL.md Design Patterns Every ADK Developer Should Know →
• ADK Core Skills — official skills for building ADK agents

I’d been hearing about Agent Skills for weeks — the idea of giving agents modular knowledge they load on demand instead of cramming everything into a system prompt. I’d even used a few with Gemini CLI. But scrolling through tutorials and X threads, I kept hitting the same question: how far can this pattern actually go with Google’s Agent Development Kit (ADK)?

The Agent Skills format was originally developed by Anthropic , released as an open standard , and has been adopted by a growing list of agent products — Claude Code, GitHub Copilot, Cursor, Gemini CLI, OpenAI Codex, and many more . Google publishes official ADK development skills that teach coding agents how to write ADK code — the same SKILL.md format powering both the development and runtime sides of the ecosystem. One take captured the momentum : “SaaS is being replaced by SKILL.md files” — 562 reactions on X.

My first thought was whether Skills are just another take on MCP . Reading through the agentskills.io overview , the distinction became clear. MCP gives agents access to external tools and data — it’s the connectivity layer. Skills teach agents what to do with those tools. MCP is “how to call a weather API.” A skill is “when the user asks about travel, check weather, compare destinations, and format as an itinerary.” You need both, and they compose naturally .

ADK adopted the same agentskills.io specification with its own Skills integration . I had a use-case sitting right in front of me: a blog-writing agent that could apply SEO checklists, follow style guides, and generate new capabilities on demand, without burning 5,000 tokens of context on every LLM call.

By the end of this post, you’ll know how to:

• Explain progressive disclosure and why it’s better than stuffing everything into a system prompt
• Set up an ADK project with the skills directory structure and imports
• Define inline skills directly in Python for simple, stable rules

Tip

• Progressive disclosure loads agent knowledge in three levels (L1 metadata → L2 instructions → L3 resources), fetching each only when needed
• An agent with 10 skills starts each call with ~1,000 tokens of L1 metadata instead of ~10,000 tokens in a monolithic system prompt
• ADK’s SkillToolset auto-generates three tools (list_skills, get_skill_details, load_skill_resource) from any collection of SKILL.md files
• Inline skills are the simplest pattern — a Python dict with name, description, and instructions keys

What Are Skills and Why They Matter#

Progressive disclosure is a design pattern defined in the Agent Skills specification where an agent loads knowledge in three levels — lightweight metadata (L1), full instructions (L2), and reference files (L3) — fetching each level only when needed instead of loading all instructions into every LLM call.

The typical way to give an agent domain knowledge is to pack everything into the system prompt. Compliance rules, style guides, API references, troubleshooting procedures — all of it concatenated into one massive instruction string. This works fine when you have two or three capabilities. At ten, the system prompt is burning through thousands of tokens on every single LLM call, whether the user’s question is relevant to those instructions or not.

Skills solve this with progressive disclosure — a design pattern defined in the Agent Skills specification. Instead of loading everything upfront, the agent sees only a lightweight listing of skill names and descriptions. When the agent decides a skill is relevant to the current query, it explicitly loads that skill’s full instructions. If the skill references detailed documentation or templates, the agent fetches those on demand too. The spec defines three levels:

• L1 — Metadata (~100 tokens per skill): The name and description fields from SKILL.md frontmatter. Loaded at startup for all skills. This is the “menu” the agent scans to decide what’s relevant.
• L2 — Instructions (<5,000 tokens recommended): The full SKILL.md body. Loaded only when the agent activates a specific skill.
• L3 — Resources (as needed): Files in references/, assets/, or scripts/. Loaded only when the skill’s instructions reference them.

Here’s what that looks like in practice. Say you ask the agent “Review my blog post for SEO.” With the system-prompt approach, the agent already has all skill instructions in context — SEO rules, style guides, research methodology, skill-creation templates — whether it needs them or not. With progressive disclosure, the flow is different:

L1 — The agent scans the skill listing (always present, ~400 tokens for 4 skills):

seo-checklist: SEO optimization checklist for blog posts. Covers title tags, meta descriptions...
blog-writer: Blog post writing skill with structure templates and style guidelines...
content-research-writer: Creates research-based content with SEO optimization...
skill-creator: Creates new ADK-compatible skill definitions from requirements...

L2 — The agent calls load_skill("seo-checklist") (~300 tokens loaded on demand):

When optimizing a blog post for SEO, check each item:
1. Title: 50-60 chars, primary keyword near the start
2. Meta description: 150-160 chars, includes a call-to-action
3. Headings: H2/H3 hierarchy, keywords in 2-3 headings
...

L3 — If the skill references a file, the agent calls load_skill_resource (loaded only if needed):

load_skill_resource("seo-checklist", "references/seo-guidelines.md")
→ Returns the full SEO guidelines document

The three other skills stayed at L1 — the agent never loaded their instructions because it recognized the query was about SEO, not writing or research. To illustrate the savings: an agent with 10 skills, each averaging 1,000 tokens of instructions, would consume ~10,000 tokens in a system prompt on every call. The same agent using progressive disclosure starts each call with ~1,000 tokens of L1 metadata, then loads only the skill it needs. The exact savings depend on skill count and how often each skill is activated, but the pattern consistently keeps the baseline context small.

ADK implements this through the SkillToolset class, EXPERIMENTAL introduced in ADK Python v1.25.0 . SkillToolset wraps one or more skills into three auto-generated tools — list_skills, load_skill, and load_skill_resource — that map directly to L1, L2, and L3. The rest of this series builds a blog-writing agent that uses all three levels across four skill patterns.

ADK Project Setup#

The agent we’re building uses a single agent.py with four skills wired into one SkillToolset . Each pattern trades simplicity for reusability, and they’re ordered so that each one picks up where the previous one hits a ceiling.

The progression tells a story. Inline skills are 10 lines of Python — fast to write, but the knowledge lives only in your code. File-based skills move the knowledge to a directory with SKILL.md and reference docs, making it reusable. External skills take that same directory format from someone else’s repo. And meta skills close the loop: the agent writes new SKILL.md files itself, following the same spec.

This post covers the first pattern. Parts 2 and 3 build the remaining three.

Project Structure#

The official skills_agent sample uses this layout. Our blog-writing agent follows the same pattern.

app/
├── __init__.py
├── agent.py
├── .env
├── requirements.txt
└── skills/
    ├── blog-writer/
    │   ├── SKILL.md
    │   └── references/
    │       └── style-guide.md
    └── content-research-writer/
        ├── SKILL.md
        └── references/
            └── seo-guidelines.md

The skills/ directory holds the file-based and external skills. Inline and meta skills are defined directly in agent.py — no directories needed.

Imports and Dependencies#

The skill imports come from three modules.

# agent.py
import pathlib

from google.adk import Agent
from google.adk.skills import load_skill_from_dir
from google.adk.skills import models
from google.adk.tools.skill_toolset import SkillToolset

• models — Classes for defining skills in code: Skill, Frontmatter, Resources
• load_skill_from_dir — Reads a skill from a directory on disk (SKILL.md + references)
• SkillToolset — Packages one or more skills into a toolset the agent can call

Note

Some external sources show from google.adk.tools.skill import SkillToolset. Both import paths work, but from google.adk.tools.skill_toolset import SkillToolset is the canonical one in the ADK source .

Set your GOOGLE_API_KEY in a .env file in the app/ directory before running. Install dependencies with pip install google-adk python-dotenv.

The skeleton is ready. The next section builds the first skill pattern — the simplest of the four.

Pattern 1: Inline Skills#

An inline skill is the simplest Agent Skills pattern — a Python dictionary defined directly in your agent code with name, description, and instructions keys, ideal for small, project-specific knowledge that doesn’t need external files.

The SEO checklist from the ADK Project Setup table is the simplest case — stable rules that rarely change, defined directly in Python as an inline skill .

# agent.py — Pattern 1: Inline Skill
seo_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="seo-checklist",
        description=(
            "SEO optimization checklist for blog posts. Covers title tags,"
            " meta descriptions, heading structure, keyword placement,"
            " and readability best practices."
        ),
    ),
    instructions=(
        "When optimizing a blog post for SEO, check each item:\n\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. **Keyword density**: 1-2%, never forced or awkward\n"
        "6. **Paragraphs**: 2-3 sentences max, use bullet lists often\n"
        "7. **Links**: 2-3 internal + 3-5 external to authoritative sources\n"
        "8. **Images**: Alt text with keywords, compressed, descriptive names\n"
        "9. **URL slug**: Short, keyword-rich, hyphenated\n\n"
        "Review the content against each item and suggest specific improvements."
    ),
)

The three fields map to the progressive disclosure levels from the previous section:

• frontmatter (L1) — Frontmatter requires two fields, both defined in the agentskills.io spec :

  • name — kebab-case, max 64 characters. Must match the directory name for file-based skills.
  • description — max 1024 characters. This is what the LLM sees during L1 discovery — it decides whether to load the skill based on this text alone. The spec recommends including “specific keywords that help agents identify relevant tasks.” “SEO optimization checklist for blog posts” tells the agent exactly when this skill is useful. “A helpful skill” does not.

• instructions (L2) — The actual knowledge the agent receives when it calls load_skill("seo-checklist"). For this checklist, nine rules in a numbered list is all the agent needs.

• resources (L3, optional) — Reference files embedded as Python strings. Inline skills can attach these for detailed docs, but for a simple checklist, instructions alone are enough. Pattern 4 (in Part 3) uses this to embed the agentskills.io spec itself.

When I asked the agent “Can you review my blog post for SEO?”, it loaded the seo-checklist skill and applied each item systematically.

Inline skills work best for simple, stable rules that don’t need external files. If your skill’s instructions grow beyond a few hundred words, or you need to reference detailed documentation, a file-based skill is a better fit.

Next: File-Based and External ADK Skills#

We’ve covered the conceptual foundation — what progressive disclosure is, why it matters, and how ADK’s SkillToolset implements it — and built the simplest pattern: an inline skill defined entirely in Python.

In Part 2, we move beyond Python strings into real file-based skills with reference documents, external skills from community repos, and wire everything into a working agent with SkillToolset. We’ll also look under the hood at the three auto-generated tools and see multi-skill loading in action. This post is part of the full Agent Engineering series . For more on ADK , check the tag archive.

Continue to Part 2: File-Based, External Skills, and SkillToolset Internals →

Frequently Asked Questions#

What is the difference between MCP tools and Agent Skills? MCP (Model Context Protocol) tools give agents the ability to do things — call APIs, query databases, execute code. Agent Skills give agents knowledge — domain expertise, guidelines, and reference material loaded on demand. They are complementary: an agent uses MCP tools for actions and skills for knowledge.

What are the three levels of progressive disclosure in ADK? Level 1 (L1) is lightweight metadata — just the skill name and description, loaded into every call (~100 tokens per skill). Level 2 (L2) is the full instruction set, loaded only when the agent decides it needs that skill. Level 3 (L3) is supplementary resources like style guides or API references, loaded only for specific subtasks.

How many tokens does progressive disclosure save? For an agent with 10 skills, a monolithic system prompt approach uses approximately 10,000 tokens per call. With progressive disclosure, the agent starts with only ~1,000 tokens of L1 metadata and loads L2/L3 content on demand, reducing baseline context by roughly 90%.

When should I use inline skills vs file-based skills? Use inline skills for small, project-specific knowledge that won’t be reused elsewhere (e.g., a single SEO checklist). Use file-based skills when the knowledge is reusable across projects, needs supplementary files (L3 resources), or should be version-controlled independently.

What are ADK Core Skills? ADK Core Skills are official skills published by Google that teach coding agents (Gemini CLI, Claude Code, Cursor) how to write ADK code. They use the same SKILL.md format and progressive disclosure pattern as SkillToolset — the Tool Wrapper pattern covered in the Design Patterns post . Install them with npx skills add google/adk-docs -y -g.

References#

1. Skills for ADK Agents — Official ADK documentation for SkillToolset and progressive disclosure
2. Agent Skills Specification — The open standard defining SKILL.md format
3. What Are Agent Skills? — Conceptual overview of skills as reusable, agent-agnostic capabilities
4. agentskills/agentskills — Open-source specification repo and reference library
5. skills/models.py — Skill, Frontmatter, Resources class definitions
6. skills_agent sample — Official ADK sample with inline + file-based skills
7. @liamottley_ — “SaaS is being replaced by SKILL.md files” — 562 reactions
8. @Pavan_Belagatti — MCP vs Skills — Clear MCP/Skills differentiation
9. ADK Core Skills — official skills for building ADK agents

This is Part 2 of a 3-part series on building ADK agents with reusable skills.

• ← Part 1: What Are Agent Skills?
• Part 3: Skills That Write Skills — Self-Extending ADK Agents →
• 5 SKILL.md Design Patterns Every ADK Developer Should Know →
• ADK Core Skills — official skills for building ADK agents

In Part 1, we covered progressive disclosure — the L1/L2/L3 pattern that keeps agent context small — and built an inline SEO checklist skill in Python. Inline skills are fast to write, but the knowledge lives only in your code. This post moves beyond Python strings into ADK skills that live on disk, come from community repos, and get wired into a working agent.

By the end of this post, you’ll know how to:

• Load file-based skills from directories with SKILL.md and reference documents
• Integrate external skills from community repositories like awesome-claude-skills
• Wire all skills into a single SkillToolset and understand its three auto-generated tools
• See multi-skill loading in action with ADK Web

Tip

• File-based skills store knowledge as SKILL.md files with YAML frontmatter, making skills reusable and version-controllable
• External skills load from community repos (like awesome-claude-skills), letting you import pre-built expertise
• SkillToolset auto-generates three tools from any skill collection: list_skills, get_skill_details, and load_skill_resource
• ADK validates skill names at import time — duplicate names raise a ValueError immediately, not at runtime

Pattern 2: File-Based ADK Skills#

A file-based skill in ADK is a skill stored as a directory containing a SKILL.md file with YAML frontmatter (name and description) and Markdown instructions, plus optional references/, assets/, and scripts/ subdirectories for L3 resources.

The SEO checklist worked as an inline skill because it was self-contained — nine rules, no external files. The blog writer skill needs more: a style guide with voice rules, formatting conventions, and anti-patterns. That reference document doesn’t belong inline as a Python string. This is where file-based skills pick up.

A file-based skill lives in its own directory with a SKILL.md file and optional subdirectories for references, assets, and scripts. The SKILL.md starts with YAML frontmatter, followed by Markdown instructions.

# skills/blog-writer/SKILL.md
---
name: blog-writer
description: Blog post writing skill with structure templates and style guidelines.
  Guides the agent through writing well-structured, engaging technical blog posts
  with proper formatting, section flow, and reader engagement techniques.
---

# Blog Writer Instructions

When asked to write a blog post, follow these steps:

## Step 1: Structure
Use `load_skill_resource` to read `references/style-guide.md` for the writing style rules.

## Step 2: Outline First
Before writing, create a brief outline with:
- **Hook**: Opening that grabs attention
- **Context**: Why this topic matters now
- **Core sections**: 3-5 sections that build on each other
- **Takeaway**: What the reader walks away knowing
...

The design splits knowledge across two layers. The SKILL.md instructions (L2) tell the agent what steps to follow. The references/style-guide.md file (L3) provides the detailed knowledge for each step — voice guidelines, formatting conventions, anti-patterns to avoid. The agent loads the reference only when its instructions say to, via load_skill_resource.

Important

The directory name must match the name field in SKILL.md frontmatter. blog-writer/ requires name: blog-writer. Mismatches cause a validation error from load_skill_from_dir — no partial matches, no fallbacks.

Loading a file-based skill in Python is one line.

# agent.py — Pattern 2: File-Based Skill
blog_writer_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "blog-writer"
)

When the agent used this skill to write a blog introduction, I could see it first loading the skill instructions (L2), then pulling the style guide via load_skill_resource (L3). The style guide’s influence was visible in the output — short paragraphs, no “In today’s rapidly evolving…” openings, action-oriented headings.

File-based skills make the knowledge reusable — any agent that follows the agentskills.io spec can load the same blog-writer/ directory. But you still wrote the SKILL.md yourself. What if someone else already wrote the skill you need?

Pattern 3: External ADK Skills from Community Repos#

An external skill is a file-based skill loaded from a source outside your project — typically a community repository like awesome-claude-skills — that provides pre-built domain expertise your agent can use without you writing the instructions yourself.

External skills work exactly like file-based skills — the only difference is where the directory came from. Instead of writing your own SKILL.md, you download one from a community repository and load it with the same load_skill_from_dir call.

External skills aren’t limited to community repos. Google publishes official ADK development skills — covering the dev guide, cheatsheet, evaluation, deployment, observability, and scaffolding — installable with npx skills add google/adk-docs -y -g. These are first-party external skills that follow the same agentskills.io spec, loadable via load_skill_from_dir just like the community content-research-writer skill below.

The content-research-writer skill in this agent is adapted from Composio’s awesome-claude-skills repository, which has over 100 production skills for various domains. The workflow for loading an external skill:

1. Find a skill that fits your use case in a community repo
2. Clone or download the skill directory into your project’s skills/ folder
3. Verify the SKILL.md frontmatter is valid (skills-ref validate ./my-skill if you have the validation tool )
4. Review the instructions and reference files — then load it

Warning

A skill’s instructions become your agent’s behavior. Always read the SKILL.md and any reference files before loading an external skill. Treat it like a dependency review — you’re giving the LLM new instructions.

# agent.py — Pattern 3: External Skill
content_researcher_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "content-research-writer"
)

The code is identical to Pattern 2. That’s the point — the agentskills.io spec defines a universal directory format, so load_skill_from_dir doesn’t care whether you wrote the SKILL.md or downloaded it.

The content-research-writer skill includes a 5-phase research methodology with detailed SEO guidelines in references/seo-guidelines.md. All of that knowledge becomes available to the agent with one line of code, no rewriting needed.

File-based and external skills cover most use cases — you either write the skill or find one that exists. But what if the skill you need doesn’t exist in any repo? Part 3 answers that question with a meta skill that generates new skills on demand.

Pattern Summary#

Wiring ADK Skills with SkillToolset#

SkillToolset is ADK’s built-in BaseToolset subclass that converts any collection of Agent Skills into three auto-generated tools — list_skills (returns L1 metadata for all skills), get_skill_details (loads L2 instructions for a specific skill), and load_skill_resource (fetches L3 reference files).

With all four skills defined (inline SEO checklist from Part 1, file-based blog writer, external content researcher, and the meta skill-creator coming in Part 3), the final step is packaging them into a SkillToolset and handing it to the agent.

# agent.py — Assemble and wire up
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\n"
        "You have four skills available:\n"
        "- **seo-checklist**: SEO optimization rules\n"
        "- **blog-writer**: Writing structure and style guide\n"
        "- **content-research-writer**: Research methodology\n"
        "- **skill-creator**: Generate new skill definitions\n\n"
        "When the user asks you to write, research, or optimize:\n"
        "1. Load the relevant skill(s) to get detailed instructions\n"
        "2. Use load_skill_resource to access reference materials\n"
        "3. Follow the skill's step-by-step instructions\n\n"
        "Always explain which skill you're using and why."
    ),
    tools=[skill_toolset],
)

The agent’s instruction explicitly lists the four skills. This overlaps with SkillToolset’s auto-injected listing, but serves a different purpose — the instruction provides a stable hint about the agent’s identity, while the dynamic list_skills injection gives the LLM structured metadata for each request.

Under the Hood: Three Auto-Generated Tools#

SkillToolset is not a regular tool — it’s a BaseToolset , which means its get_tools() method is called on every LLM step. It auto-registers three tools that map directly to progressive disclosure:

• list_skills (L1) — Returns an XML listing of all skill names and descriptions. Injected into the system context automatically via process_llm_request() — the agent never calls it explicitly. Always present, always lightweight.

• load_skill (L2) — Takes a skill name and returns its full instructions plus frontmatter. The agent calls this when it decides a skill is relevant to the current query.

• load_skill_resource (L3) — Takes a skill name and a file path, returning the content of a file from references/, assets/, or scripts/. Detailed knowledge loaded only on demand.

Note

SkillToolset validates skill names at construction time and raises a ValueError if any two skills share the same name. This happens at import time, not at runtime — so you’ll catch duplicates immediately.

Running It: Progressive Disclosure in Action#

Running the agent with ADK Web shows the progressive disclosure pattern visually.

Warning

Use adk web . not adk web app/ — pointing at app/ directly makes ADK discover skills/ as a separate app instead of treating app/ as your app.

When I asked “Help me write a blog introduction and make it SEO-friendly”, the agent loaded both the blog-writer and seo-checklist skills in parallel — without being told to load both. The L1 metadata listing gave it enough context to decide both skills were relevant. It then called load_skill_resource to read the style guide, and produced an introduction that followed both skills’ instructions.

The ADK Web UI makes the flow visible through tool call badges. Each badge shows the tool name and its status (pending → complete). In this interaction, four events fired: load_skill("blog-writer") and load_skill("seo-checklist") in the same turn, followed by load_skill_resource("references/style-guide.md"), and finally the agent’s written response.

The agent’s reasoning is also interesting in the negative case. When I asked “Can you use your video-editing skill to create a thumbnail?”, the agent checked the L1 listing and correctly responded that it has no video-editing skill. It listed all four available skills instead. No hallucination, no attempt to fake a capability it doesn’t have.

Next: ADK Meta Skills That Write Themselves#

We’ve covered skills that exist — skills you write yourself (inline, file-based) or find in community repos (external). We’ve wired them into a SkillToolset and seen multi-skill loading in action. This tutorial is part of the full Agent Engineering series by Lavi Nigam — see more on ADK for related posts.

In Part 3, the agent writes its own skills. We’ll build a meta skill-creator that generates new SKILL.md files on demand, reflect on what skills change about agent behavior, and explore what’s coming next for the pattern.

Continue to Part 3: Skills That Write Skills — Self-Extending ADK Agents →

Frequently Asked Questions#

Can I mix file-based and inline skills in the same SkillToolset? Yes. SkillToolset accepts any list of skill sources. You can combine inline Python dicts, file-based skill directories, and external skill paths in a single skills=[] parameter. The toolset treats them identically once loaded.

What happens if a SKILL.md file has invalid YAML frontmatter? ADK’s skill loader will raise a parsing error at import time, before your agent starts. The frontmatter must include valid YAML with at least name and description fields. Missing or malformed frontmatter prevents the skill from loading.

What are the three tools auto-generated by SkillToolset? list_skills returns L1 metadata (name and description) for all registered skills. get_skill_details loads the full L2 instructions for a specific skill by name. load_skill_resource fetches L3 reference files from a skill’s references/ directory. The agent calls these tools autonomously based on the user’s query.

Is there a size limit for SKILL.md files or L3 resources? The Agent Skills specification does not impose hard size limits, but practical constraints apply. L2 instructions should fit within the model’s context window alongside the conversation. L3 resources are loaded individually, so each file should be self-contained and reasonably sized (a few thousand tokens).

How does SkillToolset handle duplicate skill names? It raises a ValueError at import time if any two skills share the same name field. This happens before the agent starts, so you get an immediate, clear error rather than confusing runtime behavior.

Can I load ADK Core Skills with SkillToolset? Yes. Google publishes official ADK development skills as standard SKILL.md directories. Since they follow the agentskills.io specification, you can load them with load_skill_from_dir exactly like any file-based or external skill. Install with npx skills add google/adk-docs -y -g, then point load_skill_from_dir at the installed directory.

References#

1. Skills for ADK Agents — Official ADK documentation for SkillToolset and progressive disclosure
2. Agent Skills Specification — The open standard defining SKILL.md format, adopted by 40+ agents
3. ADK Overview (Vertex AI) — Google Cloud documentation for Agent Development Kit
4. tools/skill_toolset.py — SkillToolset implementation with auto-generated tools
5. skills/_utils.py — load_skill_from_dir, validation, SKILL.md parsing
6. skills_agent sample — Official ADK sample with inline + file-based skills
7. awesome-claude-skills — 100+ production skills organized by domain
8. content-research-writer — The external skill used in this tutorial
9. ADK Core Skills — official skills for building ADK agents

This is Part 3 of a 3-part series on building ADK agents with reusable skills.

• ← Part 1: What Are Agent Skills?
• ← Part 2: File-Based, External Skills, and SkillToolset Internals
• 5 SKILL.md Design Patterns Every ADK Developer Should Know →
• ADK Core Skills — official skills for building ADK agents

In Parts 1 and 2, we built ADK skills that exist — an inline SEO checklist, file-based and external skills loaded from directories, all wired into a SkillToolset with three auto-generated tools. Part 3 closes the loop: the agent writes its own skills.

By the end of this post, you’ll know how to:

• Build a meta skill that generates new SKILL.md files following the agentskills.io spec
• Understand how self-extending agents change the economics of capability building
• Recognize how skills change agent decision-making, not just knowledge

Tip

• A meta skill teaches the agent to generate new SKILL.md files on demand, following the agentskills.io specification
• Self-extending agents can expand their own capabilities without human intervention by writing and loading new skill definitions at runtime
• Skills change the agent’s decision-making, not just its knowledge — they reshape how the agent approaches problems
• Giorgio Crivellari’s ADK governance skill improved code correctness from 29% to 99%, demonstrating the power of well-structured skills

Pattern 4: ADK Meta Skills That Write SKILL.md Files#

A meta skill is a skill whose purpose is to generate new SKILL.md files — it teaches the agent how to create additional skills on demand, following the agentskills.io specification. An agent equipped with a meta skill becomes self-extending: it can expand its own capabilities without human intervention by writing and loading new skill definitions at runtime.

The first three patterns cover skills that exist — you write them (inline, file-based) or find them (external). Pattern 4 closes the loop: the agent writes new skills itself.

The skill-creator is an inline skill whose instructions explain how to write SKILL.md files, and whose resources contain the agentskills.io specification and a working example. This is where the resources field from Pattern 1 becomes essential.

# agent.py — Pattern 4: Meta Skill
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={
            # Full content in agent.py — abbreviated here for readability
            "skill-spec.md": "# Agent Skills Specification (agentskills.io)...",
            "example-skill.md": "# Example: Code Review Skill...",
        }
    ),
)

The resources embed the agentskills.io spec as skill-spec.md and a working code-review skill as example-skill.md. When asked to create a new skill, the agent loads the skill-creator, reads both references via load_skill_resource, and generates a complete SKILL.md that follows the spec. The pattern is inspired by obra/superpowers’ writing-skills skill , which teaches Claude Code how to write new skills.

Lavi Nigam tested this by asking: “I need a new skill for reviewing Python code for security vulnerabilities. Can you create a SKILL.md for it?” The agent loaded the skill-creator, read the spec and example, and generated a complete python-security-review skill — valid kebab-case naming, structured instructions covering input validation, authentication, and cryptography, and a severity-based reporting format.

A skill is just a SKILL.md file. An LLM can generate text. That means an agent with a skill-writing skill becomes self-extending — it can create new domain expertise on demand, then load it via load_skill_from_dir in the next session. The generated skills follow the same agentskills.io spec, so they work not just in ADK but in any compatible agent.

What Building ADK Skills Taught Me#

Skills change the agent’s decision-making, not just its knowledge. When an agent loads a skill, it doesn’t just gain new information — it gains a new way of approaching problems. The skill reshapes the agent’s reasoning process, not just its reference material.

For a simple SEO review, the agent loaded one skill. For writing, two in parallel. For skill creation, it chained load_skill → load_skill_resource → load_skill_resource → generate. The L1 listing acts as a menu — the agent composes skills based on the task, with no orchestration in the system prompt.

Quality improved more than token usage. With the blog-writer’s style guide as an L3 resource, anti-patterns were eliminated at generation time. Giorgio Crivellari documented a similar effect : his ADK governance skill took code correctness from 29% to 99%.

And the meta skill makes it self-extending — an agent that writes SKILL.md files on demand, following the same agentskills.io spec, working across any compatible agent. Instead of pre-building every capability, build one meta skill and let the agent generate the rest. See more on ADK for related posts.

Warning

When running adk api_server , use adk api_server . not adk api_server app/. ADK looks inside the target directory for sub-applications — if app/ contains a skills/ subdirectory, it discovers “skills” as a separate app instead of treating app/ as your app. Check with curl localhost:8000/list-apps if the agent isn’t loading.

Extending ADK Skills: Scripts, Multi-Agent, and Team Libraries#

Three directions to explore from here:

• Script execution — The ADK source contains a RunSkillScriptTool that executes Python and shell scripts from the scripts/ directory. The docs say “not yet supported,” but the implementation is functional. Skills that can run code, not just provide instructions.
• Multi-agent + Skills — A SequentialAgent pipeline where a researcher agent loads the content-research-writer skill and feeds into a writer agent with the blog-writer skill. SkillToolset becomes a modular knowledge layer across your entire agent system.
• Team skill libraries — Share skills via git repos, version them with tags, load them into any agent that follows the agentskills.io spec. Google does this with official ADK development skills — a curated library installable via npx skills add google/adk-docs -y -g into Gemini CLI, Claude Code, or Cursor. A team-specific library raises the quality floor the way Giorgio’s governance skill did.

Clone the companion repo , install dependencies, set your API key, and run adk web . from the project root to see all four patterns in action. Swap in your own SKILL.md files under app/skills/, or ask the skill-creator to generate one for your domain.

Series Summary#

Across the full Agent Engineering series , we built a blog-writing agent with four progressively more powerful skill patterns:

1. Part 1 — The concept: progressive disclosure (L1/L2/L3), project setup, and inline skills defined in Python
2. Part 2 — The ecosystem: file-based skills with reference docs, external skills from community repos, SkillToolset internals, and multi-skill loading
3. Part 3 — The meta pattern: a skill that writes new skills, self-extending agents, and the quality impact of modular knowledge

The core idea: skills turn a monolithic system prompt into a modular knowledge layer. The agent decides what to load, when to load it, and how to compose multiple skills for complex tasks. That shift — from “everything always present” to “load on demand” — changes not just token efficiency but agent behavior itself.

The ecosystem validates this: Google’s ADK Core Skills use the same SKILL.md format to teach coding agents how to build ADK applications — the specification powering both the tools that write agents and the agents themselves.

Frequently Asked Questions#

Can generated skills be loaded in the same session? Yes. After the meta skill writes a new SKILL.md file to disk, you can add its directory to the SkillToolset and the agent can use it immediately. In practice, reloading the agent with the new skill directory is the cleanest approach.

How do you version-control generated skills? Treat generated SKILL.md files like any other code artifact — commit them to git. The meta skill writes to a designated output directory, and you review and commit the generated files. This preserves the audit trail and lets you refine generated skills over time.

What prevents the agent from generating harmful or incorrect skills? The meta skill’s instructions define the output format and quality constraints. You can add guardrails like requiring specific sections, mandating safety disclaimers, or restricting the domains the agent can generate skills for. The generated SKILL.md files are also human-readable, so you review them before deployment.

Does the meta skill work with models other than Gemini? The meta skill pattern is model-agnostic — it generates text files following the agentskills.io specification. Any LLM that can follow structured output instructions can generate valid SKILL.md files. ADK itself supports multiple model backends.

How do ADK Core Skills relate to the meta skill pattern? ADK Core Skills are official skills covering ADK development, evaluation, deployment, and observability. The meta skill pattern from this post generates new skills on demand. They complement each other: Core Skills provide baseline ADK knowledge, while the meta skill-creator generates domain-specific skills your team needs beyond what Google provides.

References#

1. Skills for ADK Agents — Official ADK documentation for SkillToolset and progressive disclosure
2. Agent Skills Specification — The open standard defining SKILL.md format, adopted by 40+ agents
3. What Are Agent Skills? — Conceptual overview of skills as reusable, agent-agnostic capabilities
4. ADK Overview (Vertex AI) — Google Cloud documentation for Agent Development Kit
5. skills/models.py — Skill, Frontmatter, Resources class definitions
6. tools/skill_toolset.py — SkillToolset implementation with auto-generated tools
7. skills/_utils.py — load_skill_from_dir, validation, SKILL.md parsing
8. skills_agent sample — Official ADK sample with inline + file-based skills
9. awesome-claude-skills — 100+ production skills organized by domain
10. content-research-writer — The external skill used in this tutorial
11. writing-skills (obra/superpowers) — Meta skill-writing pattern that inspired Pattern 4
12. adk-skill (Giorgio Crivellari) — Open-source ADK governance skill
13. Giorgio Crivellari — I Built an Agent Skill for Google’s ADK — 245% quality improvement case study
14. Ravi Chaganti — Google ADK Agent Skills — Practical walkthrough
15. Sid Bharath — The Complete Guide to Google’s ADK
16. Spring AI — Generic Agent Skills — Java ecosystem adopting the spec
17. @antigravity — Intro to Agent Skills — The video that sparked this build (85K views)
18. @liamottley_ — “SaaS is being replaced by SKILL.md files” — 562 reactions
19. @Pavan_Belagatti — MCP vs Skills — Clear MCP/Skills differentiation
20. @dAAAb — 15 Open-Source Agent Skills — 40+ agents supporting agentskills.io
21. @alexalbert__ — Agent Skills as open standard
22. ADK Core Skills — official skills for building ADK agents