Gemini Delegate

Gemini Delegate Skill

Claude is the supervisor. Antigravity CLI (agy) drafts and synthesizes; the legacy Gemini CLI backend is fail-closed since 2026-06-18 (the wrapper refuses it with FATAL + exit 1 unless GEMINI_DEPRECATED_OVERRIDE=1 is explicitly set — the killed consumer tier makes non-interactive gemini silently emit pseudo-code). Claude reviews terminology, facts, tone, and decides what ships.

Why use this instead of raw CLI calls

This wrapper exists because the Google CLI backends have three footguns that silently break shipping tasks if you bypass it:

Measured token savings (real dogfood, not estimates)

From a 6-round mixed-workload session (awesome-agentic-ai-zh 2026-05-14, see agent-collab-skills/docs/measured-benefits.md):

Anti-patterns this skill prevents

• F1: gemini -p "Read .ai/foo.md" silently skips the brief because .ai/ is gitignored. Prevented by the wrapper's stdin-pipe pattern (cat .ai/foo.md | agy -m gemini-2.5-pro --yolo - or gemini -m gemini-2.5-pro --approval-mode yolo < .ai/foo.md).
• F13 ("liar mode"): Gemini reports task complete without actually writing output files. Prevented by the wrapper's --verify-file post-check that fails the run if the expected file is missing or unchanged.
• F14: Operator (Claude) defaults to Bash("gemini -p ...") despite the rule saying use Skill("gemini-delegate"). Prevented by a PreToolUse hook on the operator side (template below).

CLAUDE.md snippet to enforce routing

Drop this into your ~/.claude/CLAUDE.md (or repo-level CLAUDE.md) so the rule is operational, not aspirational:

## Gemini routing rule (enforced)

For any task that is long-context CJK / Chinese narrative, multi-paper
synthesis, second-opinion review, or terminology audit across long docs:
invoke `Skill("gemini-delegate", args="brief=...")`. Do NOT use
`Bash("gemini -p ...")` or raw `agy` unless you also preserve the wrapper
contract. Raw calls trigger F1 (silent skip of .ai/ brief), F13 (liar mode
without --verify-file), and approval-mode hangs.

The wrapper auto-detects `agy` or legacy `gemini`. If you must use a raw
call, use one of these canonical stdin-pipe patterns and cap logs:

  cat .ai/gemini_task_<NNN>.md | agy -m gemini-2.5-pro --yolo - 2>&1 | head -c 10485760
  gemini -m gemini-2.5-pro --approval-mode yolo < .ai/gemini_task_<NNN>.md 2>&1 | head -c 10485760
Optional mechanical enforcement: a PreToolUse hook on Bash that nudges raw
`gemini -p` toward `Skill("gemini-delegate")`. Reference:
https://github.com/WenyuChiou/dotfiles-claude/blob/main/hooks/check_codex_skill_routing.py
(same hook covers codex + gemini).

The hook excludes the canonical stdin-pipe pattern, so legitimate raw use passes silently. Only the F1-prone gemini -p "Read .ai/..." shape triggers the nudge.

Prerequisite check (do this first)

Before producing any task file, wrapper command, or handoff prompt, verify that a WORKING backend is on $PATH — only agy satisfies this by default; a gemini binary alone does NOT (the wrapper fail-closes on it):

if command -v agy >/dev/null 2>&1; then
  agy --version
elif command -v gemini >/dev/null 2>&1; then
  echo "gemini found, but the legacy backend is FAIL-CLOSED (2026-06-18) —"
  echo "the wrapper will refuse it (FATAL, exit 1) unless you have VERIFIED"
  echo "enterprise-tier access and set GEMINI_DEPRECATED_OVERRIDE=1."
  echo "Preferred: install Antigravity CLI: curl -fsSL https://antigravity.google/cli/install.sh | bash"
else
  echo "Install Antigravity CLI: curl -fsSL https://antigravity.google/cli/install.sh | bash"
  echo "(Legacy gemini is fail-closed by default — see the note below.)"
fi

If neither command is found, stop and tell the user:

This skill needs Antigravity CLI (agy) or legacy Gemini CLI. Install Antigravity CLI with:

curl -fsSL https://antigravity.google/cli/install.sh | bash
agy --version

The legacy Gemini CLI is NOT a working fallback: the wrapper fail-closes on a gemini backend (FATAL, exit 1) because the killed consumer tier makes it silently emit pseudo-code. Only an enterprise user who has VERIFIED their tier still works may opt in with GEMINI_DEPRECATED_OVERRIDE=1.

Then re-run your request.

Do not prepare a task prompt, write a wrapper command, or fabricate a result.json. Without a supported binary on PATH, every "successful" wrapper run is a hallucination.

Migration from Gemini CLI

Gemini CLI was deprecated for free/Pro/Ultra individual users on 2026-06-18. The wrapper detects AGY_PATH, then GEMINI_PATH, then agy on PATH, then gemini on PATH — but any gemini resolution fail-closes (FATAL + exit 1) unless GEMINI_DEPRECATED_OVERRIDE=1 is set. Existing wrapper commands, task brief names, and .ai/gemini_task_*.md conventions stay unchanged. For the maintained, evidence-backed Antigravity lane, prefer antigravity-delegate.

Hard rules

These three are non-negotiable. The wrapper enforces them; if you write your own wrapper, preserve all three:

1. No -C flag. cd into the target repo before invoking the backend. Neither agy nor gemini has -C.
2. Use --yolo for agy or --approval-mode yolo for gemini. The wrapper handles this automatically.
3. Pipe the prompt through stdin. agy requires the trailing - to read stdin; legacy gemini reads from redirected stdin.

The wrapper additionally verifies expected files when --verify-file is supplied.

When to delegate

Long-context synthesis or CJK writing -> Gemini / Antigravity CLI. Code execution -> Codex. Judgment / review / final acceptance -> Claude.

Full routing table and examples: references/delegation-targets.md.

Workflow

1. Brief: write .ai/gemini_task_<name>.md with Context / Goal / Language & tone / Constraints / Acceptance. Template: references/task-template.md. For a drift-sensitive task (published report, bilingual mirror, long-context synthesis, second-opinion review) — where an invented fact, a slipped term, or a wrong language variant would hurt — also add the XML prompt blocks from references/gemini-prompt-blocks.md to the Goal/Language/Constraints. A tiny low-stakes draft does not need them. If the brief was queued by agent-task-splitter (from the agent-collab-skills marketplace), it lives at .ai/gemini_task_<NNN>_<slug>.md; read .coord/plan.yml for round context first.

2. Run: from Claude Code Bash, invoke the wrapper from its install location. The command stays the same; the wrapper auto-detects agy or legacy gemini.

   bash ~/.claude/skills/gemini-delegate/scripts/run_gemini.sh \
     --prompt "Read .ai/gemini_task_<name>.md and execute all instructions inside." \
     --repo "$PWD" \
     --log-file .ai/gemini_log_<name>.txt \
     --verify-file <expected_output_path>
   

   --repo defaults to the caller's $PWD; pass --repo "$PWD" explicitly only if you want to be defensive about the working directory at invocation. On non-Claude-Code agentskills.io hosts, substitute the host's skills directory (e.g. ~/.hermes/skills/<category>/gemini-delegate/scripts/run_gemini.sh). PowerShell variant + env vars: references/wrapper.md.

3. Read status: cat .ai/gemini_log_<name>.txt.result.json.

   • success -> output still needs Claude publication review.
   • verify_failed -> process exited but expected files missing; treat as failure.
   • fallback -> quota hit; Claude takes over.
   • error -> hard failure; check <log>.error.

4. Publication review: factual accuracy, terminology consistency, dates / proper nouns, banned phrasing, audience fit. Extended checklist: references/review-checklist.md.

Output contract

.result.json includes at minimum: status (success | verify_failed | fallback | error), delegate ("agy" or "gemini"), model ("agy/<model>" or "gemini/<model>"), log_file, summary, risks, files_changed, tests_run, timestamp_utc. Full schema and status semantics: references/output-contract.md.

Common drift to watch

The model may drift terminology mid-document, over-translate proper nouns, miss project-specific banned phrases, invent dates if the brief is underspecified, or switch between Simplified and Traditional Chinese mid-paragraph. Never ship its output unreviewed.

Compatibility

• Antigravity CLI (agy) is the preferred backend for free/Pro/Ultra individual users. It reads stdin with a trailing - and uses --yolo for approval.
• Legacy @google/gemini-cli is fail-closed by the wrapper (FATAL + exit 1) since 2026-06-18; enterprise/Cloud users who have verified their tier must set GEMINI_DEPRECATED_OVERRIDE=1 to use it. Last tested working: @google/gemini-cli 0.38.2 (May 2026, pre-deprecation). Approval modes available: default, auto_edit, yolo, plan.
• Default model: gemini-2.5-pro (override via --model or -Model). For long-form CJK quality, prefer the latest Pro model available on your CLI.
• Backend detection order: AGY_PATH, GEMINI_PATH, agy on PATH, gemini on PATH.
• Prompt MUST be piped via stdin. The wrapper handles the backend-specific stdin pattern.
• No -C flag exists; the wrapper uses pushd / Push-Location. --include-directories exists on legacy Gemini CLI but has known path-resolution bugs and is not recommended.
• PowerShell wrapper requires $ErrorActionPreference to NOT be Stop so backend stderr banners do not trip the catch block.

See also

• references/delegation-targets.md — when to use vs avoid
• references/wrapper.md — full wrapper invocation, env vars, sentinels
• references/task-template.md — CJK-aware task brief template
• references/gemini-prompt-blocks.md — XML prompt blocks + recipes + anti-patterns for drift-sensitive briefs
• references/output-contract.md — full .result.json schema, status semantics, .fallback_claude quota sentinel
• references/review-checklist.md — extended publication gate
• references/multi-agent.md — leaf role in router/leaves architecture; when to route through research-hub-multi-ai or agent-task-splitter
• references/examples.md — concrete invocation examples (long-context summary, CJK report, bilingual README, second-opinion review)