gemini-cli

name	gemini-cli
description	Use Google's Gemini CLI for web-grounded research (Google Search), automation via one-shot prompts, and second-opinion review. Use when you need structured JSON output, fast scripting workflows, or cross-AI validation.
allowed-tools	["Bash","Read","Write","Grep","Glob"]

Gemini CLI Integration Skill

This skill enables Claude Code to orchestrate Google's Gemini CLI reliably using one-shot prompts (positional prompt) for scripting and automation.

When to Use This Skill

Ideal Use Cases

1. Second Opinion / Cross-Validation

   • Code review after writing code (different AI perspective)
   • Security audit with alternative analysis
   • Finding bugs Claude might have missed

2. Google Search Grounding

   • Questions requiring current internet information
   • Latest library versions, API changes, documentation updates
   • Current events or recent releases

3. Automation (One-Shot)

   • One-shot prompts in CI/scripts with gemini "..." (positional prompt)
   • Structured output via --output-format json
   • Streaming JSON events via --output-format stream-json (only when you explicitly need detailed event traces)

4. Parallel Processing

   • Offload tasks while continuing other work
   • Run multiple code generations simultaneously
   • Background documentation generation

5. Specialized Generation

   • Test suite generation
   • JSDoc/documentation generation
   • Code translation between languages

When NOT to Use

• Simple, quick tasks (overhead not worth it)
• Tasks requiring immediate response (rate limits cause delays)
• When context is already loaded and understood
• Interactive refinement requiring conversation

Core Instructions

Model policy (pinned for consistency)

In this workspace, run Gemini CLI with an explicit pinned model for consistency and deeper reviews:

gemini --model gemini-3-pro-preview "..."

This is intentional: our tests show the pinned gemini-3-pro-preview run produces more careful, slower, code-grounded reviews.

1. Verify Installation & Auth (Gemini CLI itself)

command -v gemini && gemini --version

If missing, install:

npm install -g @google/gemini-cli

Authenticate (one of):

• API key: export GEMINI_API_KEY=...
• OAuth (interactive): run gemini once and follow the prompts

2. Critical Concept: Gemini CLI Has NO Claude Context

Gemini CLI is a separate process. It does not see this chat.

Gemini one-shot calls are not interactive by default: you get one request and one answer.

To make Gemini effective in one-shot mode, always include:

• Goal: what you want and why
• Inputs: explicit file paths (or inject files/dirs via @path), plus any relevant snippets
• Constraints: languages, frameworks, versions, coding style, do/don't rules
• Deliverable: exact output shape (e.g. “return JSON”, “output diff”, “output a markdown table”)
• Scope: what to touch vs not touch (files/dirs, no network, no deps, etc.)
• Working directory: run from the project root so relative paths resolve

3. Basic One-Shot Pattern (Recommended)

Use one-shot prompts for predictable, scriptable behavior:

gemini --model gemini-3-pro-preview "Your prompt here" --output-format text

Key flags:

• --output-format: text (default), json, stream-json
• --yolo, -y: Auto-approve all actions
• --approval-mode: e.g. auto_edit
• --include-directories: add extra workspace dirs (comma-separated)
• --debug, -d: debug output

3.1 One-shot prompt checklist (must be exhaustive)

Use this checklist when writing the prompt you pass to gemini "...":

• Context injection: include @path/to/file / @src/ where needed (Gemini does not see your repo unless you provide it).
• Exact task: “Do X” + acceptance criteria (what counts as “done”).
• Output contract:
  • If you want a clean final answer only: say “Output ONLY the final answer. No reasoning.”
  • If you want machine parsing: request --output-format json and rely on .response.
• Safety / approvals:
  • If you want it to act without prompts: use --yolo or --approval-mode auto_edit.
  • If you want zero traces: avoid --output-format stream-json and avoid --debug.

3.2 Multi-line prompts (practical pattern)

For long instructions, build a multi-line prompt and pass it as one argument:

PROMPT=$(cat <<'EOF'
Output ONLY the final answer. No reasoning.

Task:
- ...

Inputs:
- @path/to/file
- @src/

Constraints:
- ...

Deliverable:
- ...
EOF
)

gemini --model gemini-3-pro-preview "$PROMPT" --output-format json > /tmp/gemini.json 2> /tmp/gemini.err \
  && jq -r '.response' /tmp/gemini.json > /tmp/gemini.out

4. Output Handling Best Practice (Low-Token, Reliable)

Do not stream Gemini output directly into the tool output for large responses. Instead, redirect to a file and read the file.

gemini --model gemini-3-pro-preview "Review @backend/src/app.module.ts for security issues" \
  --output-format text \
  --yolo \
  > /tmp/gemini.txt 2> /tmp/gemini.err && echo "Gemini completed"

# Then read with Read tool:
# - /tmp/gemini.txt
# - /tmp/gemini.err (only if needed)

Output only the final answer (no logs / no event stream)

If you want only the final output (and to avoid extra CLI chatter), prefer JSON output and extract .response into a clean file.

gemini --model gemini-3-pro-preview "Answer with ONLY the final result. No reasoning. Task: ..." \
  --output-format json \
  --yolo \
  > /tmp/gemini.json 2> /tmp/gemini.err \
  && jq -r '.response' /tmp/gemini.json > /tmp/gemini.out \
  && echo "Gemini completed"

# Then read with Read tool:
# - /tmp/gemini.out   (clean final answer only)
# - /tmp/gemini.err   (only if something went wrong)

Avoid these when you want “final output only”:

• --output-format stream-json (it emits tool/event traces by design)
• --debug (adds verbose debug logs)

For structured automation:

gemini --model gemini-3-pro-preview "Summarize @README.md in 5 bullets" \
  --output-format json \
  > /tmp/gemini.json 2> /tmp/gemini.err && echo "Gemini completed"

# Extract just the response:
jq -r '.response' /tmp/gemini.json

5. Critical Behavioral Notes

Approval behavior:

• --yolo auto-approves all actions.
• --approval-mode auto_edit can be a safer middle ground (auto-edit without fully "yolo"-ing everything).

Rate limits (documented): CLI auto-retries with backoff; you may see messages like "quota will reset after Xs".

6. Injecting Files & Directories into Prompts (@ commands)

Use @<path> in the prompt to inject file/directory contents (git-aware filtering by default):

gemini --model gemini-3-pro-preview "@src/ Summarize the code in this directory. Focus on architecture." --output-format text
gemini --model gemini-3-pro-preview "What does this file do? @README.md" --output-format text

Notes:

• For paths with spaces, escape spaces: @My\ Documents/file.txt
• By default, git-ignored paths (e.g. node_modules/, .env) are excluded (configurable in settings)

7. Output Processing (JSON)

For JSON output (--output-format json), parse:

{
  "response": "actual content",
  "stats": {
    "models": { "tokens": {...} },
    "tools": { "byName": {...} }
  }
}

Quick Reference Commands

Code Generation

gemini --model gemini-3-pro-preview "Create [description] with [features]. Output complete file content." --yolo --output-format text

Code Review

gemini --model gemini-3-pro-preview "Review @path/to/file for: 1) features, 2) bugs/security issues, 3) improvements" --output-format text

Bug Fixing

gemini --model gemini-3-pro-preview "Fix these bugs in @path/to/file: [list]. Apply fixes now." --yolo --output-format text

Test Generation

gemini --model gemini-3-pro-preview "Generate [Jest/pytest] tests for @path/to/file. Focus on [areas]." --yolo --output-format text

Documentation

gemini --model gemini-3-pro-preview "Generate JSDoc for all functions in @path/to/file. Output as markdown." --yolo --output-format text

Web Research

gemini --model gemini-3-pro-preview "What are the latest [topic]? Use Google Search." --output-format text

Error Handling

Rate Limit Exceeded

• CLI auto-retries with backoff
• Run in background for long operations

Command Failures

• Prefer --output-format json and inspect .error (if present)
• Verify Gemini is authenticated and available: gemini --version
• Check settings: ~/.gemini/settings.json and .gemini/settings.json

Validation After Generation

Always verify Gemini's output:

• Check for security vulnerabilities (XSS, injection)
• Test functionality matches requirements
• Review code style consistency
• Verify dependencies are appropriate

Integration Workflow

Standard Generate-Review-Fix Cycle

# 1. Generate
gemini --model gemini-3-pro-preview "Create [code]" --yolo --output-format text

# 2. Review (Gemini reviews its own work)
gemini --model gemini-3-pro-preview "Review @path/to/file for bugs and security issues" --output-format text

# 3. Fix identified issues
gemini --model gemini-3-pro-preview "Fix [issues] in @path/to/file. Apply now." --yolo --output-format text

Background Execution

For long tasks, run in background and monitor:

gemini --model gemini-3-pro-preview "[long task]" --yolo --output-format text > /tmp/gemini-long.txt 2>&1 &
# Monitor by reading /tmp/gemini-long.txt

Gemini CLI Capabilities Worth Using

Notable built-in tools:

• google_web_search: real-time web search grounding
• web_fetch: fetch & summarize specific URLs
• run_shell_command: execute shell commands (be careful)

Configuration

Project Context (Optional)

Create .gemini/GEMINI.md in project root for persistent context that Gemini will automatically read.

See Also

• reference.md - Complete command and flag reference
• templates.md - Prompt templates for common operations
• patterns.md - Advanced integration patterns
• tools.md - Gemini's built-in tools documentation
• image-generation.md - Practical notes for image generation (nanobanana)