Gemini

Gemini Skill Guide

When to Use Gemini

• WHEN ASKED TO BE ACTIVATED
• Code Review: Comprehensive code reviews across multiple files
• Plan Review: Analyzing architectural plans, technical specifications, or project roadmaps
• Big Context Processing: Tasks requiring >200k tokens of context (entire codebases, documentation sets)
• Multi-file Analysis: Understanding relationships and patterns across many files

⚠️ Critical: Background/Non-Interactive Mode Warning

NEVER use `--approval-mode default` in background or non-interactive shells (like Claude Code tool calls). It will hang indefinitely waiting for approval prompts that cannot be provided.

For automated/background reviews:

• ✅ Use --approval-mode yolo for fully automated execution
• ✅ OR wrap with timeout: timeout 300 gemini ...
• ❌ NEVER use --approval-mode default without interactive terminal

Symptoms of hung Gemini:

• Process running 20+ minutes with 0% CPU usage
• No network activity
• Process state shows 'S' (sleeping)

Fix hung process:

# Check if hung
ps aux | grep gemini | grep -v grep

# Kill if necessary
pkill -9 -f "gemini.*gemini-3-pro-preview"

Running a Task

1. Ask the user (via AskUserQuestion) which model to use in a single prompt. Available models:

• gemini-3-pro-preview ⭐ (flagship model, best for coding & complex reasoning, 35% better at software engineering than 2.5 Pro)
• gemini-3-flash (sub-second latency, distilled from 3 Pro, best for speed-critical tasks)
• gemini-2.5-pro (legacy option, strong all-around performance)
• gemini-2.5-flash (legacy option, cost-efficient with thinking capabilities)
• gemini-2.5-flash-lite (legacy option, fastest processing)

2. Select the approval mode based on the task:

• default: Prompt for approval (⚠️ ONLY for interactive terminal sessions)
• auto_edit: Auto-approve edit tools only (for code reviews with suggestions)
• yolo: Auto-approve all tools (✅ REQUIRED for background/automated tasks)

3. Assemble the command with appropriate options:

• -m, --model <MODEL> - Model selection
• --approval-mode <default|auto_edit|yolo> - Control tool approval
• -y, --yolo - Alternative to --approval-mode yolo
• -i, --prompt-interactive "prompt" - Execute prompt and continue interactively
• --include-directories <DIR> - Additional directories to include in workspace
• -s, --sandbox - Run in sandbox mode for isolation

4. For background/automated tasks, ALWAYS use `--approval-mode yolo` or add timeout wrapper. NEVER use default in non-interactive shells.

5. Run the command and capture the output. For background/automated mode:

   # Recommended: Use yolo for background tasks
   gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase for security issues"

   # Or with timeout (5 min limit)
   timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase"

6. For interactive sessions with an initial prompt:

   gemini -m gemini-3-pro-preview -i "Review the authentication system" --approval-mode auto_edit

7. After Gemini completes, inform the user: "The Gemini analysis is complete. You can start a new Gemini session for follow-up analysis or continue exploring the findings."

Quick Reference

Model Selection Guide

Gemini 3 Advantages: 35% higher accuracy in software engineering, state-of-the-art on SWE-bench (76.2%), GPQA Diamond (91.9%), and WebDev Arena (1487 Elo). Knowledge cutoff: January 2025.

Coming Soon: gemini-3-deep-think for ultra-complex reasoning with enhanced thinking capabilities.

Common Use Cases

Code Review (Background/Automated)

# For background execution (Claude Code, CI/CD, etc.)
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Perform a comprehensive code review focusing on:
   1. Security vulnerabilities
   2. Performance issues
   3. Code quality and maintainability
   4. Best practices violations"

# With timeout safety (5 minutes)
timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Perform a comprehensive code review..."

Plan Review (Background/Automated)

# For background execution
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Review this architectural plan for:
   1. Scalability concerns
   2. Missing components
   3. Integration challenges
   4. Alternative approaches"

Big Context Analysis (Background/Automated)

# For background execution
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Analyze the entire codebase to understand:
   1. Overall architecture
   2. Key patterns and conventions
   3. Potential technical debt
   4. Refactoring opportunities"

Interactive Code Review (Terminal Only)

# ONLY use default mode in interactive terminal
gemini -m gemini-3-pro-preview --approval-mode default \
  "Review the authentication flow for security issues"

Following Up

• Gemini CLI sessions are typically one-shot or interactive. Unlike Codex, there's no built-in resume functionality.
• For follow-up analysis, start a new Gemini session with context from previous findings.
• When proposing follow-up actions, restate the chosen model and approval mode.
• Use AskUserQuestion after each Gemini command to confirm next steps or gather clarifications.

Error Handling

• Stop and report failures whenever gemini --version or a Gemini command exits non-zero.
• Request direction before retrying failed commands.
• Before using high-impact flags (--approval-mode yolo, -y, --sandbox), ask the user for permission using AskUserQuestion unless already granted.
• When output includes warnings or partial results, summarize them and ask how to adjust using AskUserQuestion.

Troubleshooting Hung Gemini Processes

Detection

# Check for hung processes
ps aux | grep -E "gemini.*gemini-3" | grep -v grep

# Look for these symptoms:
# - Process running 20+ minutes
# - CPU usage at 0%
# - Process state 'S' (sleeping)
# - No network connections

Diagnosis

# Get detailed process info
ps -o pid,etime,pcpu,stat,command -p <PID>

# Check network activity
lsof -p <PID> 2>/dev/null | grep -E "(TCP|ESTABLISHED)" | wc -l
# If result is 0, process is hung

Resolution

# Kill hung Gemini processes
pkill -9 -f "gemini.*gemini-3-pro-preview"

# Or kill specific PID
kill -9 <PID>

# Verify cleanup
ps aux | grep gemini | grep -v grep

Prevention

• ALWAYS use `--approval-mode yolo` for background/automated tasks
• Add timeout wrapper for safety: timeout 300 gemini ...
• Never use --approval-mode default in non-interactive shells
• Monitor first run with ps to ensure process completes

Tips for Large Context Processing

1. Be specific: Provide clear, structured prompts for what to analyze 2. Use include-directories: Explicitly specify all relevant directories 3. Choose the right model:

• Use gemini-3-pro-preview for complex reasoning, coding tasks, and maximum analysis quality (recommended default)
• Use gemini-3-flash for speed-critical tasks requiring sub-second response times
• Use gemini-2.5-flash for cost-optimized high-volume processing

4. Leverage Gemini 3's strengths: 35% better at software engineering tasks, exceptional at agentic workflows and vibe coding 5. Break down complex tasks: Even with large context, structured analysis is more effective 6. Save findings: Ask Gemini to output structured reports that can be saved for reference

CLI Version

Requires Gemini CLI v0.16.0 or later for Gemini 3 model support. Check version: gemini --version

Gemini Skill

Harness the power of Google's Gemini 3 Pro for comprehensive code analysis, plan reviews, and big context processing. This skill enables Claude Code to leverage Gemini CLI for tasks requiring massive context windows (>200k tokens) and state-of-the-art reasoning capabilities.

Purpose

The Gemini skill provides access to Google's flagship Gemini 3 Pro model through the Gemini CLI, offering:

• Massive Context Windows: Process up to 1M tokens of input across entire codebases
• State-of-the-Art Performance: 76.2% on SWE-bench, 35% better at software engineering than Gemini 2.5 Pro
• Advanced Reasoning: Exceptional at complex coding tasks, architectural analysis, and agentic workflows
• Flexible Automation: Support for both interactive and background/automated execution modes

When to Use This Skill

Use the Gemini skill when:

• User explicitly asks to run Gemini CLI or mentions Gemini
• Performing comprehensive code reviews across multiple files or entire codebases
• Analyzing architectural plans, technical specifications, or project roadmaps
• Processing large context (>200k tokens) such as entire documentation sets
• Understanding complex relationships and patterns across many files
• Tasks requiring advanced reasoning on software engineering problems

Activation Keywords: "use Gemini", "run Gemini", "Gemini review", "analyze with Gemini", "big context", ">200k tokens"

How It Works

The skill acts as an intelligent wrapper around the Gemini CLI, providing:

1. Model Selection: Guides users to choose the optimal Gemini model for their task 2. Approval Mode Management: Automatically selects the correct approval mode based on execution context 3. Background Safety: Prevents hung processes in non-interactive environments 4. Structured Prompts: Helps construct effective prompts for comprehensive analysis

Execution Flow

User Request → Model Selection → Approval Mode → Command Assembly → Execution → Results

The skill handles all complexity around:

• Preventing hung processes in background mode
• Choosing between interactive and automated execution
• Timeout management for safety
• Error handling and recovery

Key Features

1. Multiple Model Options

2. Smart Approval Modes

• `default`: Prompts for approval (interactive terminal only)
• `auto_edit`: Auto-approves edit tools only (code reviews with suggestions)
• `yolo`: Auto-approves all tools (required for background/automated tasks)

3. Background Execution Safety

The skill automatically protects against hung processes by:

• Enforcing --approval-mode yolo for non-interactive shells
• Providing timeout wrappers for safety
• Detecting and killing hung processes
• Warning against dangerous approval mode combinations

4. Large Context Processing

• 1M token input capacity
• Multi-directory analysis support
• Structured prompt guidance
• Efficient codebase traversal

Usage Examples

Example 1: Comprehensive Code Review (Background)

gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Perform a comprehensive code review focusing on:
   1. Security vulnerabilities
   2. Performance issues
   3. Code quality and maintainability
   4. Best practices violations"

Use Case: Automated code review in CI/CD or Claude Code background tasks

Example 2: Architectural Plan Review

gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Review this architectural plan for:
   1. Scalability concerns
   2. Missing components
   3. Integration challenges
   4. Alternative approaches"

Use Case: Analyzing technical specifications and system designs

Example 3: Full Codebase Analysis

gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Analyze the entire codebase to understand:
   1. Overall architecture
   2. Key patterns and conventions
   3. Potential technical debt
   4. Refactoring opportunities"

Use Case: Understanding large codebases or legacy systems

Example 4: Interactive Code Review (Terminal Only)

gemini -m gemini-3-pro-preview --approval-mode default \
  "Review the authentication flow for security issues"

Use Case: Interactive sessions where user can approve/reject suggestions in real-time

Example 5: Speed-Critical Analysis

gemini -m gemini-3-flash --approval-mode yolo \
  "Quick security scan for common vulnerabilities"

Use Case: Fast analysis with sub-second latency requirements

Example 6: Multi-Directory Analysis

gemini -m gemini-3-pro-preview --approval-mode yolo \
  --include-directories /path/to/backend \
  --include-directories /path/to/frontend \
  "Analyze the full-stack application architecture"

Use Case: Projects spanning multiple directories or repositories

Command Reference

Core Flags

Approval Modes Quick Reference

Critical: Background Mode Warning

NEVER use `--approval-mode default` in background or non-interactive shells (like Claude Code tool calls). It will hang indefinitely waiting for approval prompts that cannot be provided.

For Automated/Background Tasks

✅ DO THIS:

# Use yolo for fully automated execution
gemini -m gemini-3-pro-preview --approval-mode yolo "Review codebase"

# Or wrap with timeout for safety
timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo "Review codebase"

❌ NEVER DO THIS:

# Will hang indefinitely in background
gemini -m gemini-3-pro-preview --approval-mode default "Review codebase"

Symptoms of Hung Gemini

• Process running 20+ minutes with 0% CPU usage
• No network activity
• Process state shows 'S' (sleeping)

Fix Hung Process

# Check if hung
ps aux | grep gemini | grep -v grep

# Kill if necessary
pkill -9 -f "gemini.*gemini-3-pro-preview"

Best Practices

1. Model Selection

• Default to `gemini-3-pro-preview`: Best quality, 35% better at software engineering
• Use `gemini-3-flash`: When speed is critical (sub-second latency)
• Use `gemini-2.5-flash`: For cost-optimized high-volume processing ($0.15/M tokens)

2. Prompt Engineering

Be specific and structured:

gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Analyze the authentication system for:
   1. OWASP Top 10 vulnerabilities
   2. JWT token handling security
   3. Session management best practices
   4. Rate limiting implementation
   5. Password hashing strength"

3. Context Management

• Use --include-directories to explicitly specify relevant paths
• Break down massive tasks into focused analyses
• Save structured reports for reference

4. Safety

• Always use --approval-mode yolo for background tasks
• Add timeout wrappers for safety: timeout 300 gemini ...
• Monitor first run to ensure process completes
• Check for hung processes with ps aux | grep gemini

Error Handling

The skill handles common errors:

1. Non-zero exit codes: Reports failure and requests direction 2. Hung processes: Detects and provides kill commands 3. Warnings in output: Summarizes and asks for adjustments 4. Permission issues: Asks user before using high-impact flags

Troubleshooting

Process Hung in Background

Detection:

ps aux | grep -E "gemini.*gemini-3" | grep -v grep
# Look for: 20+ min runtime, 0% CPU, state 'S'

Resolution:

pkill -9 -f "gemini.*gemini-3-pro-preview"

Prevention: Always use --approval-mode yolo for background tasks

No Output After Long Time

Check if process is waiting for approval:

ps -o pid,etime,pcpu,stat,command -p <PID>

If stat is 'S' and CPU is 0%, kill and restart with --approval-mode yolo

Out of Memory

For very large codebases:

• Use gemini-3-flash instead of Pro
• Break analysis into smaller chunks
• Use --include-directories to limit scope

Requirements

• Gemini CLI v0.16.0 or later (for Gemini 3 support)
• Check version: gemini --version
• Google Cloud credentials configured
• Sufficient API quota for large context operations

Tips for Success

1. Start with Pro: Default to gemini-3-pro-preview for best quality 2. Be Specific: Clear, structured prompts yield better results 3. Use Background Mode Safely: Always use yolo in non-interactive contexts 4. Leverage Context: Gemini excels at understanding large codebases 5. Save Results: Ask Gemini to output structured reports 6. Follow Up: Start new sessions with context from previous findings

Performance Benchmarks

Gemini 3 Pro advantages:

• SWE-bench: 76.2% (state-of-the-art)
• GPQA Diamond: 91.9%
• WebDev Arena: 1487 Elo
• 35% improvement over Gemini 2.5 Pro in software engineering tasks

Integration with Claude Code

The skill seamlessly integrates with Claude Code workflows:

1. User requests Gemini analysis 2. Skill prompts for model selection 3. Determines execution context (interactive vs background) 4. Assembles safe command with proper flags 5. Executes and captures output 6. Returns structured results to user

After completion, users can:

• Start new Gemini session for follow-up
• Continue exploring findings with Claude Code
• Save reports for documentation

Coming Soon

• gemini-3-deep-think: Ultra-complex reasoning with enhanced thinking capabilities
• Extended context windows beyond 1M tokens
• Enhanced multi-modal analysis

Resources

• Gemini CLI Documentation
• Gemini API Reference
• Model Comparison

---

Knowledge Cutoff: Gemini 3 models have knowledge through January 2025 Skill Version: Compatible with Gemini CLI v0.16.0+