shanraisshan/gemini-cli-best-practice

80 stars Quality 67 Trend 18MIT

from vibe coding to agentic engineering - practice makes gemini perfect

Overview

from vibe coding to agentic engineering — practice makes gemini perfect 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. All major workflows converge on the same architectural pattern: . 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). GEMINI.md and its nested variants hold persistent context. Keep them focused — the same lazy-loading pattern Claude Code uses applies here. Gemini CLI Hooks Claude Code Best Practice Claude Code Hooks Codex CLI Best Practice Codex CLI Hooks If you like my work, buy me a doodh patti 🍵 on

README

gemini-cli-best-practice

from vibe coding to agentic engineering — practice makes gemini perfect

= Agents · = Skills · = Commands

🧠 CONCEPTS

Feature	Location	Description
Subagents	`.gemini/agents/.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//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/.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`	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 ""`	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` · `/memory show` · `/memory refresh` for runtime facts — volatile but beats retyping
`/chat save` + `/chat resume` 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 ""` 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.

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

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

Polar

View the full README on GitHub

Recommended Tools

Try a different keyword or remove a filter.

Install

npx skillfish add shanraisshan/gemini-cli-best-practice

New to MCP? Start with the mcpskill.org guide →