gemini-delegation-patterns

Gemini Delegation Patterns

🚨 MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini CLI capabilities:

1. INVOKE gemini-cli-docs skill
2. QUERY for the specific feature topic
3. 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

1. Ensure checkpointing enabled in settings.json
2. Execute refactor via Gemini
3. Verify results (run tests)
4. /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)

1. Inform user of handoff requirement
2. Start Gemini with interactive flag
3. User interacts directly with PTY
4. 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