name: gemini-integration
description: This skill provides guidance on using Google's Gemini CLI for long-context code exploration. Use when the user explicitly invokes "/gemini", asks to "use gemini", "run gemini", or when Claude determines that Gemini's massive context window would complement its work on codebase exploration, architecture review, or cross-file analysis.
allowed-tools: Bash, Glob, Read

Gemini CLI Integration

Gemini CLI leverages Google's Gemini models with a 1M token context window - ideal for "satellite view" analysis where you need to see the entire codebase at once.

When to Use Gemini

Ideal Cases (Gemini excels)

Not Ideal (Use Claude directly)

How to Invoke

Via Slash Command

/gemini <task>
/gemini --model gemini-3-flash-preview <task>
/gemini --dirs src,lib <task>
/gemini --files "**/*.py" <task>

Via Agent (autonomous)

Claude can spawn gemini-agent automatically for deep exploration tasks.

CLI Reference

Headless Mode (for automation)

# Basic
gemini -p "<PROMPT>" --output-format text --yolo 2>&1

# With model
gemini -p "<PROMPT>" -m gemini-3-flash-preview --output-format text --yolo 2>&1

# With directory context
gemini -p "<PROMPT>" --include-directories src,lib --output-format text --yolo 2>&1

# With file context (piped)
cat src/**/*.ts | gemini -p "<PROMPT>" --output-format text --yolo 2>&1

Key Flags

Available Models

Gemini Prompting Best Practices

Based on Google's Gemini 3 prompting guide:

Structure Principles

1. Be direct and specific - Avoid unnecessary preamble
2. Use consistent delimiters - XML tags (<task>, <context>) or markdown
3. Critical instructions first - Important constraints at the beginning
4. Context → Task → Constraints - Large blocks first, questions last
5. Keep temperature at 1.0 - Don't lower it (degrades performance)

Prompt Template

<context>
[Source material / files / background]
</context>

<task>
[Clear, direct task description]
</task>

<constraints>
- Output format requirements
- What NOT to include
- Scope limits
</constraints>

Code-Specific Prompt Patterns

Architecture Analysis:

<task>Analyze the architecture of this codebase.</task>
<output>
1. Main entry points
2. Core modules and responsibilities
3. Data flow patterns
4. Key dependencies
Format: Markdown with ASCII diagrams where helpful.
</output>

Security Audit:

<task>Security audit of this codebase.</task>
<focus>auth bypass, injection, data exposure, access control</focus>
<output_format>
`file:line - SEVERITY - issue - recommendation`
Focus ONLY on confirmed issues. Skip style issues.
</output_format>

Refactoring Impact:

<task>Analyze impact of refactoring [COMPONENT].</task>
<analyze>
1. Current state and responsibilities
2. What depends on it
3. What it depends on
4. Files that need changes
5. Migration steps
6. Test plan
</analyze>

End-to-End Flow:

<task>Trace [FEATURE] flow from start to finish.</task>
<output>
For each step:
- file:line reference
- What happens
- Data transformations
- Next step
</output>

Codebase Orientation:

<task>I'm new to this codebase. Provide orientation.</task>
<answer>
1. What does this project do? (1-2 sentences)
2. Main entry points
3. Directory structure overview
4. Key patterns/abstractions
5. How to run/test
</answer>

Documentation Generation:

<task>Generate [TYPE] documentation for this codebase.</task>
<requirements>
1. Purpose: What this module/API/project does
2. Usage: How to use it with examples
3. API Reference: Functions with signatures
4. Configuration: Available options
5. Examples: Working code snippets
</requirements>
<format>Markdown. Include code blocks, tables for reference.</format>

Best Practices

Scope Discipline

• Be explicit about what to focus on
• Set boundaries - "Focus ONLY on X. Skip Y."
• Request specific format - Makes output actionable

Good vs Weak Prompts

Good:

/gemini --dirs src Analyze error handling. For each: file:line, error type, logged?, recoverable?

Weak:

/gemini check this code

Combining with Claude

1. Gemini explores - Get the satellite view
2. Claude synthesizes - Interpret and act on findings
3. Claude executes - Make actual code changes

Troubleshooting