/google-agents-cli-scaffold

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.6.1
  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](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/samples.md`; on other frameworks, see the sample index the framework template ships | | A2A protocol | built into the scaffolded app — scaffold normally (**ADK Python:** `--agent adk`, 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

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 | Language | Deployment | Description | |----------|----------|------------|-------------| | `adk` | 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` and `adk_go` are the only built-in templates.** `adk` is the default, so a Go project > needs `--agent adk_go` explicitly. > Other frameworks ship as template repos you scaffold > from directly: `--agent google/agents-cli/extensions/langchain/template@v1.6.1`, with nothing installed. The first-party LangChain > template is `ext