Gemini Skill Guide

When to Use This Skill

Primary Use Cases:

User explicitly requests
```
gemini
```
CLI execution (Mode 1: Direct CLI)
Large-context analysis requiring 1M token window (Mode 2: Gemini Delegation)
Repository-scale code reviews and architectural analysis
Multimodal analysis (code + images/diagrams)
Cross-module dependency tracking

Do NOT use for:

Simple code explanations (use Claude directly)
Small context tasks (<100K tokens)
Tasks not requiring Gemini-specific capabilities

Execution Modes

Mode 1: Direct CLI Execution

When: User explicitly asks to run gemini CLI

Workflow:

Gather configuration using structured questions:
- Model selection (gemini-3-pro-preview vs gemini-3-flash-preview)
- Approval mode (default, auto_edit, yolo)
- Output format (text, json, stream-json)

Execute:

bash

gemini "<PROMPT>" -m <MODEL> --approval-mode <MODE> --output-format <FORMAT>

Inform user: "You can resume with 'gemini --resume latest' anytime"

Resuming:

bash

gemini "<CONTINUATION PROMPT>" --resume latest

Mode 2: Gemini Delegation for Large Context

When: Task requires large context window (>100K tokens), multimodal input, or repository-scale analysis

Workflow:

Analyze context and identify what Gemini analysis would help
Formulate comprehensive query with all relevant context:
- Problem statement
- Current findings
- Code snippets or file references
- Specific questions
Leverage Gemini's 1M token context for comprehensive analysis

Execute:

gemini "<DETAILED CONTEXT>" --output-format json

Synthesize Gemini response into actionable insights
Report findings with:
- Clear summary of Gemini's analysis
- Specific recommendations or solutions
- Additional considerations or caveats
- Next steps if applicable

Error Handling

Verify gemini binary exists before execution:
```
which gemini
```
Stop immediately on non-zero exit codes and report to user
Request direction before retrying failed commands
Before using high-autonomy flags, confirm with user:
- ```
--yolo
```
  (auto-approve all actions)
- ```
--approval-mode yolo
```

Context Management

Gemini excels at large context (up to 1M tokens)
For massive contexts (>500K tokens), consider module-by-module summaries
Use
```
--include-directories
```
to add additional workspace paths
Leverage session resume for iterative refinement

Configuration Gathering Patterns

Initial Configuration (Mode 1, Step 1)

At the start of Mode 1 execution, gather model, approval mode, and output format:

Standard configuration question:

text

Select gemini configuration (model, approval mode, and output format):

1. "gemini-3-pro-preview / default / json (Recommended)" - High quality, safe mode
2. "gemini-3-pro-preview / auto_edit / json" - High quality, auto-approve edits
3. "gemini-3-flash-preview / default / json" - Fast, safe mode
4. "gemini-3-flash-preview / auto_edit / json" - Fast, auto-approve edits
5. "gemini-3-pro-preview / yolo / json" - High quality, fully autonomous
6. "gemini-3-flash-preview / yolo / json" - Fast, fully autonomous
7. "Custom" - User will specify model, approval, and format separately

High-Impact Flags Confirmation

Before executing with --yolo or autonomous flags:

text

Ready to execute with these flags: [LIST FLAGS]. Proceed?

1. "Execute now" - Run as configured
2. "Modify configuration" - Change settings
3. "Cancel" - Abort

Post-Execution Follow-up

After gemini command completes:

text

Gemini completed. [SUMMARY]. Next steps?

1. "Resume with additional prompt" - Continue session
2. "Analyze results" - Review output
3. "Complete" - Finished
4. "Retry with different config" - Adjust settings

Error Recovery

When command fails or has warnings:

text

Error: [SPECIFIC ERROR]. How to proceed?

1. "Resume with adjustments" - Fix and continue
2. "Retry with different config" - Change model/approval/format
3. "Accept partial results" - Use what worked
4. "Invoke heal-skill" - Fix outdated SKILL.md

Running a Task

Gather configuration using the patterns above
Assemble the command with the appropriate options:
- ```
-m, --model <MODEL>
```
  (gemini-3-pro-preview or gemini-3-flash-preview)
- ```
--approval-mode <MODE>
```
  (default, auto_edit, yolo)
- ```
-o, --output-format <FORMAT>
```
  (text, json, stream-json)
- ```
--include-directories <DIRS>
```
  (additional workspace paths)
- ```
-r, --resume <SESSION>
```
  (latest or session index)
Run the command, capture output, and summarize for the user
After Gemini completes, inform the user: "You can resume this Gemini session at any time by saying 'gemini resume' or asking me to continue."

Quick Reference

Use case	Approval mode	Key flags
Safe analysis	`default`	`--approval-mode default --output-format json`
Auto-approve edits	`auto_edit`	`--approval-mode auto_edit --output-format json`
Fully autonomous	`yolo`	`--yolo --output-format json`
Resume recent session	Inherited	`--resume latest`
Add workspace directories	Match task	`--include-directories <DIRS>`
Interactive continuation	default	`-i "<PROMPT>"` (stays interactive after)

Model Selection

Model	Use Case	Context	Speed
`gemini-3-pro-preview`	Complex reasoning, architecture review	1M tokens	Slower
`gemini-3-flash-preview`	Quick analysis, simple tasks	1M tokens	Faster

Session Management

bash

# List available sessions
gemini --list-sessions

# Resume most recent session
gemini --resume latest

# Resume specific session by index
gemini --resume 5

# Delete a session
gemini --delete-session 3

MCP Server Integration

bash

# List configured MCP servers
gemini mcp list

# Add an MCP server
gemini mcp add <name> <command> [args...]

# Remove an MCP server
gemini mcp remove <name>

# Limit to specific MCP servers
gemini "<PROMPT>" --allowed-mcp-server-names mcp-skillset

Extension System

bash

# List installed extensions
gemini extensions list

# Install extension from git or path
gemini extensions install <source> [--auto-update] [--pre-release]

# Update extensions
gemini extensions update [--all]

# Disable/enable extension
gemini extensions disable <name>
gemini extensions enable <name>

Following Up

After every
```
gemini
```
command, offer follow-up options
When resuming, use:
```
gemini "<new prompt>" --resume latest
```
The resumed session automatically uses the same context from the original
Restate the chosen model and approval mode when proposing follow-up actions

Error Handling Guidelines

Stop and report failures whenever
```
gemini --version
```
or a
```
gemini
```
command exits non-zero; request direction before retrying
Confirm high-impact flags before execution
When output includes warnings or partial results, offer error recovery options

Comparison with Codex Skill

Feature	Gemini	Codex
Context window	1M tokens	~200K tokens
Primary models	gemini-3-pro/flash	gpt-5.2-codex
Approval modes	default/auto_edit/yolo	never/on-request/on-failure
Sandbox	Boolean (--sandbox)	read-only/workspace-write/danger-full-access
Resume	--resume latest/index	codex exec resume --last
Stderr handling	N/A	2>/dev/null for thinking tokens
Output format	text/json/stream-json	json flag

Integration Patterns

With Other CLI Agents

bash

# Use gemini for large context, codex for GPT-specific
gemini "Analyze entire codebase architecture" --output-format json
codex exec "Implement specific feature based on analysis" --full-auto

# Chain with research CLI
research docs -t "framework API" --format json | gemini "Apply this to codebase"

Multimodal Analysis

bash

# Gemini can process images inline with code
gemini "Analyze this architecture diagram and compare with implementation" \
  --include-directories ./docs ./src

Heal-Skill Integration

When gemini CLI API changes are detected (command failures, unexpected output formats, or deprecated flags):

Detection: Notice command failures or API mismatches during execution
Trigger: Flag skill for healing via
```
/heal-skill gemini
```
Analysis: Healing agent analyzes current CLI with
```
gemini --help
```
and
```
gemini --version
```
Update: Updates skill documentation to match current API
Validation: Re-validates agent configuration for compatibility
Model Verification: Ensures only gemini-3 models are referenced
Context Window Verification: Confirms 1M token context window specifications

Common Changes to Monitor:

New or deprecated command flags
Changes to approval modes or output formats
Model availability updates (gemini-3 family)
MCP server integration API changes
Session management API modifications
Extension system updates
Context window specification changes

gemini

NPX Install

Tags

SKILL.md Content

Gemini Skill Guide

When to Use This Skill

Execution Modes

Mode 1: Direct CLI Execution

Mode 2: Gemini Delegation for Large Context

Error Handling

Context Management

Configuration Gathering Patterns

Initial Configuration (Mode 1, Step 1)

High-Impact Flags Confirmation

Post-Execution Follow-up

Error Recovery

Running a Task

Quick Reference

Model Selection

Session Management

MCP Server Integration

Extension System

Following Up

Error Handling Guidelines

Comparison with Codex Skill

Integration Patterns

With Other CLI Agents

Multimodal Analysis

Heal-Skill Integration