Gemini CLI Orchestrator - Cross-AI Task Delegation

Orchestrate Google's Gemini CLI for tasks that benefit from a second AI perspective, real-time web search via Google Search grounding, deep codebase architecture analysis, or parallel code generation.

Core Principle: Use Gemini for what it does best. Delegate, validate, integrate. The calling AI stays the conductor.

1. WHEN TO USE

Activation Triggers

Cross-AI Validation - Use when:

• Code review needs a second perspective after writing code
• Security audit benefits from alternative analysis
• Bug detection where fresh eyes help

Google Search Grounding - Use when:

• Questions require current internet information
• Checking latest library versions, API changes, documentation
• Finding community solutions or recent best practices

Codebase Architecture Analysis - Use when:

• Onboarding to an unfamiliar codebase
• Mapping cross-file dependencies and component relationships
• Creating architecture documentation from existing code

Parallel Task Processing - Use when:

• Offloading generation tasks while continuing other work
• Running multiple code generations simultaneously
• Background documentation or test generation

Agent-Delegated Tasks - Use when:

• Task matches a specialized Gemini agent's expertise
• Deep investigation benefits from Gemini's 1M+ token context
• Multi-strategy planning needs an independent perspective

Specialized Generation - Use when:

• User explicitly requests Gemini operations
• Test suite generation for entire modules
• Code translation between languages
• Batch documentation generation (JSDoc, README, API docs)

When NOT to Use

• Self-invocation guard: If you ARE Gemini CLI (running natively inside a Gemini CLI session), do NOT use this skill. You already have direct access to all capabilities described here — google_web_search, codebase_investigator, save_memory, and your agent system. Delegating to yourself via CLI is circular and wasteful. This skill is for EXTERNAL AIs (Claude Code, Codex, Copilot) to delegate TO Gemini CLI.
• Simple, quick tasks where CLI overhead is not worth it
• Tasks requiring immediate response (rate limits may cause delays)
• Context already loaded and understood by the current agent
• Interactive refinement requiring multi-turn conversation
• Tasks where Gemini CLI is not installed

2. SMART ROUTING

Prerequisite Detection

# Verify Gemini CLI is available before routing
command -v gemini || echo "Not installed. Run: npm install -g @google/gemini-cli"

Phase Detection

TASK CONTEXT
    |
    +- STEP 0: Verify Gemini CLI installed
    +- STEP 1: Score intents (top-2 when ambiguity is small)
    +- Phase 1: Construct prompt with agent routing
    +- Phase 2: Execute via Bash tool
    +- Phase 3: Validate and integrate output

Resource Domains

The router discovers markdown resources recursively from references/ and assets/ and then applies intent scoring from INTENT_SIGNALS.

references/cli_reference.md          — CLI flags, commands, config
references/integration_patterns.md   — Cross-AI orchestration patterns
references/gemini_tools.md           — Built-in tools (google_web_search, codebase_investigator)
references/agent_delegation.md       — Gemini agent routing and invocation
assets/prompt_templates.md           — Copy-paste ready templates

Resource Loading Levels

Smart Router Pseudocode

from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/cli_reference.md"

INTENT_SIGNALS = {
    "GENERATION":        {"weight": 4, "keywords": ["generate", "create", "build", "write code", "gemini create"]},
    "REVIEW":            {"weight": 4, "keywords": ["review", "audit", "security", "bug", "second opinion", "cross-validate"]},
    "RESEARCH":          {"weight": 4, "keywords": ["search", "latest", "current", "what's new", "google search", "web research"]},
    "ARCHITECTURE":      {"weight": 3, "keywords": ["architecture", "codebase", "investigate", "dependencies", "analyze project"]},
    "AGENT_DELEGATION":  {"weight": 4, "keywords": ["delegate", "agent", "background", "parallel", "offload", "gemini agent"]},
    "TEMPLATES":         {"weight": 3, "keywords": ["template", "prompt", "how to ask", "gemini prompt"]},
    "PATTERNS":          {"weight": 3, "keywords": ["pattern", "workflow", "orchestrate"]},
}

RESOURCE_MAP = {
    "GENERATION":        ["references/cli_reference.md", "assets/prompt_templates.md"],
    "REVIEW":            ["references/integration_patterns.md", "references/agent_delegation.md"],
    "RESEARCH":          ["references/gemini_tools.md", "assets/prompt_templates.md"],
    "ARCHITECTURE":      ["references/gemini_tools.md", "references/agent_delegation.md"],
    "AGENT_DELEGATION":  ["references/agent_delegation.md", "references/integration_patterns.md"],
    "TEMPLATES":         ["assets/prompt_templates.md", "references/cli_reference.md"],
    "PATTERNS":          ["references/integration_patterns.md", "references/cli_reference.md"],
}

LOADING_LEVELS = {
    "ALWAYS": [DEFAULT_RESOURCE],
    "ON_DEMAND_KEYWORDS": ["full reference", "all templates", "deep dive", "complete guide"],
    "ON_DEMAND": ["references/gemini_tools.md", "assets/prompt_templates.md"],
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Is the user asking about Gemini CLI specifically?",
    "Does the task benefit from a second AI perspective?",
    "Is real-time web information needed?",
    "Would codebase-wide analysis help?",
]

def _task_text(task) -> str:
    return " ".join([
        str(getattr(task, "text", "")),
        str(getattr(task, "query", "")),
        " ".join(getattr(task, "keywords", []) or []),
    ]).lower()

def _guard_in_skill(relative_path: str) -> str:
    resolved = (SKILL_ROOT / relative_path).resolve()
    resolved.relative_to(SKILL_ROOT)
    if resolved.suffix.lower() != ".md":
        raise ValueError(f"Only markdown resources are routable: {relative_path}")
    return resolved.relative_to(SKILL_ROOT).as_posix()

def discover_markdown_resources() -> set[str]:
    docs = []
    for base in RESOURCE_BASES:
        if base.exists():
            docs.extend(p for p in base.rglob("*.md") if p.is_file())
    return {doc.relative_to(SKILL_ROOT).as_posix() for doc in docs}

def score_intents(task) -> dict[str, float]:
    text = _task_text(task)
    scores = {intent: 0.0 for intent in INTENT_SIGNALS}
    for intent, cfg in INTENT_SIGNALS.items():
        for keyword in cfg["keywords"]:
            if keyword in text:
                scores[intent] += cfg["weight"]
    return scores

def select_intents(scores: dict[str, float], ambiguity_delta: float = 1.0, max_intents: int = 2) -> list[str]:
    ranked = sorted(scores.items(), key=lambda item: item[1], reverse=True)
    if not ranked or ranked[0][1] <= 0:
        return ["GENERATION"]  # zero-score fallback
    selected = [ranked[0][0]]
    if len(ranked) > 1 and ranked[1][1] > 0 and (ranked[0][1] - ranked[1][1]) <= ambiguity_delta:
        selected.append(ranked[1][0])
    return selected[:max_intents]

def route_gemini_resources(task):
    inventory = discover_markdown_resources()
    scores = score_intents(task)
    intents = select_intents(scores, ambiguity_delta=1.0)
    loaded = []
    seen = set()

    def load_if_available(relative_path: str) -> None:
        guarded = _guard_in_skill(relative_path)
        if guarded in inventory and guarded not in seen:
            load(guarded)
            loaded.append(guarded)
            seen.add(guarded)

    # 1. ALWAYS load baseline
    for relative_path in LOADING_LEVELS["ALWAYS"]:
        load_if_available(relative_path)

    # 2. UNKNOWN FALLBACK: no keywords matched at all
    if max(scores.values()) == 0:
        load_if_available("references/cli_reference.md")
        return {
            "intents": ["GENERATION"],
            "load_level": "UNKNOWN_FALLBACK",
            "needs_disambiguation": True,
            "disambiguation_checklist": UNKNOWN_FALLBACK_CHECKLIST,
            "resources": loaded,
        }

    # 3. CONDITIONAL: intent-mapped resources
    for intent in intents:
        for relative_path in RESOURCE_MAP.get(intent, []):
            load_if_available(relative_path)

    # 4. ON_DEMAND: explicit keyword triggers
    text = _task_text(task)
    if any(keyword in text for keyword in LOADING_LEVELS["ON_DEMAND_KEYWORDS"]):
        for relative_path in LOADING_LEVELS["ON_DEMAND"]:
            load_if_available(relative_path)

    # 5. Safety net
    if not loaded:
        load_if_available(DEFAULT_RESOURCE)

    return {"intents": intents, "intent_scores": scores, "resources": loaded}

3. HOW IT WORKS

Prerequisites

Gemini CLI must be installed and authenticated:

# Verify installation
command -v gemini || echo "Not installed. Run: npm install -g @google/gemini-cli"

# First-time authentication (interactive)
gemini

Authentication options: Google OAuth (free tier: 60 req/min, 1000 req/day), API key (export GEMINI_API_KEY=key), or Vertex AI (enterprise).

Core Invocation Pattern

All Gemini CLI calls follow this pattern:

gemini "[prompt]" -o text 2>&1

Model Selection

Gemini Agent Delegation

The calling AI acts as the conductor that delegates tasks to Gemini CLI. Gemini CLI has specialized agents in .gemini/agents/ that provide domain expertise. Route tasks to the right agent for best results.

Agent Routing Table:

Orchestration principle: The calling AI decides WHAT to delegate. The Gemini agent definition shapes HOW Gemini processes it. The calling AI always validates and integrates the output.

See agent_delegation.md for complete agent roster and invocation patterns.

Unique Gemini Capabilities

These tools are available only through Gemini CLI:

Essential Commands

# Code generation
gemini "Create [description] with [features]. Output complete file." --yolo -o text

# Code review (second opinion)
gemini "Review [file] for bugs and security issues" -o text

# Web research (Google Search grounding)
gemini "What's new in [topic]? Use Google Search." -o text

# Architecture analysis
gemini "Use codebase_investigator to analyze this project" -o text

# Background execution
gemini "[long task]" --yolo -o text 2>&1 &

# Explicit model (only supported model)
gemini "[prompt]" -m gemini-3.1-pro-preview -o text

Error Handling

4. RULES

✅ ALWAYS

ALWAYS do these without asking:

1. ALWAYS verify Gemini CLI is installed before first invocation

   • Run command -v gemini and handle missing installation gracefully

2. ALWAYS use -o text for human-readable output unless programmatic processing needed

   • Use -o json only when parsing stats or extracting structured data

3. ALWAYS validate Gemini-generated code before applying to the project

   • Check for security vulnerabilities (XSS, injection, eval)
   • Verify functionality matches requirements
   • Run syntax checks (node --check, tsc --noEmit, etc.)

4. ALWAYS capture stderr with 2>&1 to catch rate limit messages and errors

5. ALWAYS use gemini-3.1-pro-preview as the model — it is the only supported model

   • Invoke with -m gemini-3.1-pro-preview when explicit model selection is needed

6. ALWAYS route to the appropriate Gemini agent when the task matches an agent specialization

   • See agent routing table in Section 3

7. ALWAYS pass the spec folder to the delegated agent in the prompt

   • If the calling AI has an active spec folder (from Gate 3), include it in the prompt: Spec folder: <path> (pre-approved, skip Gate 3)
   • If the calling AI does NOT have a spec folder, it MUST ask the user for one BEFORE delegating — the delegated agent cannot answer Gate 3 interactively
   • This prevents the delegated agent from halting at the Gate 3 spec folder question in non-interactive mode
   • Example prompt suffix: \n\nSpec folder: .opencode/specs/02--system-spec-kit/022-hybrid-rag-fusion/022-spec-doc-indexing-bypass/ (pre-approved, skip Gate 3)

❌ NEVER

NEVER do these:

1. NEVER use --yolo on production codebases without explicit user approval

   • --yolo auto-approves file writes and shell commands; this can cause damage

2. NEVER trust Gemini output blindly for security-sensitive code

   • Always review for XSS, injection, hardcoded secrets, and eval() calls

3. NEVER send sensitive data (API keys, passwords, credentials) in prompts

   • Gemini CLI transmits prompts to Google's API

4. NEVER hammer the API with rapid sequential calls

   • Respect rate limits; use batch operations or background execution

5. NEVER use Gemini for tasks where context is already loaded

   • If the current agent already understands the code, direct action is faster

6. NEVER assume Gemini output is correct without verification

   • Cross-reference with the codebase and project standards

7. NEVER invoke this skill from within Gemini CLI itself

   • If you ARE Gemini CLI, you already have native access to all capabilities — do not self-delegate via CLI
   • Self-invocation creates a circular, wasteful loop; use your native tools directly instead

⚠️ ESCALATE IF

Ask user when:

1. ESCALATE IF Gemini CLI is not installed and user has not acknowledged

   • Provide installation command: npm install -g @google/gemini-cli

2. ESCALATE IF rate limits are persistently exceeded

   • Suggest API key setup or model fallback strategy

3. ESCALATE IF Gemini output conflicts with existing code patterns

   • Present both perspectives and let user decide

4. ESCALATE IF task requires --yolo on sensitive files

   • Describe risks and get explicit user approval

Memory Handback Protocol

When the calling AI needs to preserve session context from a Gemini CLI delegation:

1. Include epilogue: Append the Memory Epilogue template (see assets/prompt_templates.md §13) to the delegated prompt
2. Extract section: After receiving agent output, extract the MEMORY_HANDBACK section using: /<!-- MEMORY_HANDBACK_START -->([\s\S]*?)<!-- MEMORY_HANDBACK_END -->/
3. Parse to JSON: Map extracted fields to { sessionSummary, filesModified, keyDecisions, specFolder, triggerPhrases, nextSteps } (the save flow also accepts documented snake_case keys such as session_summary, files_modified, trigger_phrases, recent_context, and next_steps)
4. Redact and scrub: Remove secrets, tokens, credentials, and any unnecessary sensitive values before writing the JSON file
5. Write JSON: Save the scrubbed payload to /tmp/save-context-data.json
6. Invoke generate-context.js: node .opencode/skill/system-spec-kit/scripts/dist/memory/generate-context.js /tmp/save-context-data.json [spec-folder]
7. Index: Run memory_index_scan({ specFolder }) for immediate MCP visibility

Graceful degradation: If agent output lacks MEMORY_HANDBACK delimiters, the calling AI manually constructs the JSON from agent output and saves via the same JSON mode path. The save flow normalizes nextSteps or next_steps; the first entry persists as Next: ... and drives NEXT_ACTION, and remaining entries persist as Follow-up: ....

Explicit JSON mode failures: If the explicit data file cannot be loaded, generate-context.js fails with EXPLICIT_DATA_FILE_LOAD_FAILED: .... Do not fall back to OpenCode capture in that case; surface the error and stop.

Post-010 save gates: Valid JSON can still be rejected after normalization. File-backed handbacks skip the stateless alignment and QUALITY_GATE_ABORT checks, but they still fail with INSUFFICIENT_CONTEXT_ABORT when the payload is too thin and with CONTAMINATION_GATE_ABORT when it includes content from another spec.

Minimum payload guidance: Include a specific sessionSummary, at least one meaningful recentContext entry or equivalent observation, and rich FILES entries with a descriptive DESCRIPTION. Add ACTION, MODIFICATION_MAGNITUDE, and _provenance when known so the saved memory carries durable evidence instead of bare filenames.

5. REFERENCES

Core References

• cli_reference.md - Complete CLI command, flag, and slash command reference
• integration_patterns.md - Cross-AI orchestration patterns and workflows
• gemini_tools.md - Built-in tools documentation (google_web_search, codebase_investigator, save_memory)
• agent_delegation.md - Gemini agent roster, routing table, and invocation patterns

Templates and Assets

• prompt_templates.md - Copy-paste ready prompt templates for common tasks

Reference Loading Notes

• Load only references needed for current intent
• Keep Smart Routing (Section 2) as the single routing authority
• cli_reference.md is ALWAYS loaded as baseline

6. SUCCESS CRITERIA

Task Completion

• Gemini CLI invoked with correct flags and model selection
• Output captured, validated, and integrated appropriately
• No security vulnerabilities introduced from generated code
• Rate limits handled gracefully (retry or model fallback)
• Appropriate Gemini agent routed for specialized tasks

Skill Quality

• SKILL.md under 5000 words with progressive disclosure
• All 8 sections present with proper anchor comments
• Smart routing covers all intent signals with UNKNOWN_FALLBACK
• Reference files provide deep-dive content without duplication

7. INTEGRATION POINTS

Framework Integration

This skill operates within the behavioral framework defined in AGENTS.md.

Key integrations:

• Gate 2: Skill routing via skill_advisor.py
• Tool Routing: Per AGENTS.md Section 6 decision tree
• Memory: Context preserved via Spec Kit Memory MCP

Tool Usage

Related Skills

External Tools

Gemini CLI (required):

• Installation: npm install -g @google/gemini-cli
• Purpose: Core execution engine for all delegated tasks
• Fallback: Skill informs user of installation steps if missing

8. RELATED RESOURCES

Reference Files

• cli_reference.md - CLI flags, commands, and configuration
• integration_patterns.md - Cross-AI orchestration patterns
• gemini_tools.md - Built-in tools (google_web_search, codebase_investigator)
• agent_delegation.md - Agent routing and invocation

Templates

• prompt_templates.md - Copy-paste ready prompt templates

Related Skills

• sk-doc - Documentation generation that Gemini can supplement
• sk-code--web - Web development where Gemini provides second opinions
• sk-code--full-stack - Full-stack tasks with Gemini architecture analysis

External

• Gemini CLI GitHub - Official repository
• Google AI Studio - API key management