google-agents-cli-scaffold

Starts an agent project with the parts nobody enjoys writing already in place: the files that ship it to the cloud, the test harness, the release pipeline. Existing projects can be topped up with the pieces they are missing.

WHEN TO USE

SCOPE

USE FOR

Create a new Agent Development Kit project with a chosen deployment target and session storage.
Add deployment or CI/CD scaffolding to an existing agent prototype.
Upgrade a scaffolded project to a newer agents-cli version without losing customizations.
Generate a throwaway reference project just to copy out its Dockerfile or Terraform files.
Pick the right deployment-target and CI/CD-runner flags for a new project.

NOT FOR

Writing the agent's own code after the project exists — that's google-agents-cli-adk-code.
Running or troubleshooting an actual deployment — that's google-agents-cli-deploy.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (12)

Project Scaffolding Guide

Requires: agents-cli (uv tool install google-agents-cli) — install uv 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: see the topic index in `/google-agents-cli-adk-code` → `references/samples.md`; on other frameworks, see the sample index the framework template ships
A2A protocol	built into the scaffolded app — scaffold normally (ADK: `--agent adk`, the default)
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

Older names → CLI values (vertexai SDK package name unchanged):

Agent Engine / Vertex AI Agent Engine → --deployment-target agent_runtime
Agent Engine sessions / Agent Platform Sessions → --session-type agent_platform_sessions
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

agents-cli scaffold create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype

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 (GEMINI.md for Antigravity CLI, CLAUDE.md for Claude Code, AGENTS.md for OpenAI Codex/other).
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

agents-cli scaffold enhance . --deployment-target <target>
agents-cli scaffold enhance . --cicd-runner <runner>

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:

agents-cli scaffold upgrade                # Upgrade current directory
agents-cli scaffold upgrade <project-path> # Upgrade specific project
agents-cli scaffold upgrade --dry-run      # Preview changes without applying
agents-cli scaffold upgrade --auto-approve  # Auto-apply non-conflicting changes

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.

# Add deployment to an existing prototype (strict programmatic)
agents-cli scaffold enhance . --deployment-target agent_runtime

# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
agents-cli scaffold enhance . --cicd-runner github_actions

Template Options

Template	Deployment	Description
`adk`	Agent Runtime, Cloud Run, GKE	Standard ADK agent (default); A2A protocol built in

adk is the only built-in template. Other frameworks ship as template repos you scaffold from directly: --agent google/agents-cli/extensions/langchain/template@v1.5.0, with nothing installed. The first-party LangChain template is extensions/langchain/template/ in the agents-cli repo; 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: see the topic index in /google-agents-cli-adk-code → references/samples.md.

Deployment Options

Target	Description
`agent_runtime`	Managed by Google (Vertex AI Agent Runtime). Container-based — Agent Engine 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:

# Step 1: Create a prototype
agents-cli scaffold create my-agent --agent adk --prototype

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

# Step 3: Add deployment when ready
agents-cli scaffold enhance . --deployment-target agent_runtime

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.

Key files to customize: app/agent.py (instruction, tools, model), app/tools.py (custom tool functions), .env (project ID, location, API keys). Files to preserve: agents-cli-manifest.yaml (CLI reads this), deployment configs under deployment/, Makefile, and the generated runtime/A2A infra (app/fast_api_app.py, Dockerfile, and whatever your template puts under app/app_utils/) — these wire up serving, sessions, and the built-in A2A surface; don't hand-edit them. ADK: app/__init__.py (the App(name=...) must match the directory name — default app), app/app_utils/a2a.py, app/app_utils/services.py.

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/:

agents-cli scaffold create ref-project --output-dir /tmp \
  --agent adk \
  --deployment-target cloud_run

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 template and framework templates alike); the A2A Python API surface (import paths, AgentCard schema, to_a2a() signature) is non-trivial and changes across versions. Scaffold normally; never hand-write the A2A surface.

Examples

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

Create temp project: agents-cli scaffold create ref --output-dir /tmp --agent adk --deployment-target cloud_run
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 (understand requirements, choose architecture, scaffold)
agents-cli scaffold create my-a2a-agent --agent adk --deployment-target cloud_run --prototype Result: Valid A2A imports and Dockerfile — no manual A2A code written.

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 Python API quick reference for writing agent code (ADK projects)
/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

Local tool required

1 FOR YOU · 1 FOR THE AGENT

All items below are required.

01
Install agents-cli through uv
Run uv tool install google-agents-cli, installing uv first if it isn't already present, to get the agents-cli scaffold command.
```
uv tool install google-agents-cli
```
02
Settle the project's requirements first
Clarify what the agent should do, what tools or APIs it needs, and whether it's a prototype or a full deployment before running scaffold create — see google-agents-cli-workflow's Phase 0.

Listed as free: Connected services may require an account or charge fees.
Installation: One command — usually under 2 minutes.

This skill ships inside the Google Agents CLI plugin.

Incomplete alone

Installing just this skill adds only its own folder. Its instructions also call for other plugin components, such as shared scripts, reference files or other skills, which aren't included. Installing the Google Agents CLI plugin as a whole includes what's missing.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add google/agents-cli --skill "google-agents-cli-scaffold" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub

Same repository

google-agents-cli-adk-code
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management", or needs ADK (Agent Development Kit) Python API patterns and code examples. Part of the Google ADK skills suite. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).Read full description
google-agents-cli-deploy
This skill should be used when the user wants to "deploy an agent", "deploy my ADK agent", "set up CI/CD", "configure secrets", "troubleshoot a deployment", or needs guidance on Agent Runtime, Cloud Run, or GKE deployment targets, or binding an agent to an Agent Gateway. Covers deployment workflows, service accounts, rollback, and production infrastructure. Applies to any framework agents-cli deploys (ADK, LangChain, ...). Part of the agents-cli skills suite. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), evaluation (use google-agents-cli-eval), or project scaffolding (use google-agents-cli-scaffold).Read full description
google-agents-cli-eval
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Agent Platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).Read full description
google-agents-cli-observability
This skill should be used when the user wants to "set up tracing", "monitor my agent", "configure logging", "add observability", "debug production traffic", or needs guidance on monitoring deployed agents, including ADK (Agent Development Kit) agents. Covers Cloud Trace, prompt-response logging, BigQuery Agent Analytics, third-party integrations (AgentOps, Phoenix, MLflow, etc.), and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment setup (use google-agents-cli-deploy) or API code patterns (use google-agents-cli-adk-code).Read full description
google-agents-cli-publish
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini Enterprise", "publish to Gemini Enterprise", or needs guidance on the agents-cli publish gemini-enterprise command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).Read full description
google-agents-cli-workflow
This skill should be used when the user wants to "develop an agent", "build an agent using ADK", "run the agent locally", "debug agent code", "test an agent", "deploy an agent", "publish an agent", "monitor an agent", or needs the ADK (Agent Development Kit) development lifecycle and coding guidelines. Entrypoint for building ADK agents. Always active — provides the full workflow (scaffold, build, evaluate, deploy, publish, observe), code preservation rules, model selection guidance, and troubleshooting steps for ADK or any agent development.Read full description