5 Agent Skill Design Patterns Every ADK Developer Should Know

ADK helps developers build, debug, evaluate, and deploy agents. Agent skills help package the repeatable procedures those agents should follow.

Those are different layers. Google's ADK documentation frames Agent Development Kit as an open-source framework for building, debugging, and deploying reliable agents at enterprise scale. OpenAI's Codex skills documentation describes skills as reusable workflow packages with instructions, references, assets, and optional scripts. Let ADK own the agent runtime and let skills own portable workflow expertise.

For ADK developers, an agent skill is not a replacement for LlmAgent, Workflow, tools, callbacks, sessions, or deployment. It is the operating procedure that tells the agent how to perform a repeatable job inside those primitives. If you are building a support triage agent, ADK should expose tools such as ticket search, account lookup, and ticket creation. The skill should define when to search, which source wins when records disagree, how severity is assigned, what evidence must be included, and when the agent must stop for human review.

That distinction matters because ADK projects often start as simple agents with instructions and tools, then grow into multi-agent workflows, persistent sessions, callbacks, evaluation sets, artifacts, and hosted deployments. If every workflow rule lives inside one growing agent instruction, the project becomes hard to test and reuse. If every rule lives inside tool descriptions, the tools become product policy documents instead of small capabilities. Skills give ADK teams a third place to put procedural knowledge.

If you want the broader skill-author version of these patterns, start with 5 Agent Skill Design Patterns for Reliable Workflows. This article adapts the same idea to ADK's runtime model.

1. Runtime/skill boundary
2. Tool contract wrapper
3. State-aware handoff
4. Eval-ready output
5. Human escalation gate

Keep runtime concerns out of the skill and workflow concerns out of the agent core.

ADK is code-first: define agents, connect tools, manage sessions, evaluate behavior, and deploy to environments such as Cloud Run, GKE, Agent Runtime, or other container-friendly infrastructure. Skills should not recreate that runtime. A skill should be small enough that the same workflow could be reused by a Python ADK agent, a TypeScript ADK agent, or another agent host that supports skill-like instruction packages.

ADK's agents documentation also names the scaling pressure clearly: simple agents with models, instructions, and tools are a good starting point, but larger tasks often need workflows to manage instruction length, context limits, modularity, and deterministic execution. Skills complement that move. A workflow decides execution order. A skill defines the procedural standard each step should meet.

ADK-side responsibilities:

• model and agent configuration, including LlmAgent, workflow agents, and sub-agent routing
• tool registration, including function tools, OpenAPI toolsets, MCP toolsets, and built-in tools
• deployment target, auth, secrets, rate limits, and runtime isolation
• session service, memory service, artifact service, and state persistence
• callbacks, logging, tracing, and operational observability
• evaluation harnesses and CI integration

Skill-side responsibilities:

• task purpose
• source priority
• workflow steps
• examples and templates
• completion evidence
• stop rules

This separation prevents every skill from becoming a mini agent framework.

Example: a DevRel team builds an ADK migration-review agent for a new SDK version. The ADK app owns repository access, diff reading, test execution, and comments on pull requests. The skill owns the migration checklist: inspect public API changes first, compare samples against the migration guide, cite changed symbols, mark each finding as blocking or advisory, and do not post a PR comment until tests or a skipped-test reason are included.

The tradeoff is that some workflow rules feel convenient to place directly in the ADK instruction. That is fine for a one-off prototype. Once the rule is reused across agents, teams, or deployment targets, move it into a skill. A good rule of thumb: if the procedure would still matter after switching models or hosting targets, it belongs in the skill.

ADK agents often have access to tools. A skill should not merely repeat tool schemas; it should wrap tools with workflow judgment.

The ADK custom tools documentation describes tools as functions with structured input and output that agents can call to perform actions. The MCP tools specification is a useful cross-framework reference because it treats tools as model-controlled callable actions and recommends visible human control for safety-sensitive operations. A skill sits one layer above the schema: when to call the tool, what to do before calling it, and how to evaluate the result.

Example:

Do not bury business logic inside the tool description if it belongs in a reusable workflow.

For an ADK support agent, the tool layer might expose:

• search_tickets(customer_id, query)
• get_account_plan(customer_id)
• create_ticket(title, body, priority, labels)

The skill should answer the questions the schema cannot answer: search open tickets before creating a duplicate, treat billing-blocked accounts differently from free-tier questions, cite the latest customer message, label a ticket sev1 only when production impact is confirmed, and include the source record IDs in the final answer.

This wrapper pattern becomes more important when an ADK agent uses generated tools from an OpenAPI specification or tools discovered through an MCP server. Generated tools often know endpoint shapes. They usually do not know the team's escalation policy, data freshness requirements, or review standard. That policy belongs in a skill because it can be read, versioned, and improved separately from the API surface.

There is also a performance boundary. ADK's tool performance guidance notes that synchronous tools can block parallel execution. That is a runtime and tool implementation problem. The skill can say "look up account, entitlement, and incident status before answering," but ADK decides whether those calls run concurrently, how timeouts behave, and what gets logged.

ADK developers already think about sessions, state, memory, artifacts, and handoffs. ADK's state documentation describes session.state as the session scratchpad, while Memory Bank with ADK covers longer-term memory across sessions. LangChain's short-term memory documentation is a useful parallel reference: agents need thread-level context, but that context must be managed deliberately.

A state-aware skill should declare:

• which context must be fresh
• which context can be reused
• which state is unsafe to trust
• what must be restated in the final output
• when to clear or ignore prior assumptions
• which durable state keys or artifact names matter to the workflow

Example:

Before using prior account context, verify the account ID and current date.
Do not reuse old pricing, permissions, or plan limits from memory. If the CRM
record is unavailable, mark the recommendation as incomplete.

This lets the runtime manage memory while the skill defines domain-specific trust rules.

ADK makes this especially practical because session state, tool context, callbacks, and artifacts can carry information between steps. A skill can define the trust policy without owning the storage. For example, a procurement approval agent can keep current_vendor_id, approved_budget, and risk_review_status in session state. The skill can say: do not approve a purchase from state alone; reload the vendor record and current budget before writing approval; if the risk review status is older than 30 days, block and request review.

Artifacts deserve the same treatment. ADK artifacts can store named, versioned binary outputs such as files, images, audio, or reports. The runtime should manage artifact storage and versioning. The skill should say which artifact matters and how it should be used: "compare against the latest migration-report.md artifact," "attach the generated CSV to the final answer," or "do not summarize an image artifact until OCR has produced a text artifact."

The failure mode is subtle. If a skill says "remember the customer context" without defining freshness, the agent may reuse stale plan limits, old compliance status, or a prior ticket diagnosis. If the skill says exactly what must be refreshed, ADK can still use memory and state, but the workflow is less likely to invent continuity that is no longer true.

Skill outputs should be easy to test. If an ADK developer wants to evaluate an agent workflow, vague prose is hard to score. Structured output is easier to inspect, compare, and improve.

ADK's evaluation documentation includes criteria such as tool trajectory matching, response similarity, rubric-based response quality, rubric-based tool-use quality, and groundedness checks. Those criteria work better when the skill produces stable, inspectable outputs instead of free-form prose that changes shape every run.

Use this pattern when a skill will power repeated agent behavior.

Eval-ready output includes:

• fixed sections
• required fields
• source citations
• binary completion checks
• severity labels
• explicit skipped checks

Example output contract:

Return:
1. Decision: ship, revise, or block
2. Evidence: 3 cited findings
3. Missing inputs: list or "none"
4. Verification: commands run or reason not run
5. Next action: one concrete owner-action

That shape can be evaluated by humans, scripts, or model graders.

For an ADK pull-request review agent, an eval-ready skill might require:

Return exactly these sections:
1. Summary: one sentence
2. Findings: table with severity, file, line, issue, evidence
3. Tests: commands run and result
4. Not checked: skipped checks with reason
5. Recommendation: approve, request changes, or needs human review

That output gives you multiple evaluation handles. A tool-trajectory eval can check whether the agent read the diff before commenting. A rubric can judge whether findings cite evidence. A groundedness check can catch claims not supported by the repository. A human reviewer can scan the same shape quickly.

Some workflows should not let the agent act without review. The MCP introduction emphasizes connecting AI apps to external systems, tools, data sources, and workflows. ADK also supports action-oriented tools and tool confirmations for workflows that require oversight. Skills should say when capability is not enough.

Escalation triggers:

• destructive action
• customer-visible change
• legal, security, or compliance ambiguity
• missing authoritative source
• low-confidence classification
• irreversible external write

Template:

Prepare the change and evidence, but do not publish, send, delete, charge,
or merge without explicit human approval.

This pattern is especially useful for technical enablement agents that operate near customer docs, code samples, and support workflows.

In ADK, the escalation gate can live at several layers. A tool can request confirmation before it writes. A callback can block or modify behavior at a lifecycle point. The skill can define the domain rule that decides when those mechanisms should fire. Keep those layers separate: the tool implements the pause, the callback enforces a runtime guard, and the skill explains the business condition.

ADK's callback patterns include guardrails, dynamic state management, logging, caching, request modification, step skipping, tool-specific actions, and artifact handling. Those are implementation hooks. The skill should not hide policy inside callback code only. If a callback blocks publishing because a legal review flag is missing, the skill should also state that legal review is required.

For example, a docs-publishing agent may be allowed to open a draft pull request automatically, but not merge it. A support agent may be allowed to draft a refund explanation, but not issue the refund. A security triage agent may gather logs and propose severity, but not notify customers until a human confirms the classification.

Start with the agent boundary:

1. Define what the ADK agent owns: tools, auth, state, deployment.
2. Identify one repeated workflow the agent performs.
3. Write a skill for that workflow.
4. Add an output contract that can be evaluated.
5. Add escalation rules for unsafe actions.
6. Run the workflow against real examples and revise the skill.

This keeps the project modular. You can improve the skill without changing the agent runtime, and you can improve the runtime without rewriting the workflow procedure.

The most useful first skill is usually not the broadest one. Pick a workflow that already repeats and already has failure pain: support triage, release-note review, incident update drafting, API migration review, sales-call account brief creation, or onboarding checklist coordination. If the workflow cannot be described in one sentence, split it before turning it into a skill. A focused skill is easier to evaluate and safer to wire into tools.

If you are new to skills, What Is an Agent Skill? gives the foundation: prompt asks for an answer, tool gives a capability, skill defines a repeatable job. For implementation, How to Write an Agent Skill That Actually Works covers source order, evidence, references, and stop rules that map cleanly into ADK projects.

ADK implementation checklist

Use this checklist when deciding whether a workflow rule belongs in ADK code, a tool, or a skill.

That table is the core design move. Keep the runtime executable, keep tools narrow, and keep procedure reviewable.

ADK builds the agent environment. Agent skills package the reusable operating procedures inside that environment. The best ADK projects keep those layers separate: runtime boundary, tool contract, state trust rules, eval-ready output, and human escalation. That gives developers a practical architecture: ADK executes the workflow, tools expose capabilities, and skills make the work repeatable enough to test, review, share, and improve.