Name: google-agents-cli-scaffold
Author: google

This skill should be used when the user wants to "create an agent project", "start a new ADK project", "build me a new agent", "add CI/CD to my project", "add deployment", "enhance my project", or "upgrade my project". Part of the agents-cli skills suite. Covers `agents-cli scaffold create`, `scaffo

Project Scaffolding Guide Requires: agents cli ( uv tool install google agents cli ) — [install uv](https://docs.astral.sh/uv/getting started/installation/index.md) first if needed. Use the agents cli CLI to create new agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding. Prerequisite: Clarify Requirements (MANDATORY for new projects) Before scaffolding a new project, load /google agents cli workflow and complete Phase 0 — clarify the user's requirements before running any scaffold create command. Ask what the agent should do, what tools/APIs it needs, and whether they want a prototype or full deployment. Step 1: Choose Architecture Mapping user choices to CLI flags: Choice CLI flag Retrieval/RAG, sandboxed execution, cross session memory, OAuth consent, guardrails, scheduled runs No flag — these come from clone and study recipes. ADK Python: see the topic index in /google agents cli adk code → references/recipes.md ; on other frameworks, see the agent catalog the framework template ships A2A protocol built into the scaffolded app — scaffold normally ( ADK Python: agent adk python , the default; ADK Go: agent adk go ) Prototype (no deployment) prototype Deployment target deployment target <agent runtime\ cloud run\ gke CI/CD runner cicd runner <github actions\ google cloud build Session storage session type <in memory\ cloud sql\ agent platform sessions Product name mapping Current names (and older names users may say) → CLI values ( vertexai SDK package name unchanged): Agent Runtime in Gemini platform (Agent Engine / Vertex AI Agent Engine / Agent Runtime) → deployment target agent runtime Sessions in Gemini platform (Agent Engine sessions / Agent Platform Sessions) → session type agent platform sessions Search / Vector Search in Gemini platform (Vertex AI Search / Vertex AI Vector Search) / RAG → clone and study recipe, not a flag Removed flags. datastore , the agentic rag template, and agents cli infra datastore / agents cli data ingestion no longer exist. If you reach for one, you want a recipe instead. Step 2: Create or Enhance the Project Create a New Project 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. Pass agent guidance filename for your IDE: GEMINI.md for Antigravity CLI, CLAUDE.md for Claude Code, AGENTS.md otherwise. 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. Reference Files File Contents references/flags.md Full flag reference for create and enhance commands Enhance an Existing Project Run this from inside the project directory (or pass the path instead of . ). Upgrade a Project Upgrade an existing project to a newer agents cli version, intelligently applying updates while preserving your customizations: force is a fallback for when smart merge fails. Smart merge also stops when the agents cli version that created the project is not on PyPI, because it needs that version's template; use force then too. It overwrites scaffolding files with the new template and keeps agent code, config files, README.md , the agent guidance file and eval datasets and config. It never removes dependencies or files the new template dropped (for example, a removed CI workflow), so remove unused ones by hand. Afterwards, check your imports and run your tests. Use dry run first to see which files change. Execution Modes The CLI defaults to strict programmatic mode — all required params must be supplied as CLI flags or a UsageError is raised. No approval flags needed. Pass all required params explicitly. Common Workflows Always ask the user before running these commands. Present the options (CI/CD runner, deployment target, etc.) and confirm before executing. Template Options Template Language Deployment Description adk python Python Agent Runtime, Cloud Run, GKE Standard ADK agent (default); A2A protocol built in adk go Go Agent Runtime, Cloud Run, GKE Standard ADK Go agent; A2A protocol built in adk python and adk go are the only built in templates. adk python is the default, so a Go project needs agent adk go explicitly. adk is accepted as an alias for adk python . Other frameworks ship as template repos you scaffold from directly: agent google/agents cli/extensions/langchain/template@v1.12.0 , with nothing installed. First party templates live in extensions/ ( langchain/template , claude/template ); see /google agents cli workflow → references/extension.md to publish your own. Capabilities beyond the template — retrieval, sandboxed execution, memory, OAuth, guardrails — are clone and study recipes, not templates. ADK Python: see the topic index in /google agents cli adk code → references/recipes.md . Live and voice agents: no template. Scaffold adk python , then follow the conversion checklist in /google agents cli adk code ( references/adk python live.md , "Converting a scaffolded project to Live"). The model swap is one of five edits. Deployment Options Target Description agent runtime Managed by Google (Agent Runtime). Container based — Agent Runtime builds the project Dockerfile. Sessions handled automatically. cloud run Container based deployment. More control; you build and deploy the Dockerfile. gke Container based on GKE Autopilot. Full Kubernetes control. none No deployment scaffolding. Code only (still includes a Dockerfile). "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 scaffold enhance : Agent Runtime and session type When using agent runtime as the deployment target, Agent Runtime manages sessions internally. If your code sets a session type , clear it — Agent Runtime overrides it. Step 3: Load Dev Workflow After scaffolding, immediately load /google agents cli workflow — it contains the development workflow, coding guidelines, and operational rules you must follow when implementing the agent. What you edit differs by language; /google agents cli adk code has the annotated tree for each, in references/adk python.md and references/adk go.md . ADK Python ( agent adk python ) — customize app/agent.py and app/tools.py . ADK Go ( agent adk go ) — customize app/agent.go . .env is yours. Preserve everything else the template generated — it wires up serving, sessions and the built in A2A surface. Adapting a recipe: copy its app/ , infra/terraform/ , and any ingestion or provisioning into your scaffolded project, then run provisioning from the recipe's own Makefile (e.g. make setup infra ). Start from its AGENTS.md . Verifying your agent works: Use agents cli run "test prompt" for quick smoke tests, then agents cli eval run for systematic validation. Do NOT write pytest tests that assert on LLM response content, that belongs in eval. 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/ : 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 the CLI generates before committing to it Critical Rules NEVER skip requirements clarification — load /google agents cli workflow Phase 0 and clarify the user's intent before running scaffold create 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 Runtime clears session type — if deploying to agent runtime , 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 — A2A is built into the scaffolded app (the adk python and adk go templates and framework templates alike); each language's A2A surface (import paths, AgentCard schema etc.) is non trivial and changes across versions. Scaffold normally; never hand write the A2A surface. (The only sanctioned A2A hand edit is removing the generated wiring for a Live agent, which can't be served over A2A — see /google agents cli adk code , references/adk python live.md .) Examples A2A project: User says: "Build me a Python agent that exposes A2A and deploys to Cloud Run" Actions: 1. Follow the standard flow (understand requirements, choose architecture, scaffold) 2. agents cli scaffold create my a2a agent agent adk python deployment target cloud run prototype Result: Valid A2A imports and Dockerfile — no manual A2A code written. Go project: User says: "Build me a Go agent that deploys to Cloud Run" Actions: 1. Follow the standard flow (understand requirements, choose architecture, scaffold) 2. agents cli scaffold create my go agent agent adk go deployment target cloud run prototype Result: Go project with app/agent.go , the launcher in main.go , and the A2A card at the root. Troubleshooting agents cli command not found See /google agents cli workflow → Setup section. Related Skills /google agents cli workflow — Development workflow, coding guidelines, and the build evaluate deploy lifecycle /google agents cli adk code — ADK API quick reference for writing agent code, including the graph Workflow API /google agents cli deploy — Deployment targets, CI/CD pipelines, and production workflows /google agents cli eval — Evaluation methodology, dataset schema, and the eval fix loop