adk-scaffold
MUST READ before creating or enhancing any ADK agent project. Use when the user wants to build a new agent (e.g. "build me a search agent") or enhance an existing project (e.g. "add CI/CD to my project", "add RAG").
- Installs
- 2.6K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/google/adk-docs --skill adk-scaffold- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads adk-scaffold automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 searchvertex_ai_search— for document search, search engine
- If agent should be available to other agents → A2A protocol? Use
--agent adk_a2ato 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
mkdirthe project directory before runningcreate— the CLI creates it automatically. If you mkdir first,createwill fail or behave unexpectedly. - Auto-detect the guidance filename based on the IDE you are running in and pass
--agent-guidance-filenameaccordingly. - 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
enhancecan'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
mkdirbeforecreate— 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 anysession_typesetting from your code - Start with
--prototypefor quick iteration — add deployment later withenhance - Project names must be ≤26 characters, lowercase, letters/numbers/hyphens only
- NEVER write A2A code from scratch — the A2A Python API surface (import paths,
AgentCardschema,to_a2a()signature) is non-trivial and changes across versions. Always use--agent adk_a2ato 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 -yResult: 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.
FAQ
What does the adk-scaffold skill do?
MUST READ before creating or enhancing any ADK agent project. Use when the user wants to build a new agent (e.g. "build me a search agent") or enhance an existing project (e.g. "add CI/CD to my project", "add RAG").
How do I install adk-scaffold?
Run npx skills add https://github.com/google/adk-docs --skill adk-scaffold in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/adk-scaffold/ (personal) or .claude/skills/adk-scaffold/ (project).
Which AI agents can use adk-scaffold?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is adk-scaffold safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains adk-scaffold?
It is published by google in google/adk-docs. It has 2,645 recorded installs.
More from google/adk-docs
adk-dev-guide
google/adk-docs
ALWAYS ACTIVE — read at the start of any ADK agent development session. ADK development lifecycle and mandatory coding guidelines — spec-driven workflow, code preservation rules, model selection, and troubleshooting.
adk-cheatsheet
google/adk-docs
MUST READ before writing or modifying ADK agent code. ADK API quick reference for Python — agent types, tool definitions, orchestration patterns, callbacks, and state management. Includes an index of all ADK documentation pages. Do NOT use for creating new projects (use adk-scaffold).
adk-eval-guide
google/adk-docs
MUST READ before running any ADK evaluation. ADK evaluation methodology — eval metrics, evalset schema, LLM-as-judge, tool trajectory scoring, and common failure causes. Use when evaluating agent quality, running adk eval, or debugging eval results. Do NOT use for API code patterns (use adk-cheatsheet), deployment (use adk-deploy-guide), or project scaffolding (use adk-scaffold).
adk-deploy-guide
google/adk-docs
MUST READ before deploying any ADK agent. ADK deployment guide — Agent Engine, Cloud Run, GKE, CI/CD pipelines, secrets, observability, and production workflows. Use when deploying agents to Google Cloud or troubleshooting deployments. Do NOT use for API code patterns (use adk-cheatsheet), evaluation (use adk-eval-guide), or project scaffolding (use adk-scaffold).
adk-observability-guide
google/adk-docs
MUST READ before setting up observability for ADK agents or when analyzing production traffic, debugging agent behavior, or improving agent performance. ADK observability guide — Cloud Trace, prompt-response logging, BigQuery Agent Analytics, third-party integrations, and troubleshooting. Use when configuring monitoring, tracing, or logging for agents, or when understanding how a deployed agent handles real traffic.
integration-review
google/adk-docs
Open the skill to read its SKILL.md instructions.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.