adk-scaffold

SKILL.md

ADK Project Scaffolding Guide

Use the agent-starter-pack CLI (via uvx) to create new ADK agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding.

Step 1: Gather Requirements

Start with the use case, then ask follow-ups based on answers.

Always ask:

What problem will the agent solve? — Core purpose and capabilities

External APIs or data sources needed? — Tools, integrations, auth requirements

Safety constraints? — What the agent must NOT do, guardrails

Deployment preference? — Prototype first (recommended) or full deployment? If deploying: Agent Engine, Cloud Run, or GKE?

Ask based on context:

If retrieval or search over data mentioned (RAG, semantic search, vector search, embeddings, similarity search, data ingestion) → Datastore? Use --agent agentic_rag --datastore <choice>:

vertex_ai_vector_search — for embeddings, similarity search, vector search

vertex_ai_search — for document search, search engine

If agent should be available to other agents → A2A protocol? Use --agent adk_a2a to expose the agent as an A2A-compatible service.

If full deployment chosen → CI/CD runner? GitHub Actions (default) or Google Cloud Build?

If Cloud Run or GKE chosen → Session storage? In-memory (default), Cloud SQL (persistent), or Agent Engine (managed).

If deployment with CI/CD chosen → Git repository? Does one already exist, or should one be created? If creating, public or private?

Step 2: Write DESIGN_SPEC.md

Compose a detailed spec with these sections. Present the full spec for user approval before scaffolding.

# DESIGN_SPEC.md

## Overview
2-3 paragraphs describing the agent's purpose and how it works.

## Example Use Cases
3-5 concrete examples with expected inputs and outputs.

## Tools Required
Each tool with its purpose, API details, and authentication needs.

## Constraints & Safety Rules
Specific rules — not just generic statements.

## Success Criteria
Measurable outcomes for evaluation.

## Edge Cases to Handle
At least 3-5 scenarios the agent must handle gracefully.

The spec should be thorough enough for another developer to implement the agent without additional context.

Step 3: Create or Enhance the Project

Create a New Project

uvx agent-starter-pack create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype \
  -y

Constraints:

Project name must be 26 characters or less, lowercase letters, numbers, and hyphens only.

Do NOT mkdir the project directory before running create — the CLI creates it automatically. If you mkdir first, create will fail or behave unexpectedly.

Auto-detect the guidance filename based on the IDE you are running in and pass --agent-guidance-filename accordingly.

When enhancing an existing project, check where the agent code lives. If it's not in app/, pass --agent-directory <dir> (e.g. --agent-directory agent). Getting this wrong causes enhance to miss or misplace files.

Create Flags

Flag
Short
Default
Description

--agent
-a
adk
Agent template (see template table below)

--deployment-target
-d
agent_engine
Deployment target (agent_engine, cloud_run, gke, none)

--region

us-central1
GCP region

--prototype
-p
off
Skip CI/CD and Terraform (recommended for first pass)

--cicd-runner

skip
github_actions or google_cloud_build

--datastore
-ds
—
Datastore for data ingestion (vertex_ai_search, vertex_ai_vector_search)

--session-type

in_memory
Session storage (in_memory, cloud_sql, agent_engine)

--auto-approve
-y
off
Skip confirmation prompts

--skip-checks
-s
off
Skip GCP/Vertex AI verification checks

--agent-directory
-dir
app
Agent code directory name

--agent-guidance-filename

GEMINI.md
Guidance file name (CLAUDE.md, AGENTS.md)

--debug

off
Enable debug logging for troubleshooting

By default, the scaffolded project uses Google Cloud credentials (Vertex AI). For API key setup and model configuration, see Configuring Gemini models and Supported models.

Enhance an Existing Project

uvx agent-starter-pack enhance . \
  --deployment-target <target> \
  -y

Run this from inside the project directory (or pass the path instead of .). Remember that enhance creates new files (.github/, deployment/, tests/load_test/, etc.) that need to be committed.

Enhance Flags

All create flags are supported, plus:

Flag
Short
Default
Description

--name
-n
directory name
Project name for templating

--base-template
-bt
—
Override base template (e.g. agentic_rag to add RAG)

--dry-run

off
Preview changes without applying

--force

off
Force overwrite all files (skip smart-merge)

Common Workflows

Always ask the user before running these commands. Present the options (CI/CD runner, deployment target, etc.) and confirm before executing.

# Add deployment to an existing prototype
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
uvx agent-starter-pack enhance . --cicd-runner github_actions -y

# Add RAG with data ingestion
uvx agent-starter-pack enhance . --base-template agentic_rag --datastore vertex_ai_search -y

# Preview what would change (dry run)
uvx agent-starter-pack enhance . --deployment-target cloud_run --dry-run -y

Template Options

Template
Deployment
Description

adk
Agent Engine, Cloud Run, GKE
Standard ADK agent (default)

adk_a2a
Agent Engine, Cloud Run, GKE
Agent-to-agent coordination (A2A protocol)

agentic_rag
Agent Engine, Cloud Run, GKE
RAG with data ingestion pipeline

Deployment Options

Target
Description

agent_engine
Managed by Google (Vertex AI Agent Engine). Sessions handled automatically.

cloud_run
Container-based deployment. More control, requires Dockerfile.

gke
Container-based on GKE Autopilot. Full Kubernetes control.

none
No deployment scaffolding. Code only.

"Prototype First" Pattern (Recommended)

Start with --prototype to skip CI/CD and Terraform. Focus on getting the agent working first, then add deployment later with enhance:

# Step 1: Create a prototype
uvx agent-starter-pack create my-agent --agent adk --prototype -y

# Step 2: Iterate on the agent code...

# Step 3: Add deployment when ready
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

Agent Engine and session_type

When using agent_engine as the deployment target, Agent Engine manages sessions internally. If your code sets a session_type, clear it — Agent Engine overrides it.

Step 4: Save DESIGN_SPEC.md and Load Dev Workflow

After scaffolding, save the approved spec from Step 2 to the project root as DESIGN_SPEC.md.

Then immediately load /adk-dev-guide — it contains the development workflow, coding guidelines, and operational rules you must follow when implementing the agent.

Scaffold as Reference

When you need specific files (Terraform, CI/CD workflows, Dockerfile) but don't want to scaffold the current project directly, create a temporary reference project in /tmp/:

uvx agent-starter-pack create /tmp/ref-project \
  --agent adk \
  --deployment-target cloud_run \
  --cicd-runner github_actions \
  -y

Inspect the generated files, adapt what you need, and copy into the actual project. Delete the reference project when done.

This is useful for:

Non-standard project structures that enhance can't handle

Cherry-picking specific infrastructure files

Understanding what ASP generates before committing to it

Critical Rules

NEVER change the model in existing code unless explicitly asked

NEVER mkdir before create — the CLI creates the directory; pre-creating it causes enhance mode instead of create mode

NEVER create a Git repo or push to remote without asking — confirm repo name, public vs private, and whether the user wants it created at all

Always ask before choosing CI/CD runner — present GitHub Actions and Cloud Build as options, don't default silently

Agent Engine clears session_type — if deploying to agent_engine, remove any session_type setting from your code

Start with --prototype for quick iteration — add deployment later with enhance

Project names must be ≤26 characters, lowercase, letters/numbers/hyphens only

NEVER write A2A code from scratch — the A2A Python API surface (import paths, AgentCard schema, to_a2a() signature) is non-trivial and changes across versions. Always use --agent adk_a2a to scaffold A2A projects.

Examples

Using scaffold as reference:
User says: "I need a Dockerfile for my non-standard project"
Actions:

Create temp project: uvx agent-starter-pack create /tmp/ref --agent adk --deployment-target cloud_run -y

Copy relevant files (Dockerfile, etc.) from /tmp/ref

Delete temp project
Result: Infrastructure files adapted to the actual project

A2A project:
User says: "Build me a Python agent that exposes A2A and deploys to Cloud Run"
Actions:

Follow the standard flow (gather requirements, DESIGN_SPEC, scaffold)

uvx agent-starter-pack create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype -y
Result: Valid A2A imports and Dockerfile — no manual A2A code written.

Troubleshooting

uvx command not found

Install uv following the official installation guide.

If uv is not an option, use pip instead:

# macOS/Linux
python -m venv .venv && source .venv/bin/activate
# Windows
python -m venv .venv && .venv\Scripts\activate

pip install agent-starter-pack
agent-starter-pack create <project-name> ...

For all available options, run uvx agent-starter-pack create --help.