Gemini CLI Skill Skill | Agent Skills

Gemini CLI Skill

Headless wrapper for Google Gemini CLI. Sends prompts via stdin to gemini -p "" --yolo. Free tier available — no API key required (Google OAuth only).

When to Use

Get a Google Gemini perspective on any question
Free-tier AI consultation (no API key costs)
Code review from Gemini's model
Brainstorming and analysis tasks
Cross-validation of Claude's own responses
Large files or codebases that benefit from Gemini's context window
Sandbox execution (run/test code via Gemini)

Response Times

Gemini CLI runs as a subprocess and includes model startup time:

Simple Q&A / news query: ~2 minutes
Codebase or large-file review: ~5–10 minutes

Set expectations with the user before running long tasks.

Usage

Ask a question

node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "What is the best caching strategy for a Node.js API?"

Specify model (short or long flag)

node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Explain async/await" --model gemini-2.5-flash
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Explain async/await" -m gemini-2.5-flash

JSON output

node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "List 5 design patterns" --json
# Returns: {"response":"..."} on success, {"error":"...","raw":"..."} on parse failure

Code sandbox (short or long flag)

node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Write and run a fibonacci function" --sandbox
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Write and run a fibonacci function" -s

Stdin usage

echo "Explain recursion" | node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs

File review (embed content in prompt)

node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Review this code: $(cat src/auth.ts)"

Availability Check

node .claude/skills/omega-gemini-cli/scripts/verify-setup.mjs
# Exit 0 = available (Node 18+ and Gemini CLI found)
# Exit 1 = not installed or too old

Scripts

| Script | Purpose | | ------------------- | --------------------------------------------------------- | | ask-gemini.mjs | Core headless wrapper — sends prompt via stdin | | parse-args.mjs | Argument parser (--model/-m, --json, --sandbox/-s) | | verify-setup.mjs | Availability check (Node 18+, Gemini CLI via PATH or npx) | | format-output.mjs | Output normalization (JSON envelope handling) |

Flags

| Flag | Short | Description | | --------------- | ----- | ----------------------------------------------------------- | | --model MODEL | -m | Gemini model (e.g., gemini-2.5-flash, gemini-2.5-pro) | | --json | | Machine-readable JSON output: {"response":"..."} envelope | | --sandbox | -s | Code execution sandbox mode |

Models (2026)

| Model ID | Notes | | ------------------------ | ------------------------------------- | | gemini-3-pro-preview | Latest (2026), highest capability | | gemini-3-flash-preview | Latest (2026), faster | | gemini-2.5-pro | Stable, high capability | | gemini-2.5-flash | Recommended: lower quota/latency | | gemini-2.5-flash-lite | Lightest, fastest, lowest quota usage |

Exit Codes

| Code | Meaning | | ---- | --------------------------------------------------------------- | | 0 | Success | | 1 | Error (CLI failure, auth issue, JSON parse failure with --json) | | 9009 | Windows: command not found (falls back to npx automatically) |

Slash Commands (when installed in a project with .claude/commands/)

| Command | Purpose | | --------------------- | ----------------------------------------------------------------------- | | /analyze | Run headless script with user's prompt (and any @ file refs) | | /sandbox | Run with --sandbox; execute or test code | | /omega-gemini | Alias: run headless for analysis, sandbox, or brainstorm as appropriate | | /brainstorm | Brainstorm mode (build prompt with challenge + optional methodology) | | /omega-gemini-setup | Verify Node and Gemini CLI; guide user to install and auth. No MCP. |

Anti-Patterns & Iron Laws

ALWAYS use verify-setup.mjs before first use
NEVER pass prompt as positional arg to raw gemini CLI — use ask-gemini.mjs wrapper
ALWAYS validate model parameter (wrapper validates via regex ^[a-zA-Z0-9._-]+$ on Windows)
NEVER assume gemini is on PATH — wrapper handles npx @google/gemini-cli fallback automatically
ALWAYS handle exit code 1 and 9009 gracefully
ALWAYS set user expectations about response time before running (2–10 minutes typical)

Integration Notes

Auth: One-time Google OAuth via gemini interactive session (run gemini once to sign in)
Rate limits: Governed by Gemini API quotas (generous for personal use on free tier)
Platform: Full cross-platform; Windows uses shell: true with model validation; non-Windows uses array args (no shell)
npx fallback: On PATH miss, automatically retries with npx -y @google/gemini-cli
No timeout flag: Unlike other omega wrappers, gemini wrapper has no --timeout-ms
Stdin delivery: Prompt always sent via stdin to avoid shell argument length limits (8191-char cmd.exe limit on Windows, ARG_MAX on Linux/macOS)
JSON envelope: --json wraps output as {"response":"..."} on success or {"error":"...","raw":"..."} on failure

Requirements

Node.js 18+ to run the scripts
Google Gemini CLI (npm install -g @google/gemini-cli) with one-time Google sign-in

Memory Protocol

Before work: Read .claude/context/memory/learnings.md After work: Append findings to learnings or issues as needed.

Note: Use pnpm search:code to discover references to this skill codebase-wide.

Agent Skills: Gemini CLI Skill

Install this agent skill to your local

Skill Files