google-agents-cli-workflow

Name: google-agents-cli-workflow
Author: google

bygoogle· 116 skills

Installs

65k

Stars

5.4k

Forks

565

How to install google-agents-cli-workflow?

google/agents-cli/google-agents-cli-workflow

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

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-workflow"` 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	# Agent Development Workflow & Guidelines
2
3	agents-cli is a CLI and skills toolkit for building, evaluating, and deploying agents on Google Cloud. It works with any coding agent — Antigravity CLI, Claude Code, Codex, or others — and with the agent framework of your choice (the [Agent Development Kit (ADK)](https://adk.dev/) by default). Install with `uvx google-agents-cli setup`.
4
5	> Before writing agent code, make sure a scaffolded project exists (see Phase 2). Skipping scaffolding loses eval boilerplate, CI/CD config, and project conventions.
6
7
8	> Requires: google-agents-cli ~= 1.2.1
9	> If version is behind, run: uv tool install "google-agents-cli~=1.2.1"
10
11	> Check version: agents-cli info
12	> [Install uv](https://docs.astral.sh/uv/getting-started/installation/index.md) first if needed.
13
14	## Session Continuity & Skill Cross-References
15
16	Re-read the relevant skill before each phase — not after you've already started and hit a problem. Context compaction may have dropped earlier skill content. If skills are not available, run `uvx google-agents-cli setup` to install them.
17
18	\| Phase \| Skill \| When to load \|
19	\|-------\|-------\|--------------\|
20	\| 0 — Understand \| — \| No skill needed — read `.agents-cli-spec.md` if present, else clarify goals with the user \|
21	\| 1 — Study samples \| — \| Check the Notable Samples catalog in `references/samples.md` — clone and study matching samples before scaffolding \|
22	\| 2 — Scaffold \| `/google-agents-cli-scaffold` \| Before creating or enhancing a project \|
23	\| 3 — Build \| `/google-agents-cli-adk-code` \| Before writing agent code — API patterns, tools, callbacks, state \|
24	\| 4 — Evaluate \| `/google-agents-cli-eval` \| Before running any eval — dataset schema, metrics, eval-fix loop \|
25	\| 5 — Deploy \| `/google-agents-cli-deploy` \| Before deploying — target selection, troubleshooting 403/timeouts \|
26	\| 6 — Publish \| `/google-agents-cli-publish` \| After deploying, if registering with Gemini Enterprise (optional) \|
27	\| 7 — Observe \| `/google-agents-cli-observability` \| After deploying — traces, logging, monitoring setup \|
28
29	---
30
31	## Setup
32
33	If `agents-cli` is not installed:
34	```bash
35	uv tool install google-agents-cli
36	```
37
38	### `uv` command not found
39
40	Install `uv` following the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/index.md).
41
42	### Product name mapping
43
44	Users name products inconsistently (Vertex AI → Agent Platform, Agent Engine → Agent Runtime, etc.). Map user terms to CLI values using `references/terminology.md`.
45
46	---
47
48	## Phase 0: Understand
49
50	Before writing or scaffolding anything, understand what you're building — through a design dialogue, not a checklist. Load `references/brainstorming.md` and follow it: ask one question at a time, propose 2–3 architecture approaches for non-trivial agents, and validate the design before any scaffolding.
51
52	If `.agents-cli-spec.md` exists in the current directory, read it — it is your primary source of truth. Otherwise:
53
54	Do NOT proceed to planning, scaffolding, or coding until the user approves the spec. Do not assume, research, or fill in the blanks yourself — the user's intent drives everything.
55
56	Scale the ceremony to complexity: a trivial agent (single tool, fixed persona) needs only a couple of questions, a 2–3 sentence spec, and one approval; a complex agent (multi-agent, RAG, external APIs/auth, safety-critical) gets the full treatment in `references/brainstorming.md`.
57
58	Topics to cover (one question at a time, adapting to the user — see the playbook):
59
60	1. What problem will the agent solve? — Core purpose and capabilities
61	2. External APIs or data sources needed? — Tools, integrations, auth requirements
62	3. Safety constraints? — What the agent must NOT do, guardrails
63	4. Deployment preference? — Prototype first (recommended) or full deployment? If deploying: Agent Runtime, Cloud Run, or GKE?
64
65	Ask based on context:
66
67	- If the agent needs retrieval/search over data (RAG, semantic/vector search, embeddings) → RAG is a clone-and-study recipe, not a scaffold flag. In Phase 1, study `rag-vector-search` (embeddings / similarity search) or `rag-agent-search` (managed document search) from `references/samples.md` and adapt one into your project.
68	- If agent should be available to other agents → A2A protocol is built into every Python agent scaffolded by agents-cli; no separate choice needed — just scaffold normally.
69	- If full deployment chosen → CI/CD runner? GitHub Actions (default) or Google Cloud Build?
70	- If agent should remember user preferences or facts across sessions → Memory Bank? Long-term memory across conversations. See `/google-agents-cli-adk-code`.
71	- If Cloud Run or GKE chosen → Session storage? In-memory (default), Cloud SQL (persistent), or Agent Platform Sessions (managed).
72	- If deployment with CI/CD chosen → Git repository? Does one already exist, or should one be created? If creating, public or private?
73
74	Once the design is agreed, write the spec to `.agents-cli-spec.md` using the template in `references/spec-template.md`, self-review it, then get the user's approval. See `/google-agents-cli-scaffold` for how these choices map to CLI flags.
75
76	Once you have a clear understanding, proceed to Phase 1.
77
78	## Phase 1: Study Reference Samples
79
80	Ask yourself: is there a sample that can help me design this and cut time? Scan the keyword-indexed catalog in `references/samples.md` — it lists the samples and how to clone one. Multiple samples can match — clone and study all that are relevant.
81
82	If no sample matches, proceed to Phase 2. But first — are you sure? Re-read the user's request and compare it against the sample catalog in `references/samples.md`. Skipping a matching sample means rebuilding patterns that already exist.
83
84	> IMPORTANT — Exit criteria: After studying a sample, ask yourself: can I apply anything from this sample to help me deliver the design? Note what you'll reuse before moving on. Do NOT proceed until you've answered this.
85
86	> This list is useful at any phase — revisit it when you hit deployment, publishing, or infrastructure questions. A sample's Terraform or registration pattern may be exactly what you need later.
87
88	## Phase 2: Scaffold (if needed)
89
90	First check whether a project already exists: run `agents-cli info` from the project root. If one was already created or enhanced by agents-cli, skip this phase.
91
92	Otherwise, scaffold before writing any code:
93	- No project yet → `agents-cli scaffold create <name>`
94	- Existing code to import → `agents-cli scaffold enhance .` (adds the agents-cli structure)
95
96	Use `/google-agents-cli-scaffold` for the full workflow — it covers architecture choices (deployment target, agent type, session storage) and project creation or enhancement.
97
98	## Phase 3: Build and Implement
99
100	Implement the agent logic:
101
102	1. Write/modify code in the agent directory (check `GEMINI.md` / `CLAUDE.md` for directory name)
103	2. Quick smoke test: Use `agents-cli run "your prompt"` to verify the agent works after changes — this is the fastest way to check behavior without leaving the terminal
104	3. Iterate on the implementation based on user feedback
105
106	If the user asks for interactive testing, suggest `agents-cli playground` — it opens a web-based playground for manual conversation with the agent.
107
108	For ADK API patterns and code examples, use `/google-agents-cli-adk-code`.
109
110	> Smoke-test only here — do not write behavioral pytest. LLM output is non-deterministic; behavioral checks belong in eval (Phase 4), not pytest. Use `agents-cli run "prompt"` for quick checks.
111
112	### Provision a datastore (RAG, if the agent uses one)
113
114	RAG is a clone-and-study recipe (Phase 1). Datastore provisioning and ingestion live in the sample's
115	own `Makefile` (e.g. `make setup-infra`, `make data-ingestion`) and its `README.md` / `AGENTS.md` —
116	follow those, adapting the sample's `infra/terraform/` and `.env` into your project. (The former
117	`agents-cli infra datastore` / `agents-cli data-ingestion` commands have been removed.)
118
119	## Phase 4: Evaluate
120
121	This is the most important phase. Evaluation validates agent behavior end-to-end.
122
123	MANDATORY: Activate `/google-agents-cli-eval` before running evaluation.
124	It contains the dataset schema, config format, and critical gotchas. Do NOT skip this.
125
126	Do NOT skip this phase. After building the agent, you MUST proceed to evaluation.
127
128	`uv run pytest` vs `agents-cli eval` — know the difference:
129	- `uv run pytest` — Tests code correctness: imports work, functions return expected types, API contracts hold. Does NOT test whether the agent behaves well.
130	- `agents-cli eval` — Tests agent behavior: response quality, tool usage, persona consistency, safety compliance. This is what validates your agent actually works.
131	- `agents-cli run "prompt"` — Quick one-off smoke test during development. If testing multiple prompts use the `--start-server` option to persist the local server, which reduces overhead for repeated calls and allows resuming local sessions via `--session-id`. Use this for fast iteration, not pytest.
132
133	NEVER write pytest tests that check LLM response content (e.g., asserting pirate keywords appear, checking if the agent mentions allergies). LLM outputs are non-deterministic. Use eval with LLM-as-judge criteria instead.
134
135	1. Start small: Begin with 1-2 sample eval cases, not a full suite
136	2. Run evaluations: `agents-cli eval run` (chains `generate` + `grade`). For debugging or custom trace locations, use the two-step form: `agents-cli eval generate` then `agents-cli eval grade`.
137	3. Discuss results with the user
138	4. Fix issues and iterate on the core cases first
139	5. Only after core cases pass, add edge cases and new scenarios
140	6. Repeat until quality thresholds are met
141
142	Expect 5-10+ iterations here.
143
144	## Phase 5: Deploy
145
146	Once evaluation thresholds are met:
147
148	1. Check if the project has a deployment target configured — run `agents-cli info` to see current config
149	2. If the project is a prototype (no deployment target), add deployment support first:
150	```bash
151	agents-cli scaffold enhance . --deployment-target <target>
152	```
153	See `/google-agents-cli-deploy` for the deployment target decision matrix (Agent Runtime vs Cloud Run vs GKE).
154	3. Deploy when ready: `agents-cli deploy`
155
156	IMPORTANT: Never deploy without explicit human approval.
157
158	## Phase 6: Publish (optional)
159
160	Not all agents require this — currently supporting Gemini Enterprise. See `/google-agents-cli-publish` for registration modes, flags, and troubleshooting.
161
162	## Phase 7: Observe
163
164	After deploying, use observability tools to monitor agent behavior in production. See `/google-agents-cli-observability` for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.
165
166	---
167
168	# Operational Guidelines for Coding Agents
169
170	## Common Shortcuts to Resist
171
172	Agents routinely skip steps with plausible-sounding excuses. Recognize these and push back:
173
174	\| Shortcut \| Why it fails \|
175	\|----------\|-------------\|
176	\| "The user's request is clear enough, no need to clarify" \| You're guessing at requirements. Phase 0 exists to confirm intent before scaffolding — even one question can prevent a full rework. \|
177	\| "The agent responded correctly in `agents-cli run`, so eval isn't needed" \| One prompt is not a test suite. Eval catches regressions, edge cases, and tool trajectory issues that a single run never will. \|
178	\| "I'll use a newer/better model" \| The scaffolded model was chosen deliberately. Changing it without being asked violates code preservation (Principle 1) and often breaks things — wrong location, deprecated version, or 404. Your training data is likely out of date — rely on the skills and the model listing command, not your knowledge of model names. \|
179	\| "I can skip the scaffold and set up manually" \| Manual setup misses eval boilerplate, CI/CD config, and project configuration manifest conventions. Use `agents-cli create` even for quick experiments. \|
180
181	## Principle 1: Code Preservation & Isolation
182
183	Code modifications require surgical precision — alter only the code segments directly targeted by the user's request and strictly preserve all surrounding and unrelated code.
184
185	Mandatory Pre-Execution Verification:
186
187	Before finalizing any code replacement, verify the following:
188
189	1. Target Identification: Clearly define the exact lines or expressions to change, based solely on the user's explicit instructions.
190	2. Preservation Check: Confirm that all code, configuration values (e.g., `model`, `version`, `api_key`), comments, and formatting outside the identified target remain identical.
191
192	Example:
193
194	- User Request: "Change the agent's instruction to be a recipe suggester."
195	- Incorrect (VIOLATION):
196	```python
197	root_agent = Agent(
198	name="recipe_suggester",
199	model="gemini-1.5-flash", # UNINTENDED - model was not requested to change
200	instruction="You are a recipe suggester."
201	)
202	```
203	- Correct (COMPLIANT):
204	```python
205	root_agent = Agent(
206	name="recipe_suggester", # OK, related to new purpose
207	model="gemini-3.6-flash", # PRESERVED
208	instruction="You are a recipe suggester." # OK, the direct target
209	)
210	```
211
212	## Principle 2: Execution Best Practices
213
214	- Model Selection — CRITICAL:
215	- NEVER change the model unless explicitly asked.
216	- When creating NEW agents (not modifying existing), use the latest Gemini model. List available models to pick the newest one:
217	```bash
218	# Use 'global' or any supported region (e.g. 'us-east1')
219	uv run --with google-genai python -c "
220	from google import genai
221	client = genai.Client(vertexai=True, location='global')
222	for m in client.models.list(): print(m.name)
223	"
224	```
225	- Do NOT use older models unless explicitly requested. For model docs, fetch `https://adk.dev/agents/models/google-gemini/index.md`. See also [stable model versions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions).
226
227	- Running Python Commands:
228	- Always use `uv` to execute Python commands (e.g., `uv run python script.py`)
229	- Run `uv sync` before executing scripts
230
231	- Breaking Infinite Loops:
232	- Stop immediately if you see the same error 3+ times in a row
233	- RED FLAGS: Lock IDs incrementing, names appending v5→v6→v7, "I'll try one more time" repeatedly
234	- State conflicts (Error 409): Use `terraform import` instead of retrying creation
235	- When stuck: Run underlying commands directly (e.g., `terraform` CLI)
236
237	- Troubleshooting:
238	- Check `/google-agents-cli-adk-code` first — it covers most common patterns
239	- Use WebFetch on URLs from the ADK docs index (`curl https://adk.dev/llms.txt`) for deep dives
240	- When encountering persistent errors, a targeted web search often finds solutions faster
241	- CLI command failures: run `agents-cli <command> --help` — the output ends with a `Source:` line pointing to the exact source file implementing that command. Read it to understand the logic and diagnose failures. Use `agents-cli info` to get the full CLI install path if you need to browse across multiple files.
242
243	### Systematic Debugging
244
245	When something breaks, follow this sequence — don't skip steps or shotgun fixes:
246
247	1. Reproduce — Run the exact command that failed. Save the full error output. If you can't reproduce it, you can't fix it.
248	2. Localize — Narrow the cause: is it the agent code, a tool, the config, or the environment? Use `agents-cli run "prompt"` to isolate agent behavior from deployment issues. Add `-v` (`--verbose`) to print the full JSON event payloads — useful for inspecting tool calls, intermediate steps, and silent failures.
249	3. Fix one thing — Change one variable at a time. If you change the instruction AND the tool AND the config simultaneously, you won't know what fixed it (or what broke something else).
250	4. Verify — Rerun the exact reproduction command. Don't assume the fix worked.
251	5. Guard — If it was a non-obvious bug, add an eval case to catch regressions.
252
253	Stop-the-line rule: If a change breaks something that was working, stop feature work and fix the regression first. Don't push forward hoping to circle back — regressions compound.
254
255	- Environment Variables:
256	- `.env` files and env var assignments (e.g., `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`) are typically required for the agent to function — never remove or modify them unless the user explicitly asks
257	- If a `.env` file exists in the project root, treat it as essential configuration
258	- For secrets and API keys, prefer GCP Secret Manager over plain `.env` entries — see `/google-agents-cli-deploy` for secret management guidance
259
260	---
261
262	## Using a Temporary Scaffold as Reference
263
264	When you need specific infrastructure files (Terraform, CI/CD, Dockerfile) but don't want to modify the current project, use `/google-agents-cli-scaffold` to create a temporary project in `/tmp/` and copy over what you need.
265
266	---
267
268	## Reference Files
269
270	\| File \| Contents \|
271	\|------\|----------\|
272	\| `references/internals.md` \| Underlying tools and commands that `agents-cli` wraps (adk, pytest, ruff, uvicorn) \|
273	\| `references/samples.md` \| Keyword-indexed catalog of ADK reference samples to study before scaffolding \|
274	\| `references/spec-template.md` \| `.agents-cli-spec.md` template and optional sections \|
275	\| `references/brainstorming.md` \| Phase 0 design-dialogue playbook (one-at-a-time Q&A, approaches, gates) \|
276	\| `references/terminology.md` \| Product-name → CLI-value mapping \|
277	\| `references/commands.md` \| Per-phase `agents-cli` command index \|
278
279	## Development Commands
280
281	Run `agents-cli --help` or `agents-cli <command> --help` for the authoritative flag list. A per-phase command index lives in `references/commands.md`; per-phase usage is in the phase sections above.
282
283	---
284
285	## Skills Version
286
287	> Troubleshooting hint: If skills seem outdated or incomplete, reinstall:
288	> ```
289	> agents-cli setup --skip-auth
290	> ```
291	> Only do this when you suspect stale skills are causing problems.

6 picks

Type

Run `npx skills use "https://github.com/google/agents-cli" --skill "google/agents-cli/google-agents-cli-workflow"` 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-workflow

How to install google-agents-cli-workflow?

Related

google-agents-cli-workflow

How to install google-agents-cli-workflow?

Related