Skip to content
Agents CLI Project Scaffolding

Agents CLI Project Scaffolding Skill

Google's agents-cli skill for creating, enhancing and upgrading ADK agent projects: scaffold create with the adk_python or adk_go template, deployment targets (Agent Runtime, Cloud Run, GKE), CI/CD runners and a prototype-first workflow.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from google/agents-cli.

$ npx skills add google/agents-cli --skill google-agents-cli-scaffold

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/google-agents-cli-scaffold/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/google/agents-cli.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/google-agents-cli-scaffold ~/.claude/skills/google-agents-cli-scaffold

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/google-agents-cli-scaffold/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • agents-cli scaffold create, enhance and upgrade commands
  • adk_python and adk_go templates with A2A built in; extension templates such as LangChain
  • Deployment targets: Agent Runtime, Cloud Run and GKE, plus GitHub Actions or Cloud Build CI/CD
  • Prototype-first workflow: --prototype now, scaffold enhance later
  • Smart-merge upgrades with dry-run, auto-approve and force fallbacks
  • Maps legacy Vertex AI product names to current CLI flags

Agents CLI Project Scaffolding is the skill in Google's google/agents-cli suite that owns project setup. It teaches an agent to use the agents-cli scaffold commands to start a new Agent Development Kit (ADK) project, add deployment or CI/CD to an existing one, or upgrade a project to a newer agents-cli release, and it hands agent code to google-agents-cli-adk-code and deployment operations to google-agents-cli-deploy.

For a new project the agent must first clarify requirements through the google-agents-cli-workflow skill. It then maps the user's choices to flags: --agent adk_python (the default) or adk_go, --deployment-target agent_runtime, cloud_run or gke, --cicd-runner github_actions or google_cloud_build, a session store, and --prototype to skip Terraform and CI/CD. It translates older product names (Vertex AI Agent Engine and similar) into current flag values, notes removed flags, and explains that retrieval, sandboxed execution, memory, OAuth and guardrails come from clone-and-study recipes rather than templates; third-party templates such as LangChain are scaffolded from the google/agents-cli-extensions repository.

It lists the practical constraints: project names of at most 26 lowercase characters, never creating the directory first, passing the right guidance filename (CLAUDE.md, GEMINI.md or AGENTS.md) and --agent-directory when code is not in app/. Upgrades use smart-merge, with --dry-run, --auto-approve and --force as fallbacks. It recommends a prototype-first path, checking an agent with agents-cli run and agents-cli eval run rather than pytest assertions on model output, and scaffolding a throwaway reference project in /tmp to borrow Terraform or CI files. Requires agents-cli (uv tool install google-agents-cli). Apache-2.0.

SKILL.md

The instructions your agent loads, as published by Google.

SKILL.md
name
google-agents-cli-scaffold
description
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`, `scaffold enhance`, and `scaffold upgrade` commands, template options, deployment targets, and the prototype-first workflow. Do NOT use for writing agent code (ADK projects: use google-agents-cli-adk-code) or deployment operations (use google-agents-cli-deploy).
metadata
author: Google license: Apache-2.0 version: 1.15.0 requires: bins: - agents-cli install: "uv tool install google-agents-cli"

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:

ChoiceCLI flag
Retrieval/RAG, sandboxed execution, cross-session memory, OAuth consent, guardrails, scheduled runsNo 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 protocolbuilt 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
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.
  • 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
FileContents
references/flags.mdFull 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
agents-cli scaffold upgrade --force        # Overwrite scaffolding files when smart-merge fails
agents-cli scaffold upgrade --force --dry-run  # List what --force would overwrite

--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.

# 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
TemplateLanguageDeploymentDescription
adk_pythonPythonAgent Runtime, Cloud Run, GKEStandard ADK agent (default); A2A protocol built in
adk_goGoAgent Runtime, Cloud Run, GKEStandard 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. adk is an alias for adk_python.
Other frameworks and third-party templates ship as template repos you scaffold
from directly: --agent google/agents-cli-extensions/core/langchain/template, with nothing installed. First-party
templates live in the google/agents-cli-extensions repo under core/ (core/langchain/template,
core/claude/template); the old copies in google/agents-cli/extensions/ are deprecated. 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
TargetDescription
agent_runtimeManaged by Google (Agent Runtime). Container-based — Agent Runtime builds the project Dockerfile. Sessions handled automatically.
cloud_runContainer-based deployment. More control; you build and deploy the Dockerfile.
gkeContainer-based on GKE Autopilot. Full Kubernetes control.
noneNo deployment scaffolding. Code only (still includes a Dockerfile).

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_python --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.

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

agents-cli scaffold create ref-project --output-dir /tmp \
  --agent adk_python \
  --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_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.

---

  • /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
Install

Google's skill for writing agent code with the Agent Development Kit (ADK) in Python or Go: agent types, tools, callbacks, state, multi-agent orchestration, the graph Workflow API and a catalogue of reference recipes, used with agents-cli.

Netlify's official deploy skill: netlify.toml deploy contexts and their precedence, CLI and drag-and-drop deploys, Deploy Previews, build hooks, skew protection, and secrets-scanning build failures.

Browse all skills →