gemini-skill

A Claude Code skill that delegates coding tasks to Gemini CLI and supervises the result.

Claude orchestrates. Gemini codes. You review the diff.

What it does

When you type /gemini <instruction> in Claude Code, this skill:

1. Decomposes the task into atomic sub-tasks (if needed)
2. Chooses a mode: impl (writes files) or plan (read-only exploration)
3. Runs gemini-delegate — a shell script that launches Gemini CLI in headless mode
4. Streams structured output: [read], [write], [plan-write], [WARN], [SYNTAX ERROR]
5. Runs post-run syntax checks on modified .py and .js files automatically
6. Reports the git diff and any issues to you
7. Appends a structured JSON entry to ~/.local/share/delegate-runs.jsonl (tokens, cost, duration, exit code)

Prerequisites

• Gemini CLI installed and authenticated (gemini --version)
• Claude Code with skills enabled
• python3 available (for the streaming parser and syntax checks)
• node available (optional — for JS syntax checks)
• A git repository to work in

Installation

git clone https://github.com/pcx-wave/gemini-skill.git && cd gemini-skill && mkdir -p ~/tools ~/.claude/skills/gemini && ln -sf "$(pwd)/tools/gemini-delegate" ~/tools/gemini-delegate && ln -sf "$(pwd)/tools/delegate-report" ~/tools/delegate-report && chmod +x ~/tools/gemini-delegate ~/tools/delegate-report && ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/gemini/SKILL.md

Step-by-step

# 1. Clone this repo
git clone https://github.com/pcx-wave/gemini-skill.git
cd gemini-skill

# 2. Install the scripts (symlinks — stay in sync with git pull)
mkdir -p ~/tools
ln -sf "$(pwd)/tools/gemini-delegate" ~/tools/gemini-delegate
ln -sf "$(pwd)/tools/delegate-report" ~/tools/delegate-report
chmod +x ~/tools/gemini-delegate ~/tools/delegate-report

# 3. Install the skill for Claude Code
mkdir -p ~/.claude/skills/gemini
ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/gemini/SKILL.md

# 4. (Optional) Enable auto-mode — Claude delegates all code tasks automatically
#    without requiring /gemini each time. Toggle with /geminion and /geminioff.
grep -q "gemini auto-mode" ~/.claude/CLAUDE.md 2>/dev/null || cat >> ~/.claude/CLAUDE.md << 'EOF'

# gemini auto-mode
At the start of every user request that involves writing, editing, or fixing code:
1. Run `test -f ~/.local/share/gemini-auto.flag` (silent, no output to user).
2. If the flag exists → automatically invoke the `gemini` skill exactly as if the user had typed `/gemini <their full instruction>`. Do NOT ask first, do NOT explain — just delegate.
3. If the flag is absent → proceed normally.

The flag is toggled by `/geminion` and `/geminioff`.
EOF

Verify the install

# Check gemini is available
gemini --version

# Test the delegate script (plan mode — no writes)
~/tools/gemini-delegate /tmp "Say hello in one sentence." 120 plan
# Should print: [gemini] Hello! ...

Updating

Because the install uses symlinks, a git pull is all you need:

cd ~/gemini-skill && git pull

~/tools/gemini-delegate and all skill files are automatically up to date — no re-copy needed.

Usage

In a Claude Code session, just describe what you want:

/gemini add a dark mode toggle to the settings page

/gemini the login form is not validating the email field — fix it

/gemini read the route structure in app.py and summarise it

Claude will decompose the task, choose the right mode, write the Gemini prompt, supervise execution, and report the diff.

Two modes

In plan mode, any write Gemini proposes is shown as [plan-write] but never executed — useful for understanding a codebase before touching it.

How gemini-delegate works

Claude Code
  └─ /gemini <instruction>
       └─ SKILL.md logic
            └─ ~/tools/gemini-delegate <workdir> <prompt> [timeout] [mode]
                 ├─ writes prompt to temp file (avoids shell injection with UTF-8/emoji)
                 ├─ selects --yolo (impl) or --approval-mode plan
                 ├─ runs: gemini -p "$PROMPT" $APPROVAL_FLAG -o stream-json
                 │         └─ no pseudo-TTY needed (unlike Vibe)
                 ├─ pipes stream-json events through Python parser
                 │         └─ handles: init / message / tool_call / tool_result / result
                 │         └─ prints [init] / [read] / [write] / [plan-write] / [gemini] / [WARN]
                 ├─ reads real token counts from the stream-json result event
                 ├─ runs syntax checks on modified .py and .js files (skipped in plan mode)
                 ├─ prints git diff --stat (skipped in plan mode)
                 └─ appends JSON entry to ~/.local/share/delegate-runs.jsonl

Why no pseudo-TTY?

Unlike Mistral Vibe, Gemini CLI works fine in a plain pipe — no TTY check on startup. This simplifies the script significantly compared to vibe-delegate.

Why prompt via temp file?

Inline shell arguments break when the prompt contains Python dict syntax, emojis, accented characters, or multi-line code. Writing to a temp file avoids all shell injection issues.

Why a timeout instead of --max-turns?

Gemini CLI has no --max-turns flag. The timeout is the only runaway-control lever. The 503 backoff on the free tier can silently consume 60–90s before work begins — always budget for this in your timeout value.

Token economics

Gemini's internal tool calls consume Gemini tokens, not Claude tokens. Claude only receives the compressed final output (~200–800 tokens/run).

Approximate pricing (Gemini 2.5 Flash):

• ~$0.15/M input tokens, ~$0.60/M output tokens
• Claude Sonnet 4.6: ~$3/M input, ~$15/M output
• Typical ratio: ~20–30x cheaper per token than Claude

Note: Gemini CLI loads a large system prompt (~900–10k tokens) before each task, so actual per-run cost is higher than token math alone suggests.

Free-tier caps (Google AI Studio):

• ~60 requests/minute, ~1,000 requests/day
• 503 errors = rate cap or demand spike → auto-retried with backoff

Real token counts and cost are printed after every run and appended to the run log.

Known limitations

Customization

Edit ~/.claude/skills/gemini/SKILL.md:

• Known projects table — list your repos with their absolute paths
• Timeout defaults — adjust per project complexity
• Mode preference — default to plan for exploratory projects

Run Log

Every run appends one JSON entry to ~/.local/share/delegate-runs.jsonl. The shared ~/tools/delegate-report script can query all runs across delegates.

~/tools/delegate-report                  # full report
~/tools/delegate-report --since 7        # last 7 days
~/tools/delegate-report --fails          # failures only

Sister projects

• vibe-skill — delegate to Mistral Vibe
• opencode-skill — delegate to OpenCode CLI

All three write to the same delegate-runs.jsonl log, making runs comparable across delegates.

License

MIT