google-agents-cli-scaffold
Skill10 starsChanged todayMITView on GitHub
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).
- Reads credentials
2 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- jgeofil/agent-skillsedited, first seen Nov 8, 2026
- google/agents-cliword for word, first seen Oct 27, 2026
Other versions2 projects use a version of this.
Word for word · 1
- google/agents-cli★ 6.4k100% same
Edited · 1
- jgeofil/agent-skills★ 099% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository44 other files it gives its agents.
- llms-full.txtllms.txt
- llms.txtllms.txt
- ai-prompt-engineering-safety-reviewSkill
- ast-codemapSkill
- ast-grepSkill
- autoharnessSkill
- autonomous-backlog-driverSkill
- claude-kimi-mcp-normalizationSkill
- cli-self-updaterSkill
- code-frugalitySkill
- codemode-gatewaySkill
- codemode-typesSkill
- consequence-simulationSkill
- context-pruningSkill
- github-update-checkerSkill
- google-agents-cli-evalSkill
- history-searchSkill
- hook-gatingSkill
- hybrid-semantic-searchSkill
- kimi-code-agent-integrationSkill
- kimi-mcp-configurationSkill
- leann-vectorSkill
- log-summarizerSkill
- markdown-vagueSkill
- memory-reconciliationSkill
- mode-classificationSkill
- multiagent-orchestrationSkill
- output-compressionSkill
- prompt-injectionSkill
- python-anti-patternsSkill
- regression-sentinelSkill
- restart-trackingSkill
- rollback-guardSkill
- rust-call-graphSkill
- secrets-managementSkill
- security-best-practicesSkill
- session-compactorSkill
- sqlite-memorySkill
- swarm-barrierSkill
- swarm-dagSkill
- autoharnessSkill
- code-reliability-checksSkill
- skill-threat-rulesSkill
- autoharnessSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Use the agents-cli CLI to create new agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding.
- Distinctive: line 55
Search / Vector Search in Gemini platform (Vertex AI Search / Vertex AI Vector Search) / RAG → clone-and-study recipe, not a flag
- Very specific: line 76
Do NOT mkdir the project directory before running create — the CLI creates it automatically.
- Very specific: line 78
When enhancing an existing project, check where the agent code lives.
- Very specific: line 93
Run this from inside the project directory (or pass the path instead of .).
- Very specific: line 162
Start with --prototype to skip CI/CD and Terraform.
- Very specific: line 176
When using agent_runtime as the deployment target, Agent Runtime manages sessions internally.
- Very specific: line 182
After scaffolding, immediately load /google-agents-cli-workflow — it contains the development workflow, coding guidelines, and operational …
- Very specific: line 197
Verifying your agent works: Use agents-cli run "test prompt" for quick smoke tests, then agents-cli eval run for systematic validation.
- Very specific: line 203
When you need specific files (Terraform, CI/CD workflows, Dockerfile) but don't want to scaffold the current project directly, create a …
- Very specific: line 229
Project names: must be ≤26 characters, lowercase, letters/numbers/hyphens only
- Distinctive: line 239
Follow the standard flow (understand requirements, choose architecture, scaffold)
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 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 protocol | built 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, theagentic_ragtemplate, andagents-cli infra datastore/agents-cli data-ingestionno 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> \
--prototypeConstraints:
- Project name must be 26 characters or less, lowercase letters, numbers, and hyphens only.
- Do NOT
mkdirthe project directory before runningcreate— the CLI creates it automatically. If you mkdir first,createwill fail or behave unexpectedly. - Pass
--agent-guidance-filenamefor your IDE:GEMINI.mdfor Antigravity CLI,CLAUDE.mdfor Claude Code,AGENTS.mdotherwise. - 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
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_actionsTemplate Options
| Template | Language | Deployment | Description |
adk_python | 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_pythonandadk_goare the only built-in templates.adk_pythonis the default, so a Go project needs--agent adk_go.adkis an alias foradk_python. Other frameworks and third-party templates ship as template repos you scaffold from directly:--agent google/agents-cli/extensions/langchain/template@v1.14.0, with nothing installed. First-party templates live inextensions/(langchain/template,claude/template); see/google-agents-cli-workflow→references/extension.mdto 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
| Target | Description |
agent_runtime | Managed by Google (Agent Runtime). Container-based — Agent Runtime 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_python --prototype
# Step 2: Iterate on the agent code...
# Step 3: Add deployment when ready
agents-cli scaffold enhance . --deployment-target agent_runtimeAgent 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) — customizeapp/agent.pyandapp/tools.py. - ADK Go (
--agent adk_go) — customizeapp/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_runInspect 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
enhancecan'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-workflowPhase 0 and clarify the user's intent before runningscaffold create - NEVER change the model in existing code unless explicitly asked
- NEVER
mkdirbeforecreate— 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 anysession_typesetting from your code - Start with
--prototypefor quick iteration — add deployment later withenhance - 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_pythonandadk_gotemplates and framework templates alike); each language's A2A surface (import paths,AgentCardschema 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:
- Follow the standard flow (understand requirements, choose architecture, scaffold)
agents-cli scaffold create my-a2a-agent --agent adk_python --deployment-target cloud_run --prototypeResult: 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:
- Follow the standard flow (understand requirements, choose architecture, scaffold)
agents-cli scaffold create my-go-agent --agent adk_go --deployment-target cloud_run --prototypeResult: Go project withapp/agent.go, the launcher inmain.go, and the A2A card at the root.
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 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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

