gemini-cli-best-practice

from vibe coding to agentic engineering — practice makes gemini perfect

= Agents · = Skills · = Commands

🧠 CONCEPTS

Feature	Location	Description
Subagents	.gemini/agents/<name>.md	Specialized actors with isolated context, scoped tools, and custom system prompts · auto-delegate or explicit @agent invocation · built-ins: codebase_investigator, cli_help, generalist, browser_agent (v0.38.1+)
Agent Skills	.gemini/skills/<name>/SKILL.md	First-class primitive (v0.23.0+) — name + description only frontmatter, optional scripts/ / references/ / assets/ subfolders · progressive disclosure via activate_skill tool with user consent · Workspace > User > Extension precedence
Commands	.gemini/commands/<name>.toml	TOML prompt templates with {{args}}, !{shell}, and @path injection. Sub-folders create namespaces (git/commit.toml → /git:commit).
Workflow	.gemini/commands/weather-orchestrator.toml	Command → Agent → Skill
MCP Servers	.gemini/settings.json → mcpServers	Model Context Protocol integrations (Playwright, Context7, Google Workspace, Figma, GitHub, custom).
Extensions	gemini extensions install <name>	Distributable bundles of commands + MCP servers + scoped GEMINI.md.
Memory	GEMINI.md, .gemini/GEMINI.md, ~/.gemini/GEMINI.md	Tree-merged memory with @path imports and /memory runtime commands.
Settings	.gemini/settings.json	Hierarchical config: flags > env vars > local > project > user > defaults.
Checkpointing	--checkpointing, /restore	Pre-edit file snapshots with session-local rollback.
CLI Startup Flags	gemini [flags]	Flags, subcommands (gemini mcp add, gemini extensions install), and environment variables.
AI Terms		Agentic Engineering · Context Engineering · Vibe Coding
Official Docs		Gemini CLI · Gemini API · MCP

🔥 Hot

Feature	Where	Description
YOLO Mode	--yolo / -y	Auto-approves every tool call — sandbox/CI only, never on your workstation
Headless Mode	gemini -p "<prompt>"	One-shot invocation; pipes through stdin/stdout for CI/cron
Checkpointing	--checkpointing + /restore	File-level undo for exploratory refactors
Multi-directory	--include-directories ../other	Reason across multiple repos in one session
@path injection	inside prompts & commands	Multimodal — @file.png, @file.pdf, @file.mp3 all work
Shell passthrough	!cmd (single) or ! (persistent)	Run shell without leaving Gemini
/compress	built-in	Summarizes the chat to free context window
/chat save / /chat resume	built-in	Multi-session conversation persistence
IDE integration	VS Code / JetBrains plugins	Diffs and code context pipe into the CLI
GitHub Actions	google-gemini/gemini-cli-action	Gemini-driven PR review and triage in CI
Extensions	gemini extensions install	Community packs with commands + MCP servers bundled
Google Workspace MCP	google-workspace MCP server	Paste a Docs/Sheets link, get a summary
Sandbox	GEMINI_SANDBOX=1	Container / macOS Seatbelt isolation for file/shell tools
Telemetry (local)	telemetry.target: "local"	Offline observability for tool calls and tokens
Vertex AI auth	selectedAuthType: "vertex-ai"	Enterprise-grade auth with GCP IAM

See orchestration-workflow for implementation details of the Command → Agent → Skill pattern — built on Gemini CLI's TOML commands, native subagents (v0.38.1+), and first-class Agent Skills (v0.23.0+).

gemini
/weather-orchestrator

Gemini asks for your unit, fetches the temperature from Open-Meteo, writes an SVG card, and prints the paths. The full command prompt: .gemini/commands/weather-orchestrator.toml.

⚙️ DEVELOPMENT WORKFLOWS

All major workflows converge on the same architectural pattern: Research → Plan → Execute → Review → Ship.

Name	★	Workflow
Superpowers	171k	→ → → → →	5	3	14
Everything Claude Code	167k	→ → → → →	48	143	230
Spec Kit	92k	→ → → →	0	9+	0
gstack	86k	→ → → → → → → →	0	0	37
Get Shit Done	58k	→ → → → → →	33	122	0
BMAD-METHOD	46k	→ → → → → → → →	0	0	39
OpenSpec	44k	→ →	0	11	0
oh-my-claudecode	31k	→ → → → → → → →	19	0	37
Compound Engineering	16k	→ → → → → →	50	4	44

Note: yellow tags are sub-loops — steps that repeat inside a parent step (e.g. per task, per story, or until a verify condition passes).

Others

• Taylor Mullen (Creator of Gemini CLI) Workflow — · GitHub · X · Gemini CLI repo
• Addy Osmani (Google DevRel) Workflow — 29 Tips · source · X

💡 TIPS AND TRICKS (29+)

🚫👶 = do not babysit

Memory · GEMINI.md · Agents · Skills · Commands · MCP · Context · Safety · Automation · Cost & Observability

■ Memory & Persistence (4)

Tip	Source
store project-specific instructions in GEMINI.md for zero-prompt context — auto-loaded every session
/memory add <fact> · /memory show · /memory refresh for runtime facts — volatile but beats retyping
/chat save <tag> + /chat resume <tag> for parallel multi-day threads — context survives across days 🚫👶
/compress at ~50% context before auto-compact fires at the model's least intelligent point

GEMINI.md (3)

GEMINI.md and its nested variants hold persistent context. Keep them focused — the same lazy-loading pattern Claude Code uses applies here.

Tip	Source
keep each GEMINI.md under ~200 lines — longer files dilute attention and the model starts ignoring rules
for monorepos, push scoped instructions into per-package GEMINI.md files rather than one mega root file — ancestor + descendant loading covers the tree
use @path imports inside GEMINI.md to pull in style guides or build docs — cheaper and more reliable than pasting content inline

Agents (5)

Tip	Source
delegate long, tool-heavy work to the built-in codebase_investigator — 20 file reads + 12 greps stay in the child's context, only the final report returns 🚫👶
use @agent_name in the prompt to force a specific subagent — auto-delegation via description: matching works, but explicit is more reliable for orchestrated flows
scope tools: tightly — read-only allowlist for audit agents, no MCP for offline agents · tools: ["*"] means the agent can do anything, scope explicitly
write a specific description: — it's what the main agent reads to decide when to delegate · "helpful assistant" gets ignored, "Reviews diffs for SQLi/XSS/SSRF before merging auth PRs" gets routed
drop temperature: 0.2 for review / audit agents; let generators run at 1.0 — deterministic reviewers, creative generators

Skills (5)

Tip	Source
treat the skill description: as a trigger, not a summary — "Use this skill to X. It handles Y. Activate when Z." routes reliably
skills are folders, not files — use scripts/, references/, assets/ subdirectories for progressive disclosure so activation is cheap
include scripts and asset templates in skills so the model composes rather than reconstructs boilerplate each time
don't put skills that fetch data — use subagents for fetching · skills are procedural (render, review, migrate)
precedence is Workspace > User > Extension — rename on name collisions instead of relying on shadowing

Commands (4)

Tip	Source
TOML slash commands in .gemini/commands/ — namespace with sub-folders · git/commit.toml → /git:commit
inject shell output at load time with !{cmd} instead of asking the model to run it — deterministic and the prompt reads the result directly
~/.gemini/settings.json for cross-project personal defaults; project-level .gemini/settings.json for team-shared
if you do something more than once a day, turn it into a skill or command — build /status, /techdebt, /review:security

■ MCP & Integrations (4)

Tip	Source
MCP servers are first-class — Figma, Google Workspace, GitHub, Playwright, proprietary DBs all plug in via .gemini/settings.json → mcpServers
paste Google Docs / Sheets links directly into prompts once the Workspace MCP is configured — Gemini fetches and summarizes on the spot
ask Gemini to write and spin up a temporary MCP server mid-session when you hit a gap — it generates the server, you register it, and the tool is live for the rest of the session
IDE plugins (VS Code / JetBrains) pipe diffs and code context straight into the CLI — skip the copy/paste dance

■ Context & Input (5)

Tip	Source
@./path injects files, directories, images, PDFs, and audio into the prompt — multimodal works out of the box
--include-directories ../sibling,../shared works across multiple repos in one session — cross-repo reasoning without leaving Gemini
AI-assisted file organization — point Gemini at a messy directory and ask it to classify, rename (using vision), dedupe
multimodal OCR — invoice parsing, UI mockup analysis, audio transcription, chart reading all via @file.png / @file.pdf / @file.mp3
/stats shows token usage — structure long prompts so the stable prefix comes first to benefit from cache hits

■ Safety & Modes (4)

Tip	Source
--checkpointing snapshots files before every edit · /restore rolls back · safety net for exploratory refactors
prefer scoped allowlists (Shell(npm test), WebFetch(domain:*.google.com)) over global --yolo — scoped auto-approval doesn't unlock rm -rf /
GEMINI_SANDBOX=1 for container / macOS Seatbelt isolation when the session touches untrusted code or data
restrict $PATH for Gemini CLI so it can't reach unwanted tools — improves safety in CI and shared envs 🚫👶

■ Automation & Scripting (4)

Tip	Source
gemini -p "<prompt>" for headless / CI / scheduled runs · pipes through stdin/stdout, no chat UI
GEMINI_SYSTEM_MD=./ci-prompt.md replaces the baked-in system prompt — perfect for scoping CI personas per job
!cmd shell passthrough for one-shot commands; ! alone enters persistent shell mode — terminal without leaving the session
your entire $PATH (Docker, ffmpeg, ImageMagick, gcloud, kubectl) is Gemini's toolkit — CLI tools beat asking the model to re-implement them

■ Cost & Observability (3)

Tip	Source
/stats for token usage and cache-hit insight — catch context bloat before it hits your wallet
local telemetry on (telemetry.target: "local") for session-level observability — tool calls, tokens, durations without data leaving the machine
summarizeToolOutput in settings caps tool-call context bloat — long ReadFile / Shell outputs get summarized before being appended

1. Read the repo like a course — learn what commands, agents, and skills are before trying to use them.
2. Clone this repo and play with the examples. Try /weather-orchestrator, watch @weather-agent run in isolated context, and consent to the weather-svg-creator skill activation so you can see how the pieces connect.
3. Go to your own project and ask Gemini to suggest what best practices from this repo you should add — give it this repo as a reference so it knows what's possible.

🔔 SUBSCRIBE

Source	Name	Badge
	r/GoogleGeminiAI, r/GeminiAI, r/Bard, r/google, r/googlecloud
	Google AI, Google DeepMind, Gemini App, Taylor Mullen (Creator of Gemini CLI), Allen Hutchison (Gemini CLI Lead), Jack Wotherspoon (Gemini CLI DevRel), Addy Osmani (Google DevRel), Paige Bailey (AI DevX Lead), Logan Kilpatrick (AI Studio Lead), Sundar Pichai, Demis Hassabis, Jeff Dean, Oriol Vinyals, Koray Kavukcuoglu, Noam Shazeer, Quoc Le, Jack Rae, Denny Zhou, Ankur Bapna, Josh Woodward, Tulsee Doshi
	Google DeepMind, Google for Developers, Google AI Developers, Google Cloud Tech

Other Repos

Gemini CLI Hooks

Claude Code Best Practice

Claude Code Hooks

Codex CLI Best Practice

Codex CLI Hooks

Sponsor My Work

If you like my work, buy me a doodh patti 🍵 on

Polar