adk-dev-guide

SKILL.md

ADK Development Workflow & Guidelines

Session Continuity

If this is a long session, re-read the relevant skill before each phase —
/adk-cheatsheet before writing code, /adk-eval-guide before running evals,
/adk-deploy-guide before deploying, /adk-scaffold before scaffolding.
Context compaction may have dropped earlier skill content.

DESIGN_SPEC.md — Your Primary Reference

IMPORTANT: If DESIGN_SPEC.md exists in this project, it is your primary source of truth.
Read it FIRST to understand:

Functional requirements and capabilities

Success criteria and quality thresholds

Agent behavior constraints

Expected tools and integrations

The spec is your contract. All implementation decisions should align with it. When in doubt, refer back to DESIGN_SPEC.md.

Phase 1: Understand the Spec

Before writing any code:

Read DESIGN_SPEC.md thoroughly

Identify the core capabilities required

Note any constraints or things the agent should NOT do

Understand success criteria for evaluation

Phase 2: Build and Implement

Implement the agent logic:

Write/modify code in the agent directory (check the agent guidance file, e.g. GEMINI.md or CLAUDE.md, for directory name)

Use make playground (or adk web .) for interactive testing during development

Iterate on the implementation based on user feedback

For ADK API patterns and code examples, use /adk-cheatsheet.

Phase 3: Evaluate

This is the most important phase. Evaluation validates agent behavior end-to-end using evalsets and scoring metrics.

MANDATORY: Activate /adk-eval-guide before running evaluation. It contains the evalset schema, config format, and critical gotchas. Do NOT skip this.

Tests (pytest) are NOT evaluation. They test code correctness but say nothing about whether the agent behaves correctly. Always run adk eval.

Start small: Begin with 1-2 sample eval cases, not a full suite

Run evaluations: adk eval (or make eval if the project has a Makefile)

Discuss results with the user

Fix issues and iterate on the core cases first

Only after core cases pass, add edge cases and new scenarios

Repeat until quality thresholds are met

Expect 5-10+ iterations here.

Phase 4: Deploy

Once evaluation thresholds are met:

Deploy when ready — see /adk-deploy-guide for deployment options

IMPORTANT: Never deploy without explicit human approval.

Operational Guidelines for Coding Agents

Principle 1: Code Preservation & Isolation

When executing code modifications, your paramount objective is surgical precision. You must alter only the code segments directly targeted by the user's request, while strictly preserving all surrounding and unrelated code.

Mandatory Pre-Execution Verification:

Before finalizing any code replacement, verify:

Target Identification: Clearly define the exact lines or expressions to be changed, based solely on the user's explicit instructions.

Preservation Check: Ensure all code, configuration values (e.g., model, version, api_key), comments, and formatting outside the identified target remain identical.

Example:

User Request: "Change the agent's instruction to be a recipe suggester."

Incorrect (VIOLATION):
root_agent = Agent(
    name="recipe_suggester",
    model="gemini-1.5-flash",  # UNINTENDED - model was not requested to change
    instruction="You are a recipe suggester."
)

Correct (COMPLIANT):
root_agent = Agent(
    name="recipe_suggester",  # OK, related to new purpose
    model="gemini-3-flash-preview",  # PRESERVED
    instruction="You are a recipe suggester."  # OK, the direct target
)

Principle 2: Execution Best Practices

Model Selection — CRITICAL:

NEVER change the model unless explicitly asked. If the code uses gemini-3-flash-preview, keep it as gemini-3-flash-preview. Do NOT "upgrade" or "fix" model names.

When creating NEW agents (not modifying existing), use Gemini 3 series: gemini-3-flash-preview, gemini-3-pro-preview.

Do NOT use older models (gemini-2.0-flash, gemini-1.5-flash, etc.) unless the user explicitly requests them.

Location Matters More Than Model:

If a model returns a 404, it's almost always a GOOGLE_CLOUD_LOCATION issue (e.g., needing global instead of us-central1).

Changing the model name to "fix" a 404 is a violation — fix the location instead.

Some models (like gemini-3-flash-preview) require specific locations. Check the error message for hints.

ADK Built-in Tool Imports (Precision Required):

# CORRECT - imports the tool instance
from google.adk.tools.load_web_page import load_web_page

# WRONG - imports the module, not the tool
from google.adk.tools import load_web_page

Pass the imported tool directly to tools=[load_web_page], not tools=[load_web_page.load_web_page].

Running Python Commands:

Always use uv to execute Python commands (e.g., uv run python script.py)

Run make install (or uv sync) before executing scripts

Consult Makefile and README.md for available commands (if present)

Breaking Infinite Loops:

Stop immediately if you see the same error 3+ times in a row

Don't retry failed operations — fix the root cause first

RED FLAGS: Lock IDs incrementing, names appending v5->v6->v7, "I'll try one more time" repeatedly

State conflicts (Error 409: Resource already exists): Import existing resources with terraform import instead of retrying creation

Tool bugs: Fix source code bugs before continuing — don't work around them

When stuck: Run underlying commands directly (e.g., terraform CLI) instead of calling problematic tools

Troubleshooting:

Check /adk-cheatsheet first — it covers most common patterns

Search the installed ADK package with Glob/Grep/Read (find it with python -c "import google.adk; print(google.adk.__path__[0])" — use uv run python if using uv)

For ADK docs index, use curl https://adk.dev/llms.txt

For framework questions or GCP products, check official documentation

When encountering persistent errors, a targeted Google Search often finds solutions faster

Scaffold as Reference

When you need specific infrastructure files but don't want to scaffold the current project directly, use the /adk-scaffold skill to create a temporary reference project in /tmp/ and copy over what you need.

See /adk-scaffold for full CLI commands and options.

Development Commands

Projects created via the Agent Starter Pack CLI include a Makefile with these commands.
To create or enhance a project, see the /adk-scaffold skill for full instructions.
For non-scaffolded projects, use the ADK CLI equivalents.

Make (scaffolded)
ADK CLI equivalent
Purpose

make playground
adk web .
Interactive local testing

make test
pytest
Run unit and integration tests

make eval
adk eval <agent_dir> <evalset>
Run evaluation against evalsets

make lint
ruff check .
Check code quality

make setup-dev-env
— (scaffolded only)
Set up dev infrastructure (Terraform)

make deploy
— (scaffolded only)
Deploy to dev (requires human approval)

Skills Version

Troubleshooting hint: If you encounter repeated errors, unexpected tool
failures, or instructions in these skills that seem incomplete or reference
features you can't find, the skills may be outdated. Run:

npx skills check -g

If it reports outdated skills, tell the user to update:

npx skills update -g

Do NOT run this check on every session — only when you suspect stale skills
are causing problems.