---

name: gemini-research description: Research and codebase analysis assistant. Use for large codebase analysis and exploration ("analyze this code", "investigate the architecture", "コードを調査して"), library recommendations, error solutions, and best practices. Also use when users ask "what's the best library for X?", "which framework should I use?", "how do I fix this error?", or need web-enhanced research. Leverages Gemini CLI with Google Search integration and --include-directories for codebase exploration. Gemini analyzes and researches but does NOT write implementation code - Claude Code handles all implementation.

Gemini Research

Overview

This skill enables Claude Code to delegate research and analysis tasks to Gemini CLI, leveraging Gemini's strengths in codebase exploration, web-enhanced investigation, and multimodal analysis. While Claude Code focuses on implementation, Gemini provides deep analysis and current information through Google Search integration.

Key principle: Gemini is used for research and analysis (including codebase analysis) - it does NOT write implementation code. Claude Code remains responsible for all implementation work.

When Claude Should Use This Skill

Automatically leverage Gemini CLI in these scenarios:

1. Plan Mode - Repository Analysis: Understanding large or unfamiliar codebases before planning changes
2. Plan Mode - Library Research: Evaluating and selecting libraries, researching APIs and frameworks
3. Error Investigation: Finding solutions to build errors, runtime issues, or unexpected behavior
4. Best Practices Research: Gathering current patterns, conventions, and community consensus
5. Documentation Discovery: Finding usage examples and implementation guides for libraries/APIs

Basic Usage Pattern

Gemini CLI is invoked via bash commands. The general pattern:

gemini -p "research prompt here" --output-format json

Key flags:

• -p: Non-interactive mode with direct prompt
• --output-format json: Structured output for programmatic parsing
• --include-directories: Target specific directories for codebase analysis

Example:

gemini -p "Analyze the testing strategy in this repository. What frameworks are used and how are tests organized?" --include-directories ./tests --output-format json

--include-directories syntax

Directories must be comma-separated, not space-separated. Space-separated paths are interpreted as positional arguments and conflict with -p, producing the error Cannot use both a positional prompt and the --prompt (-p) flag together.

# ✅ Correct: comma-separated
gemini -p "..." --include-directories ./src,./tests --output-format json

# ❌ Wrong: space-separated (causes positional arg conflict)
gemini -p "..." --include-directories ./src ./tests --output-format json

For large prompts, stdin is more reliable:

cat <<'EOF' | gemini -p "" --include-directories ./src,./tests --output-format json
Your large research prompt here...
EOF

Research Workflows

Step 0: Select Workflow

Choose the appropriate workflow based on the task:

Exploring an unfamiliar or large codebase?    → Workflow 1 (Repository Analysis)
Choosing or comparing libraries/frameworks?   → Workflow 2 (Library Research)
Investigating a build error or runtime bug?   → Workflow 3 (Error Investigation)
Learning an API or finding best practices?    → Workflow 4 (Documentation & Best Practices)

If the task spans multiple categories (e.g., error in an unfamiliar codebase), combine workflows — use Workflow 1 first for context, then Workflow 3 for the error.

Workflow 1: Repository Analysis (Plan Mode)

Trigger: User requests feature work requiring codebase understanding

1. Identify scope: Determine which parts of the codebase are relevant
2. Construct prompt: Use templates from references/prompts.md
3. Execute Gemini CLI:

   gemini -p "Analyze [ASPECT] in this codebase. Focus on [SPECIFIC_AREAS]." \
     --include-directories [TARGET_DIR] \
     --output-format json
   

4. Parse results: Extract key findings (architecture, patterns, dependencies)
5. Inform plan: Use Gemini's analysis to design implementation approach
6. Report to user: Summarize findings and proposed plan

Example scenario: "Add authentication to this app"

• Gemini analyzes current auth patterns, middleware structure, database schema
• Claude Code uses findings to plan authentication implementation

Workflow 2: Library Research (Plan Mode)

Trigger: Need to select, learn, or migrate libraries

1. Define requirements: What problem needs solving? What are the constraints?
2. Construct research prompt: Library comparison, API usage, or migration guidance
3. Execute Gemini CLI:

   gemini -p "Research libraries for [USE_CASE]. Compare options and recommend best choice for [REQUIREMENTS]." \
     --output-format json
   

4. Evaluate options: Parse Gemini's recommendations
5. Inform plan: Choose library and design integration approach
6. Report to user: Present recommendation with rationale

Example scenario: "Choose a form validation library for React"

• Gemini researches current options (React Hook Form, Formik, Zod, etc.)
• Claude Code proposes best fit and integration plan

Workflow 3: Error Investigation

Trigger: Build failure, runtime error, or unexpected behavior

1. Capture error context:
   • Full error message
   • Stack trace
   • Environment details (OS, framework versions, etc.)
   • Recent changes
2. Construct investigation prompt:

   gemini -p "Investigate this error: [ERROR_MESSAGE]. Environment: [CONTEXT]. Find known solutions." \
     --output-format json
   

3. Parse solutions: Extract root cause, known issues, workarounds
4. Apply fix: Implement solution (Claude Code writes the code)
5. Verify: Test that error is resolved
6. Report: Explain what was found and how it was fixed

Example scenario: TypeScript build fails with cryptic error

• Gemini searches for error message, finds it's a known tsconfig issue
• Claude Code applies the documented fix

Workflow 4: Documentation and Best Practices

Trigger: Implementing unfamiliar API or pattern

1. Identify knowledge gap: What specific information is needed?
2. Request targeted research:

   gemini -p "How do I use [LIBRARY/API] for [SPECIFIC_TASK]? Show examples and best practices." \
     --output-format json
   

3. Extract guidance: Code patterns, configuration, gotchas
4. Implement with Claude Code: Write actual code following Gemini's guidance
5. Report: Explain implementation approach

Example scenario: "Implement server-sent events in Express"

• Gemini finds documentation, examples, and best practices
• Claude Code writes the Express SSE implementation

Prompt Construction Guidelines

Effective research prompts are:

• Specific: Include exact versions, error codes, technology stack
• Contextual: Provide environment details and constraints
• Focused: Ask for specific information, not general overviews
• Actionable: Request concrete recommendations or steps

See references/prompts.md for proven templates.

Important Guidelines

Gemini's Role: Research and Analysis

• DO: Use Gemini for codebase analysis, architecture exploration, and dependency investigation
• DO: Use Gemini for web-enhanced research, best practices, and library evaluation
• DO: Ask Gemini to explain, compare, and recommend approaches
• DON'T: Ask Gemini to write implementation code
• DON'T: Have Gemini make file edits or changes

Claude Code always writes the actual implementation.

When to Use Gemini vs. Claude Code Directly

Use Gemini when:

• Codebase is large (>100 files) and unfamiliar
• Need current web information (library versions, known issues)
• Investigating errors with unclear root cause
• Comparing multiple approaches or technologies
• Learning unfamiliar APIs or frameworks

Use Claude Code directly when:

• Codebase is small or already understood
• Task is straightforward implementation
• No external research needed
• Working within well-known stack

Output Handling

When using --output-format json, parse the JSON response to extract:

• Key findings and recommendations
• Code examples (for reference, not direct use)
• Links and resources
• Next steps or action items

Structure findings clearly when reporting to user:

• What was researched
• Key discoveries
• Recommended approach
• Why this approach makes sense

Example Session Flow

User: "Add Stripe payment integration to the checkout page"

Claude Code:
1. Enters plan mode
2. Uses Gemini to research:
   - Stripe API best practices 2026
   - React + Stripe integration patterns
   - PCI compliance considerations
3. Parses Gemini's findings
4. Designs implementation plan
5. Presents plan to user with:
   - Stripe SDK recommendation
   - Security approach
   - UI/UX pattern
   - Testing strategy
6. After approval, implements (without Gemini)

Tips for Effective Usage

1. Be strategic: Don't use Gemini for simple tasks Claude Code handles easily
2. Batch questions: Combine related research into single comprehensive prompts
3. Extract learnings: Apply Gemini's insights to inform better implementation
4. Verify information: Cross-reference critical recommendations before implementing
5. Use JSON output: Enables programmatic parsing for automated workflows