gemini-skill-install 0.1.2

Bootstrap installer for the gemini Claude Code skill

gemini-skill

A Claude Code skill for broad Gemini REST API access — text generation, multimodal input, image/video/music generation, embeddings, caching, batch processing, search grounding, code execution, file search, and more.

Quick Start

1. Installation

   See install.md for detailed setup and update paths.

   uvx gemini-skill-install
   

   or fallback if there are errors

   uvx --python 3.13 gemini-skill-install
   

   Or with pipx:

   pipx install gemini-skill-install
   

   or fallback if there are errors

   pipx install --python 3.13 gemini-skill-install
   

2. Fallback: install from a clone or release tarball

   git clone https://github.com/reshinto/gemini-skill.git
   cd gemini-skill
   python3 setup/install.py
   

   Both installer entry points call the same core installer. They:

   • Copy operational files to ~/.claude/skills/gemini/
   • Includes the runtime payload: SKILL.md, VERSION, core, adapters, reference, registry, scripts, and setup/{update.py,requirements.txt}
   • Creates ~/.claude/skills/gemini/.venv with pinned google-genai
   • Verifies install integrity via SHA-256 checksums
   • Prompts for Gemini API key (hidden input)
   • Merges env block into ~/.claude/settings.json (with conflict resolution)
   • Reuses an existing skill-local .venv on overwrite installs

3. Set your Gemini API key (get one at aistudio.google.com/apikey)

   The installer prompts you interactively. If you need to manually edit, add/update the env block in ~/.claude/settings.json:

   {
     "env": {
       "GEMINI_API_KEY": "AIzaSy...",
       "GEMINI_IS_SDK_PRIORITY": "true",
       "GEMINI_IS_RAWHTTP_PRIORITY": "false",
       "GEMINI_LIVE_TESTS": "0"
     }
   }
   

   Claude Code injects these values into the process env at session start.

   Do NOT edit the repo-root .env — that's only for local development from a clone. For the installed skill, use ~/.claude/settings.json exclusively.

4. Fully restart Claude Code (⌘Q on macOS, not "Reload Window"). Skill discovery and env injection happen at IDE launch.

5. Use it in Claude Code

   /gemini text "Explain quantum computing"
   

Architecture

Features

• Text generation, multimodal input, structured output, function calling
• Image generation (Nano Banana, Imagen 3), video generation (Veo), music generation (Lyria 3)
• Embeddings, context caching, batch processing, token counting
• Google Search grounding, Google Maps grounding, code execution
• File API, File Search / hosted RAG
• Deep Research (Interactions API), Computer Use (preview)
• Live API realtime sessions (async dispatch)
• Automatic model routing by task type and complexity
• Two-phase cost tracking (pre-flight estimate + post-response)
• Multi-turn conversation sessions with Gemini
• Dual transport backend — google-genai SDK primary + urllib raw HTTP fallback, user never picks

Prerequisites

• Python 3.9+
• A Gemini API key
• google-genai==1.33.0 (installed automatically by the installer into ~/.claude/skills/gemini/.venv)

Documentation

Start here: docs/README.md — the single index hub for every doc and reference page.

Most-read pages

• Design patterns — what / where / why / how for every architectural decision in the codebase (Adapter, Facade, Capability registry, Coordinator, Anti-corruption layer, Atomic write, SHA-256 integrity, etc.). Read this first if you're touching the code.
• Security & secrets storage — full threat model + the "How the skill stores secrets and why it's safe" section explaining where GEMINI_API_KEY lives, why the chosen storage location is safe, alternatives rejected, and rotation procedure.
• Usage tour — 16 end-to-end examples (text, multimodal, streaming, function calling, search grounding, image gen, batch, caching, sessions, dry-run vs --execute, error recovery).
• Per-command reference — detailed docs for all 22 commands. Every page covers what / which model(s) / why (vs alternatives) / how (concrete usage).

Reference catalogs (single-page lookups)

• Flags reference — every CLI flag the skill accepts, grouped by category (privacy, cost, execution, I/O), with rationale.
• Models reference — every model in the registry with cost tier, capabilities, and "when to pick this over siblings".

Architecture & internals

• Architecture — System design, module layout, dual-backend transport diagram, "Why SKILL.md is terse" (token optimization rationale).
• How It Works — End-to-end execution trace.
• Model Routing — Router decision tree.
• Capabilities — Feature matrix with status and limitations.
• Commands — Command index by capability family.

Operating the skill

• Installation — Setup, troubleshooting, API key configuration.
• Usage — Getting started and common workflows.
• Update & Sync — Install mechanism, release checking, rollback, and release publishing.

Contributors

• Contributing — Adding adapters, code style, PRs, strict typing rule.
• Testing — Running tests, writing tests, coverage, live API smoke tests.
• Python Design — Python 3.9+ floor, no typing.Any, idiomatic patterns.

Diagrams

All diagrams are committed as both Mermaid source (.mmd) and rendered SVG with white background under docs/diagrams/:

• architecture-dual-backend.svg — high-level dual-backend transport
• coordinator-decision-flow.svg — fallback eligibility + capability gate
• backend-priority-matrix.svg — env flag truth table
• auth-resolution.svg — GEMINI_API_KEY precedence
• install-flow.svg — installer pipeline
• secrets-flow.svg — secret storage data flow + threat boundaries
• design-patterns-overview.svg — class-diagram-style pattern map
• command-dispatch-flow.svg — request lifecycle from /gemini to stdout
• token-optimization-flow.svg — why SKILL.md stays small

Regenerate any diagram with bash scripts/render_diagrams.sh [name].

Releases

Tagged releases (v*) run .github/workflows/release.yml. The workflow verifies VERSION, builds the GitHub release tarball plus Python wheel/sdist artifacts, writes checksums.txt, creates the GitHub Release, and publishes gemini-skill-install to PyPI via Trusted Publishing.

Maintainers can cut a release tag from the current VERSION with:

bash scripts/tag_release.sh

See docs/update-sync.md for the full release flow.

Backends

By default, the skill uses the google-genai SDK as the primary backend, with urllib raw HTTP as the fallback. Both backends return identical response shapes via the normalize layer — adapters never know which ran.

To invert backend priority (raw HTTP primary, SDK fallback), edit ~/.claude/settings.json:

{
  "env": {
    "GEMINI_IS_SDK_PRIORITY": "false",
    "GEMINI_IS_RAWHTTP_PRIORITY": "true"
  }
}

Restart Claude Code. Both flags cannot be false (ConfigError), and if both are true, SDK wins.

License

MIT