gemini

What this skill does

# Gemini: Google AI Assistant for Claude Code

---

## DEFAULT MODEL: Gemini 3.1 Pro

**The default model for ALL Gemini invocations is `gemini-3.1-pro-preview`.**

- Always use `gemini-3.1-pro-preview` unless user explicitly requests another model
- This is the highest reasoning model available (released Feb 19, 2026)
- CLI default (without `-m`) is `gemini-3-flash-preview` (fast but less capable)
- Fallback chain: `gemini-3.1-pro-preview` → `gemini-3-pro-preview` → `gemini-2.5-flash`

```bash
# Default invocation - ALWAYS use gemini-3.1-pro-preview
gemini -m gemini-3.1-pro-preview "your prompt here"
```

---

## CRITICAL: Headless Mode with `-p` Flag

**REQUIRED**: Use `-p`/`--prompt` flag for non-interactive (headless) execution in Claude Code.

As of Gemini CLI v0.29.0+, positional prompts default to **interactive mode**. The `-p` flag is the correct way to run in **non-interactive (headless) mode**.

**Examples:**
- `gemini -m gemini-3.1-pro-preview -p "prompt"` (CORRECT - headless mode)
- `gemini -m gemini-3.1-pro-preview "prompt"` (also works when piped, but `-p` is more explicit)
- `gemini -r latest` (session resume)

**Why?** As of v0.29.0, the CLI description states: "Defaults to interactive mode. Use -p/--prompt for non-interactive (headless) mode." The `-p` flag is no longer deprecated.

---

## IMPORTANT: Preview Features & OAuth Free Tier

**For OAuth free tier users in headless mode:**

When `previewFeatures: true` in `~/.gemini/settings.json`, the CLI routes ALL requests to Gemini 3.1 Pro (even `-m gemini-2.5-pro`). Since free tier doesn't have Gemini 3 access, this causes 404 errors.

**Solution**: Disable preview features for reliable headless operation:
```json
// ~/.gemini/settings.json
{
  "general": {
    "previewFeatures": false
  }
}
```

**Plugin Behavior**: This skill automatically falls back to `gemini-2.5-flash` when encountering 404 errors. Flash always works with OAuth free tier.

---

## Trigger Examples

This skill activates when users say phrases like:
- "Use gemini to research this topic"
- "Ask gemini about this design pattern"
- "Run gemini on this analysis"
- "Call gemini for help with this problem"
- "I need Google AI for this task"
- "Get Gemini's reasoning on this"
- "Continue with gemini" or "Resume the gemini session"
- "Gemini, help me with..." or simply "Gemini"
- "Use Gemini 3" or "Use Gemini 2.5"

## When to Use This Skill

This skill should be invoked when:
- User explicitly mentions "Gemini" or requests Gemini assistance
- User needs Google's AI models for reasoning, research, or analysis
- User requests complex problem-solving or architectural design
- User needs research capabilities with web search integration
- User wants to continue a previous Gemini conversation
- User needs an alternative to Codex or Claude for specific tasks

## How It Works

### Detecting New Gemini Requests

When a user makes a request, **default to read-only mode (default approval)** unless they explicitly request file editing:

**Use `gemini-3.1-pro-preview` for ALL tasks with `default` approval mode:**
- Architecture, design, reviews, research
- Explanations, analysis, problem-solving
- Code analysis and understanding
- ANY task where user does NOT explicitly request file editing

**Approval Mode Selection:**
- **`default`** (default): For all tasks - prompts for approval on edits (safe)
- **`auto_edit`**: ONLY when user explicitly requests file editing
- **`plan`**: Read-only mode - no file modifications allowed
- **`yolo`**: When user explicitly wants full auto-approval (use with caution)

**⚠️ Explicit Edit Request**: If the user explicitly asks to "edit files", "modify code", "write changes", or "make edits" - ONLY then use `--approval-mode auto_edit` to enable file modifications.

**Fallback Chain** (if primary unavailable):
1. `gemini-3.1-pro-preview` (primary - highest capability)
2. `gemini-2.5-pro` (stable general reasoning)
3. `gemini-2.5-flash` (fast, always available)

**Example requests**: "Design a distributed cache", "Explain CQRS pattern", "Analyze this code"

### Bash CLI Command Structure

**IMPORTANT**: Gemini CLI works differently from Codex - no `exec` subcommand needed. Use positional prompts directly.

#### Default Command (Read-Only) - Use for ALL Tasks

```bash
gemini -m gemini-3.1-pro-preview \
  "Design a microservices architecture for e-commerce"
```

#### Explicit Edit Request Only - When User Asks to Edit Files

```bash
gemini -m gemini-3.1-pro-preview \
  --approval-mode auto_edit \
  "Edit this file to refactor the function"
```

#### For Session Continuation

```bash
# Resume most recent session
gemini -r latest

# Resume specific session by index
gemini -r 3

# Resume and add new prompt
gemini -r latest "Continue our discussion about caching strategies"
```

**Why positional prompts?**
- Simpler, more direct syntax
- Future-proof (recommended by Gemini CLI)
- Works in non-TTY environments (like Claude Code's bash)
- No separate `exec` command needed

### Model Selection Logic

**Use `gemini-3.1-pro-preview` (default for ALL tasks):**
- Code editing, refactoring, implementation
- Designing architecture or system design
- Conducting research or analysis
- Explaining complex concepts
- Planning implementation strategies
- General problem-solving and advanced reasoning

**Fallback to `gemini-2.5-pro` when:**
- Gemini 3.1 Pro unavailable or quota exhausted
- User explicitly requests "Gemini 2.5" or "use 2.5"
- Stable, production-ready tasks

**Fallback to `gemini-2.5-flash` when:**
- Both Gemini 3.1 Pro and 2.5 Pro unavailable
- Fast iterations needed (explicit user request)
- Simple, quick responses (explicit user request)

### Version-Based Model Mapping

When users mention a version number, map to the latest model in that family:

| User Request | Maps To | Actual Model ID |
|--------------|---------|-----------------|
| "use 3" / "Gemini 3" | Latest 3.x Pro | `gemini-3.1-pro-preview` |
| "use 2.5" | 2.5 Pro | `gemini-2.5-pro` |
| "use flash" | 2.5 Flash | `gemini-2.5-flash` |
| No version specified | Latest Pro (ALL tasks) | `gemini-3.1-pro-preview` |

**See**: `references/model-selection.md` for detailed model selection guidance and decision tree.

### Default Configuration

All Gemini invocations use these defaults unless user specifies otherwise:

| Parameter | Default Value | CLI Flag | Notes |
|-----------|---------------|----------|-------|
| Model | `gemini-3.1-pro-preview` | `-m gemini-3.1-pro-preview` | For ALL tasks (highest capability) |
| Model (fallback 1) | `gemini-2.5-pro` | `-m gemini-2.5-pro` | If Gemini 3.1 Pro unavailable |
| Model (fallback 2) | `gemini-2.5-flash` | `-m gemini-2.5-flash` | Always works on free tier |
| Approval Mode (default) | `default` | No flag | Safe default - prompts for edits |
| Approval Mode (editing) | `auto_edit` | `--approval-mode auto_edit` | Only when user explicitly requests editing |
| Sandbox | `false` (disabled) | No flag | Sandbox disabled by default |
| Output Format | `text` | No flag | Human-readable text output |
| Web Search | Enabled when appropriate | `-e web_search` (if needed) | Context-dependent |

**Rationale for Defaults:**
- **Gemini 3.1 Pro for ALL tasks**: Highest capability model, optimized for both reasoning and code
- **Fallback chain**: gemini-3.1-pro-preview → gemini-2.5-pro → gemini-2.5-flash
- **default mode**: Safe default that prompts for approval on edits
- **auto_edit mode**: Only use when user explicitly requests file editing
- **No sandbox**: Claude Code environment assumed trusted
- **Text output**: Default for human consumption (use `--output-format json` for parsing)

**Note**: If you have `previewFeatures: true` in settings, disable it for reliable headless operation (see warning above).

### Error Handling

The skill handles these common errors gracefully:

#### CLI Not Installed

**Error**: `command not found: gemini`

**Message**: "Gemini CLI not installed. Install from: https://github.com/google-gem