google-agents-cli-scaffold

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

bygoogle· 116 skills

Installs

65k

Stars

5.4k

Forks

565

How to install google-agents-cli-scaffold?

google/agents-cli/google-agents-cli-scaffold

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

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/google/agents-cli" --skill "google/agents-cli/google-agents-cli-scaffold"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/google/agents-cli" that are relevant to the current task. Run `npx skills add "https://github.com/google/agents-cli"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# ADK Project Scaffolding Guide
2
3	> Requires: `agents-cli` (`uv tool install google-agents-cli`) — [install uv](https://docs.astral.sh/uv/getting-started/installation/index.md) first if needed.
4
5	Use the `agents-cli` CLI to create new ADK agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding.
6
7	---
8
9	## Prerequisite: Clarify Requirements (MANDATORY for new projects)
10
11	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.
12
13	---
14
15	## Step 1: Choose Architecture
16
17	Mapping user choices to CLI flags:
18
19	\| Choice \| CLI flag \|
20	\|--------\|----------\|
21	\| RAG (vector or document search) \| Not a scaffold flag — clone-and-study `rag-vector-search` / `rag-agent-search` (see `/google-agents-cli-workflow` Phase 1) \|
22	\| A2A protocol \| built into every ADK agent — scaffold normally (`--agent adk`) \|
23	\| Prototype (no deployment) \| `--prototype` \|
24	\| Deployment target \| `--deployment-target <agent_runtime\\|cloud_run\\|gke>` \|
25	\| CI/CD runner \| `--cicd-runner <github_actions\\|google_cloud_build>` \|
26	\| Session storage \| `--session-type <in_memory\\|cloud_sql\\|agent_platform_sessions>` \|
27
28	### Product name mapping
29
30	Older names → CLI values (`vertexai` SDK package name unchanged):
31
32	- Agent Engine / Vertex AI Agent Engine → `--deployment-target agent_runtime`
33	- Agent Engine sessions / Agent Platform Sessions → `--session-type agent_platform_sessions`
34	- Vertex AI Search / Vertex AI Vector Search / RAG → clone-and-study recipe, not a flag (see `/google-agents-cli-workflow` Phase 1)
35
36	---
37
38	## Step 2: Create or Enhance the Project
39
40	### Create a New Project
41
42	```bash
43	agents-cli scaffold create <project-name> \
44	--agent <template> \
45	--deployment-target <target> \
46	--region <region> \
47	--prototype
48	```
49
50	Constraints:
51	- Project name must be 26 characters or less, lowercase letters, numbers, and hyphens only.
52	- Do NOT `mkdir` the project directory before running `create` — the CLI creates it automatically. If you mkdir first, `create` will fail or behave unexpectedly.
53	- 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).
54	- 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.
55
56	### Reference Files
57
58	\| File \| Contents \|
59	\|------\|----------\|
60	\| `references/flags.md` \| Full flag reference for `create` and `enhance` commands \|
61
62	### Enhance an Existing Project
63
64	```bash
65	agents-cli scaffold enhance . --deployment-target <target>
66	agents-cli scaffold enhance . --cicd-runner <runner>
67	```
68
69	Run this from inside the project directory (or pass the path instead of `.`).
70
71	### Upgrade a Project
72
73	Upgrade an existing project to a newer agents-cli version, intelligently applying updates while preserving your customizations:
74
75	```bash
76	agents-cli scaffold upgrade # Upgrade current directory
77	agents-cli scaffold upgrade <project-path> # Upgrade specific project
78	agents-cli scaffold upgrade --dry-run # Preview changes without applying
79	agents-cli scaffold upgrade --auto-approve # Auto-apply non-conflicting changes
80	```
81
82	### Execution Modes
83
84	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.
85
86	### Common Workflows
87
88	Always ask the user before running these commands. Present the options (CI/CD runner, deployment target, etc.) and confirm before executing.
89
90	```bash
91	# Add deployment to an existing prototype (strict programmatic)
92	agents-cli scaffold enhance . --deployment-target agent_runtime
93
94	# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
95	agents-cli scaffold enhance . --cicd-runner github_actions
96	```
97
98	---
99
100	## Template Options
101
102	\| Template \| Deployment \| Description \|
103	\|----------\|------------\|-------------\|
104	\| `adk` \| Agent Runtime, Cloud Run, GKE \| Standard ADK agent (default); A2A protocol built in \|
105
106	> RAG is a clone-and-study recipe, not a template. Build it by studying `rag-vector-search` or
107	> `rag-agent-search` and adapting the sample into your project — see `/google-agents-cli-workflow`
108	> Phase 1.
109
110	---
111
112	## Deployment Options
113
114	\| Target \| Description \|
115	\|--------\|-------------\|
116	\| `agent_runtime` \| Managed by Google (Vertex AI Agent Runtime). Container-based — Agent Engine builds the project Dockerfile. Sessions handled automatically. \|
117	\| `cloud_run` \| Container-based deployment. More control; you build and deploy the Dockerfile. \|
118	\| `gke` \| Container-based on GKE Autopilot. Full Kubernetes control. \|
119	\| `none` \| No deployment scaffolding. Code only (still includes a Dockerfile). \|
120
121	### "Prototype First" Pattern (Recommended)
122
123	Start with `--prototype` to skip CI/CD and Terraform. Focus on getting the agent working first, then add deployment later with `scaffold enhance`:
124
125	```bash
126	# Step 1: Create a prototype
127	agents-cli scaffold create my-agent --agent adk --prototype
128
129	# Step 2: Iterate on the agent code...
130
131	# Step 3: Add deployment when ready
132	agents-cli scaffold enhance . --deployment-target agent_runtime
133	```
134
135	### Agent Runtime and session_type
136
137	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.
138
139	---
140
141	## Step 3: Load Dev Workflow
142
143	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.
144
145	Key files to customize: `app/agent.py` (instruction, tools, model), `app/tools.py` (custom tool functions), `.env` (project ID, location, API keys).
146	Files to preserve: `agents-cli-manifest.yaml` (CLI reads this), deployment configs under `deployment/`, `Makefile`, `app/__init__.py` (the `App(name=...)` must match the directory name — default `app`), and the generated runtime/A2A infra (`app/fast_api_app.py`, `app/app_utils/a2a.py`, `app/app_utils/services.py`, `Dockerfile`) — these wire up serving, sessions, and the built-in A2A surface; don't hand-edit them.
147
148	RAG projects — clone-and-study, not a template:
149	RAG isn't a scaffold option. Build it by studying `rag-vector-search` or `rag-agent-search` (see
150	`/google-agents-cli-workflow` Phase 1) and adapting the sample's `app/`, `infra/terraform/`, and
151	ingestion into your project. Provisioning and ingestion run from the sample's own `Makefile`
152	(`make setup-infra`, `make data-ingestion`).
153
154	Verifying your agent works: Use `agents-cli run "test prompt"` for quick smoke tests, then `agents-cli eval generate` and `agents-cli eval grade` for systematic validation. Do NOT write pytest tests that assert on LLM response content — that belongs in eval.
155
156	---
157
158	## Scaffold as Reference
159
160	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/`:
161
162	```bash
163	agents-cli scaffold create /tmp/ref-project \
164	--agent adk \
165	--deployment-target cloud_run
166	```
167
168	Inspect the generated files, adapt what you need, and copy into the actual project. Delete the reference project when done.
169
170	This is useful for:
171	- Non-standard project structures that `enhance` can't handle
172	- Cherry-picking specific infrastructure files
173	- Understanding what the CLI generates before committing to it
174
175	---
176
177	## Critical Rules
178
179	- NEVER skip requirements clarification — load `/google-agents-cli-workflow` Phase 0 and clarify the user's intent before running `scaffold create`
180	- NEVER change the model in existing code unless explicitly asked
181	- NEVER `mkdir` before `create` — the CLI creates the directory; pre-creating it causes enhance mode instead of create mode
182	- 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
183	- Always ask before choosing CI/CD runner — present GitHub Actions and Cloud Build as options, don't default silently
184	- Agent Runtime clears session_type — if deploying to `agent_runtime`, remove any `session_type` setting from your code
185	- Start with `--prototype` for quick iteration — add deployment later with `enhance`
186	- Project names must be ≤26 characters, lowercase, letters/numbers/hyphens only
187	- NEVER write A2A code from scratch — A2A is built into every Python ADK agent (`adk`); 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.
188
189	---
190
191	# Examples
192
193	Using scaffold as reference:
194	User says: "I need a Dockerfile for my non-standard project"
195	Actions:
196	1. Create temp project: `agents-cli scaffold create /tmp/ref --agent adk --deployment-target cloud_run`
197	2. Copy relevant files (Dockerfile, etc.) from /tmp/ref
198	3. Delete temp project
199	Result: Infrastructure files adapted to the actual project
200
201	---
202
203	A2A project:
204	User says: "Build me a Python agent that exposes A2A and deploys to Cloud Run"
205	Actions:
206	1. Follow the standard flow (understand requirements, choose architecture, scaffold)
207	2. `agents-cli scaffold create my-a2a-agent --agent adk --deployment-target cloud_run --prototype`
208	Result: Valid A2A imports and Dockerfile — no manual A2A code written.
209
210	---
211
212	## Troubleshooting
213
214	### `agents-cli` command not found
215
216	See `/google-agents-cli-workflow` → Setup section.
217
218	---
219
220	## Related Skills
221
222	- `/google-agents-cli-workflow` — Development workflow, coding guidelines, and the build-evaluate-deploy lifecycle
223	- `/google-agents-cli-adk-code` — ADK Python API quick reference for writing agent code
224	- `/google-agents-cli-deploy` — Deployment targets, CI/CD pipelines, and production workflows
225	- `/google-agents-cli-eval` — Evaluation methodology, dataset schema, and the eval-fix loop

6 picks

Type

Run `npx skills use "https://github.com/google/agents-cli" --skill "google/agents-cli/google-agents-cli-scaffold"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/google/agents-cli" that are relevant to the current task. Run `npx skills add "https://github.com/google/agents-cli"` and select the relevant skills, then follow their instructions.

google-agents-cli-scaffold

How to install google-agents-cli-scaffold?

Related

google-agents-cli-scaffold

How to install google-agents-cli-scaffold?

Related