Labsco
softaworks logo

gemini

★ 2,144

by softaworks · part of softaworks/agent-toolkit

Use when the user asks to run Gemini CLI for code review, plan review, or big context (>200k) processing. Ideal for comprehensive analysis requiring large context windows. Uses Gemini 3 Pro by default for state-of-the-art reasoning and coding.

🧩 One of 7 skills in the softaworks/agent-toolkit package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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"

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.

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