claudetools/.claude/skills/agy/SKILL.md

name, description

name

description

agy

Route a task to the official Google Gemini CLI for an independent second model — a sibling of the `grok` second-opinion router. Use for: an independent, different-vendor SECOND OPINION or adversarial VERIFICATION of a Claude finding/design before acting on it, a Gemini code REVIEW of a file / set of files / git diff, and one-shot Gemini TEXT answers. Invoke on: "ask gemini", "gemini verify", "second opinion from gemini", "gemini review", "agy ...". Gemini is an independent second model (and Google-ecosystem reach), NOT a replacement for Claude's own codebase work.

AGY — Gemini capability router

Claude shells out to the locally-installed Google Gemini CLI (gemini, npm global, v0.45.2) for a genuinely independent, different-vendor second model. AGY is the sibling of grok: both are second-opinion / review routers. Use whichever you want a second model from (or both, to triangulate). Verified working on this machine (2026-06-05; re-validated 2026-06-17 against the CLI's bundled help/README — JSON schema, all flags, pinned model, and live search all confirmed): text, verify, review (single file / file set / git diff), image-analyze (vision input), search (live Google web search). All KEYLESS — they work on Google OAuth, no API key.

Auth: Gemini uses Google login (OAuth) — no API key. Creds live at ~/.gemini/oauth_creds.json. If calls fail with an auth error, run gemini interactively once and choose "Login with Google", then retry.

The wrapper

bash "$CLAUDETOOLS_ROOT/.claude/skills/agy/scripts/ask-gemini.sh" <mode> ...

Mode	Usage	What it does
text	ask-gemini.sh text "<prompt>" or text --prompt-file <path>	One-shot text answer from an independent model. --prompt-file for long content (review/summarize a doc). Default model routing.
verify	ask-gemini.sh verify "<claim/finding>" or verify --prompt-file <path>	Adversarial second opinion — Gemini tries to REFUTE / find gaps, returns a verdict + reasons. Pinned to the strong model.
review	ask-gemini.sh review <file-path> ["<instructions>"]	Gemini reads the file itself (its read_file tool, read-only plan mode) and reviews it. Path resolution: absolute, CWD-relative, or relative to $CLAUDETOOLS_ROOT — see the path gotcha below. Spaces OK. Works even on gitignored files.
review-files	ask-gemini.sh review-files [-i "<instr>"] <f1> [f2 …]	Review a set of files together (cross-file consistency, multi-file change). Same path resolution as review (see gotcha below); spaces OK. No code passed as a shell arg.
review-diff	ask-gemini.sh review-diff [-C <repo-dir>] [-i "<instr>"] <gitref> [-- <pathspec>]	Review a git diff (git diff <gitref> from <repo-dir>; default repo root, use -C for a submodule e.g. -C projects/msp-tools/guru-rmm). Diff goes via the prompt file; Gemini can read_file changed files for full context.
image-analyze	ask-gemini.sh image-analyze <image-path> ["<question>"]	Vision — Gemini read_files the image and describes/answers about it. Pins the pro vision model (the default flash-lite router hallucinates image content). Path absolute or repo-relative; spaces OK. KEYLESS (works on OAuth).
search	ask-gemini.sh search "<query>" (or search --prompt-file <path>)	Live Google web search (sibling of grok xsearch) — Gemini uses its google_web_search tool and returns the answer with source URLs. KEYLESS (works on OAuth).
raw	ask-gemini.sh raw <gemini args...>	Escape hatch — passes args straight to gemini.

The script runs Gemini headless with -o json, extracts the answer from .response (parsing from the first { so the CLI's cosmetic warning lines are ignored), and keeps stderr separate from the JSON so 429-backoff / warning noise never corrupts the parse.

Warning

Path gotcha for review / review-files (this has bitten us repeatedly). A relative path is resolved against ONLY two roots: your current directory, and $CLAUDETOOLS_ROOT (/d/claudetools). It is NOT resolved against a submodule or any arbitrary subdir. So a path like server/src/api/auth.rs that is relative to a submodule (e.g. projects/msp-tools/guru-connect/) fails with file not found whenever your CWD isn't that submodule — even though the file obviously exists. When reviewing files in a submodule or any non-root subtree, pass ABSOLUTE paths (e.g. build the list with find "$(pwd)/server/src" -name '*.rs' from inside the submodule). Absolute paths always work regardless of CWD and tolerate spaces. (For review-diff, the analogous fix is -C <submodule-dir>.)

Model

• text uses Gemini's default routing (currently a flash-tier model) — fast, cheap.
• verify / review* pin a strong model — gemini-3.1-pro-preview (verified available 2026-06-05, still valid 2026-06-17; the GA-looking gemini-3.1-pro and gemini-3-pro both ModelNotFoundError, so keep the -preview suffix).
• Override either with GEMINI_MODEL=<id> (e.g. GEMINI_MODEL=gemini-2.5-pro).
• image-analyze and search also pin the strong model (GEMINI_MODEL still honored).

Multimodal: image INPUT works, image GENERATION does not

• Image INPUT (vision) works on OAuth — image-analyze reads an image with the pinned pro vision model and describes it correctly. The default flash-lite router HALLUCINATES image content, which is why the pro model is pinned.
• Image GENERATION (nano-banana) does NOT work on OAuth — it needs a Google AI Studio NANOBANANA_API_KEY plus the nanobanana extension. Deferred for now. Image/video generation stays GROK's lane (grok image / grok video); AGY's multimodal support is read/analyze only.

Machine availability (fleet)

AGY is per-machine — the skill syncs fleet-wide but the gemini binary does not. Availability is gated by identity.json (per-machine, gitignored):

"gemini": { "installed": true,
            "binary": "C:/Users/guru/AppData/Roaming/npm/gemini",
            "auth": "oauth", "is_fleet_host": true,
            "capabilities": ["text","verify","review","image-analyze","search"] }

• If gemini.installed is false (or the block is absent), ask-gemini.sh exits 3 with routing guidance instead of failing obscurely. Claude on such a machine should NOT attempt local Gemini.
• Fleet Gemini hosts: GURU-5070, GURU-BEAST-ROG — machines with the Gemini CLI installed and Google-OAuth'd. When others get it, install @google/gemini-cli, run gemini once to log in with Google, then set their identity.json gemini block (and update this line).

Remote routing (NOT yet wired): a non-host machine cannot run Gemini locally. To fulfill an AGY request from elsewhere, route it to the host (GURU-5070) — same pending channels as Grok (GuruRMM agent exec, a relay, or a coord-API job queue). Until that's built, AGY requests originate on the host machine.

When to route to Gemini (AGY)

• Independent verification — a genuinely different vendor/model to red-team a Claude finding or design before acting on it. (verify)
• Second-model code review — have Gemini read and critique a file, a set of files, or a diff independently of Claude. (review, review-files, review-diff)
• Diverse drafts / second opinion — alternative phrasing or approach to compare. (text)
• Google-ecosystem reach — when a Google-side model/behavior is specifically wanted as the comparison point.

AGY and GROK are sibling second-opinion routers. Pick one, or run both and compare — disagreement between them is a strong signal to slow down.

When NOT to

• Pure classify / extract / summarize → cheaper via Tier-0 Ollama (.claude/OLLAMA.md).
• Editing this repo's code → Claude's own agents own the codebase work. Gemini's review* modes are read-only (--approval-mode plan) by design; do not give Gemini write access to this repo.
• Image / video generation → that's GROK's lane (grok image / grok video), not Gemini here (nano-banana needs an API key — deferred). Gemini CAN analyze an image you give it (image-analyze, vision input on OAuth).
• Never delegate unsupervised destructive / production actions to Gemini. Always review Gemini output before acting on it — like Grok, it can over-claim.

Safety / operational notes

• --skip-trust is REQUIRED for headless runs (the CWD isn't a Gemini "trusted folder"). Equivalent env: GEMINI_CLI_TRUST_WORKSPACE=true. The wrapper passes it.
• review* runs under --approval-mode plan (read-only): Gemini can read files but cannot modify anything. Do not change this to auto_edit/yolo.
• Gemini's read_file honors .gitignore and a workspace sandbox (only files inside the workspace are readable). The wrapper sidesteps both by copying each review target into a temp dir added via --include-directories — so review works for tracked, gitignored, and spaced-path files alike.
• Prompts are passed via -p "$(cat <prompt-file>)" built from a temp file, not inline shell args (avoids quote hell with long/structured content).
• stdin is always closed (</dev/null) so -p never hangs waiting on stdin.
• stdout carries two cosmetic warning lines ("True color (24-bit) support not detected", "Ripgrep is not available...") before output; JSON extraction from the first { ignores them. A transient 429 No capacity backoff may appear on stderr and self-recovers — it does not affect the parsed answer.

Reference

• Binary: npm global gemini (C:/Users/guru/AppData/Roaming/npm/gemini on the host; the npm global dir is on PATH). The wrapper auto-locates it or honors GEMINI=.
• Version 0.45.2. Auth: Google OAuth (~/.gemini/oauth_creds.json), no API key.
• Headless contract: gemini -p "<prompt>" -o json --skip-trust </dev/null → {session_id, response, stats}; answer is .response.
• Sibling router: grok (image/video/live-data + second opinion).