gemini-cli-best-practice
from vibe coding to agentic engineering — practice makes gemini perfect
-white?style=flat&labelColor=555)
= 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
