Agent-skills gemini

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.

install

source · Clone the upstream repo

git clone https://github.com/jdrhyne/agent-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jdrhyne/agent-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/codex/gemini" ~/.claude/skills/jdrhyne-agent-skills-gemini && rm -rf "$T"

manifest: codex/gemini/SKILL.md

source content

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

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)
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)
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
For background/automated tasks, ALWAYS use
```
--approval-mode yolo
```
or add timeout wrapper. NEVER use
```
default
```
in non-interactive shells.

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"

For interactive sessions with an initial prompt:

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

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."

Safety Boundaries

Do not run Gemini unless the user explicitly asked for Gemini or for a second-opinion review that justifies it.
Do not use
```
--approval-mode yolo
```
unless the task is non-interactive and the user approved high-autonomy execution.
Do not save reports or write files unless the user asked for an artifact.
Do not pass secrets, private keys, or unrelated workspace data into prompts.

Quick Reference

Use case	Approval mode	Key flags
Background code review	`yolo` ✅	`-m gemini-3-pro-preview --approval-mode yolo`
Background analysis	`yolo` ✅	`-m gemini-3-pro-preview --approval-mode yolo`
Background with timeout	`yolo` ✅	`timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo`
Interactive code review	`default`	`-m gemini-3-pro-preview --approval-mode default` (interactive terminal only)
Code review with auto-edits	`auto_edit`	`-m gemini-3-pro-preview --approval-mode auto_edit`
Automated refactoring	`yolo`	`-m gemini-3-pro-preview --approval-mode yolo`
Speed-critical background	`yolo` ✅	`-m gemini-3-flash --approval-mode yolo`
Cost-optimized background	`yolo` ✅	`-m gemini-2.5-flash --approval-mode yolo`
Multi-directory analysis	`yolo` (if background)	`--include-directories <DIR1> --include-directories <DIR2>`
Interactive with prompt	`auto_edit` or `default`	`-i "prompt" --approval-mode <mode>`

Model Selection Guide

Model	Best for	Context window	Key features
`gemini-3-pro-preview` ⭐	Flagship model: Complex reasoning, coding, agentic tasks	1M input / 64k output	Vibe coding, 76.2% SWE-bench
`gemini-3-flash`	Sub-second latency, speed-critical applications	1M input / 64k output	Distilled from 3 Pro, TPU-optimized
`gemini-2.5-pro`	Legacy: Strong all-around performance	1M input / 65k output	Thinking mode, mature stability
`gemini-2.5-flash`	Legacy: Cost-efficient, high-volume tasks	1M input / 65k output	Thinking mode
`gemini-2.5-flash-lite`	Legacy: Fastest processing, high throughput	1M input / 65k output	Maximum speed, minimal latency

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

Be specific: Provide clear, structured prompts for what to analyze
Use include-directories: Explicitly specify all relevant directories
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
Leverage Gemini 3's strengths: 35% better at software engineering tasks, exceptional at agentic workflows and vibe coding
Break down complex tasks: Even with large context, structured analysis is more effective
Return structured findings: Ask Gemini for markdown or JSON that can be quoted directly in the final answer

CLI Version

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

gemini --version