Gemini Delegation Patterns

🚨 MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini CLI capabilities:

• INVOKE gemini-cli-docs skill

• QUERY for the specific feature topic

• BASE all responses EXCLUSIVELY on official documentation loaded

Overview

Meta-skill for determining when and how Claude should delegate to Gemini CLI. Documents decision criteria, execution patterns, and result handling.

When to Use This Skill

Keywords: delegate to gemini, use gemini, gemini vs claude, which agent, hand off, gemini better, claude or gemini, second brain

Use this skill when:

• Deciding whether a task should go to Gemini

• Planning cross-agent workflows

• Understanding Gemini CLI integration points

• Optimizing task distribution between Claude and Gemini

Decision Matrix

Scenario Delegate to Gemini? Rationale

Interactive TUI needed (vim, git rebase -i) YES Claude cannot handle PTY

Risky shell command YES Gemini sandbox isolation

Large codebase analysis (100K+ tokens) YES Gemini 1M+ context window

GCP/Firebase/Vertex auth required YES Native Google integration

Need instant rollback capability YES Gemini checkpointing

Quick code edit NO Claude is faster

Multi-turn conversation NO Claude maintains context better

Complex reasoning with files NO Claude's Edit tool is superior

Need persistent session NO Claude Code has better UX

Security-sensitive analysis MAYBE Gemini sandbox + Claude reasoning

Execution Patterns

Pattern 1: Fire-and-Forget (Headless)

Best for: Quick queries, analysis, code generation

gemini "{prompt}" --output-format json

When to use:

• One-off questions

• Code analysis without modification

• Documentation generation

Pattern 2: Sandboxed Execution

Best for: Risky commands, untrusted code

gemini -s "Execute: {command}" --output-format json --yolo

When to use:

• Running npm install for unknown packages

• Executing user-provided scripts

• Testing destructive operations

• Analyzing potentially malicious code

Pattern 3: Checkpointed Experimentation

Best for: Risky refactors, migrations

• Ensure checkpointing enabled in settings.json

• Execute refactor via Gemini

• Verify results (run tests)

• /restore if failed, keep if passed

When to use:

• Large-scale refactoring

• Framework migrations

• Database schema changes

• Breaking API modifications

Pattern 4: Interactive Handoff

Best for: TUI commands (vim, rebase, htop)

• Inform user of handoff requirement

• Start Gemini with interactive flag

• User interacts directly with PTY

• Claude resumes after completion

When to use:

• git rebase -i

• vim / nano / emacs

• htop / top

• Database CLIs (psql, mysql, redis-cli)

Pattern 5: Bulk Analysis

Best for: Large codebases exceeding Claude's context

cat $(find src -name "*.ts") | gemini "Analyze architecture" --output-format json -m gemini-2.5-flash

When to use:

• Full codebase architecture analysis

• Cross-file dependency mapping

• Large log file analysis (100K+ lines)

• Documentation generation for entire modules

Pattern 6: Second Opinion

Best for: Validation and alternative perspectives

gemini "REVIEW MODE (read-only): Analyze this independently: {content}" --output-format json

When to use:

• Validating security analysis

• Reviewing architectural decisions

• Checking refactoring plans

• Getting alternative implementation approaches

Model Selection Guide

Model Context Cost Best For

gemini-2.5-flash Large Lower Bulk analysis, simple tasks

gemini-2.5-pro Very large Higher Complex reasoning, quality critical

Use Flash when:

• Processing large files

• Doing bulk analysis

• Cost is a concern

• Task is straightforward

Use Pro when:

• Complex reasoning needed

• Quality is critical

• Task requires deep understanding

• Context exceeds 1M tokens

Quick Decision Tree

START | v Does it need a TUI? ─────────────> YES ─> gemini-interactive-shell agent | NO | v Is it risky/destructive? ────────> YES ─> gemini-sandboxed-executor agent | NO | v Is it a large file/codebase? ────> YES ─> gemini-bulk-analyzer agent | NO | v Need safety net for experiments? ─> YES ─> gemini-checkpoint-experimenter agent | NO | v Want validation/second opinion? ──> YES ─> gemini-second-opinion agent | NO | v Simple query? ───────────────────> YES ─> /gemini-query command | NO | v Keep in Claude ─────────────────────────> Use Claude's native tools

Keyword Registry (Delegates to gemini-cli-docs)

Topic Query Keywords

Headless mode headless json output , output format , -p flag

Sandboxing sandbox docker podman , seatbelt , -s flag

Checkpointing checkpoint restore , rollback , /restore command

Interactive interactive shell , enableInteractiveShell , PTY

Model selection model routing , flash vs pro , -m flag

Auto-approve yolo mode , --yolo , auto approve

Error Handling

Common Errors and Recovery

Error Cause Recovery

JSON parse error Malformed output Retry with --output-format json

Timeout Long-running task Increase timeout, use streaming

Auth error Missing credentials Check gemini auth status

Sandbox error Missing container Build sandbox image first

Retry Strategy

Retry with exponential backoff

for i in 1 2 4; do result=$(gemini "query" --output-format json 2>&1) && break sleep $i done

References

Query gemini-cli-docs for official documentation on:

• "headless mode usage"

• "sandbox configuration"

• "checkpointing setup"

• "model selection"

Test Scenarios

Scenario 1: Delegation Decision

Query: "Should I delegate this task to Gemini?" Expected Behavior:

• Skill activates on "delegate to gemini" or "which agent"

• Consults decision matrix Success Criteria: User receives clear recommendation with rationale

Scenario 2: TUI Handoff

Query: "I need to run git rebase -i, can Claude do this?" Expected Behavior:

• Skill activates on "interactive" or "rebase"

• Recommends gemini-interactive-shell agent Success Criteria: User understands TUI limitation and handoff pattern

Scenario 3: Bulk Analysis

Query: "I have a 100K+ token codebase to analyze" Expected Behavior:

• Skill activates on "large file" or "bulk analysis"

• Recommends gemini-bulk-analyzer agent Success Criteria: User receives Gemini delegation recommendation

Version History

• v1.1.0 (2025-12-01): Added Test Scenarios section

• v1.0.0 (2025-11-25): Initial release