Gemini OCR Agent Skill

English

Purpose

gemini-ocr-agent-skill gives agents a dedicated Gemini file-analysis surface instead of forcing everything through the host model’s built-in vision behavior.

It is designed for two complementary workflows:

• promptable image/PDF analysis with free-text output
• document-focused OCR where PDFs and images can still be converted into faithful Markdown

Public release surfaces:

• GitHub repo: codecell-germany/gemini-pdf-img-ocr-agent-skill
• npm package: @codecell-germany/gemini-ocr-agent-skill
• CLI binary: gemini-ocr
• installer binary: gemini-ocr-skill
• skill name: gemini-ocr-cli

What the package contains

• A global CLI binary: gemini-ocr
• A skill installer binary: gemini-ocr-skill
• A Codex skill payload under skills/gemini-ocr-cli/
• Onboarding and command references for first-run agent workflows
• A generic analyze-file path for promptable file understanding
• Preset document-mode commands for Markdown-oriented OCR

Installation

1. Install the CLI globally

npm install -g @codecell-germany/gemini-ocr-agent-skill

2. Verify the public binaries

gemini-ocr --help
gemini-ocr-skill --help

3. Install the skill payload

gemini-ocr-skill install --force

Canonical first-run sequence

1. Verify the public CLI

gemini-ocr --help

2. Check the environment

gemini-ocr doctor --json

3. If setup is incomplete, print the setup guide

gemini-ocr setup --language en

4. Export one supported Gemini API key env var

export GEMINI_API_KEY="..."

Supported alias:

export GOOGLE_GENERATIVE_AI_API_KEY="..."

Fallback alias:

export GOOGLE_API_KEY="..."

5. Re-run the environment check

gemini-ocr doctor --json

6. Run the real command

gemini-ocr analyze-file /absolute/path/to/image.png --prompt "Describe this image precisely."
gemini-ocr analyze-file /absolute/path/to/image.png --prompt "Describe this image precisely." --reasoning-level low
gemini-ocr scan-pdf /absolute/path/to/document.pdf

Command overview

• gemini-ocr analyze-file <path> --prompt <text> [--output <path>] [--model <id>] [--reasoning-level minimal|low|medium|high]
• gemini-ocr setup --language en|de
• gemini-ocr doctor --json [--reasoning-level minimal|low|medium|high]
• gemini-ocr scan-image <path> [--format markdown|json] [--output <path>] [--model <id>] [--reasoning-level minimal|low|medium|high]
• gemini-ocr scan-pdf <path> [--pdf-mode auto|native|raster] [--dpi <n>] [--format markdown|json] [--reasoning-level minimal|low|medium|high]
• gemini-ocr-skill install --force
• gemini-ocr-skill uninstall
• gemini-ocr-skill doctor

Model policy

As of April 10, 2026, the current default policy is:

• preferred default: gemini-3.1-flash-lite-preview
• fallback: gemini-3-flash-preview
• override via --model or GEMINI_OCR_MODEL
• reasoning override via --reasoning-level or GEMINI_OCR_REASONING_LEVEL
• if unset, Gemini 3 uses its model-default thinking behavior

doctor prints the resolved policy so agents can see what will be used before running OCR.

Product modes

• analyze-file
  • accepts a local image or PDF
  • requires --prompt
  • returns free text
  • uses the generic Gemini file-analysis path
  • supports explicit Gemini thinking control via --reasoning-level
• scan-image
  • keeps the document/OCR-oriented image preset
  • defaults to Markdown output
• scan-pdf
  • keeps the document/OCR-oriented PDF preset
  • defaults to Markdown output
  • retains the PDF-native vs raster logic

Document-mode behavior

• Default output format is Markdown.
• --format json returns the full typed OCR object for agent workflows.
• PDF mode defaults to auto.
• Default timeout is 180000 ms.
• Native PDF requests get a higher adaptive timeout for large or many-page PDFs unless you set --timeout-ms explicitly.
• auto samples the PDF text layer and prefers native PDF upload for born-digital and mixed PDFs.
• When a local PDF text layer exists, the CLI also attaches it to the Gemini request so wording stays closer to the original while Gemini focuses on structure and tables.
• If pdftoppm is available and the sampled PDF looks scanned, auto can rasterize pages first.
• If a native auto PDF request aborts or times out, the CLI retries with raster page OCR when pdftoppm is available.
• --pdf-mode raster requires a working pdftoppm binary.
• analyze-file does not use the document JSON schema; it returns direct text from Gemini.

Agent guardrails

• Use the public CLI names gemini-ocr and gemini-ocr-skill.
• Do not bypass the product surface with node dist/index.js.
• Do not call hidden runtime paths such as ~/.codex/tools/gemini-ocr-cli/dist/index.js.
• Run doctor --json in every new shell before the first real OCR task.
• Use analyze-file for general promptable file understanding.
• Use scan-pdf or scan-image when you explicitly want the document/OCR preset.
• Use --reasoning-level minimal|low|medium|high when you need explicit latency vs. reasoning-depth control.

Privacy and remote processing

This tool sends file inputs to Gemini for remote processing.

Do not use it for documents that must not leave the local machine unless that remote-processing policy is acceptable for the environment.

The CLI does not persist API keys. Secrets should stay in shell environment variables such as GEMINI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_API_KEY.

Supported file inputs

The CLI currently supports:

• PDFs
• PNG
• JPEG / JPG
• WEBP
• GIF
• BMP
• TIFF / TIF
• HEIC
• HEIF

Skills ecosystem

Repository listing check:

npx -y skills add codecell-germany/gemini-pdf-img-ocr-agent-skill -l

Global install example:

npx -y skills add codecell-germany/gemini-pdf-img-ocr-agent-skill -g --skill gemini-ocr-cli -a '*' -y

Release verification

npm run build
npm test
npm whoami --registry=https://registry.npmjs.org/
npm pack

Local tarball smoke test:

TMP="$(mktemp -d)"
cd "$TMP"
npx -y -p /absolute/path/to/package.tgz gemini-ocr --help
npx -y -p /absolute/path/to/package.tgz gemini-ocr-skill install --codex-home "$TMP/codex" --force
"$TMP/codex/bin/gemini-ocr" --help

References

• Skill overview: skills/gemini-ocr-cli/references/overview.md
• Agent onboarding: skills/gemini-ocr-cli/references/agent-onboarding.md
• OCR first run: skills/gemini-ocr-cli/references/ocr-first-run.md
• Command cheat sheet: skills/gemini-ocr-cli/references/command-cheatsheet.md
• Architecture notes: knowledge/ARCHITECTURE.md
• Known limitations: knowledge/KNOWN_LIMITATIONS.md
• Release checklist: knowledge/RELEASE_CHECKLIST.md
• Skill publishing guide: knowledge/SKILL_PUBLISHING_GUIDE.md

Deutsch

Zweck

gemini-ocr-agent-skill gibt Agenten eine dedizierte Gemini-Dateianalyse-Oberfläche, statt alles durch das eingebaute Vision-Verhalten des Host-Modells zu erzwingen.

Das Paket ist für zwei zusammengehörige Arbeitsweisen gedacht:

• promptbare Bild- und PDF-Analyse mit Freitext-Ausgabe
• dokumentorientierte OCR, bei der Bilder und PDFs weiterhin möglichst originalgetreu in Markdown überführt werden können

Öffentliche Release-Oberflächen:

• GitHub-Repo: codecell-germany/gemini-pdf-img-ocr-agent-skill
• npm-Paket: @codecell-germany/gemini-ocr-agent-skill
• CLI-Binary: gemini-ocr
• Installer-Binary: gemini-ocr-skill
• Skill-Name: gemini-ocr-cli

Was das Paket enthält

• Ein globales CLI-Binary: gemini-ocr
• Ein Installer-Binary für den Skill: gemini-ocr-skill
• Einen Codex-Skill unter skills/gemini-ocr-cli/
• Onboarding- und Befehlsreferenzen für First-Run-Agenten-Workflows
• Einen generischen analyze-file-Pfad für promptbare Dateiverarbeitung
• Dokumentmodus-Kommandos für Markdown-orientierte OCR

Installation

1. CLI global installieren

npm install -g @codecell-germany/gemini-ocr-agent-skill

2. Öffentliche Binaries prüfen

gemini-ocr --help
gemini-ocr-skill --help

3. Skill-Payload installieren

gemini-ocr-skill install --force

Kanonischer First-Run-Ablauf

gemini-ocr --help
gemini-ocr doctor --json
gemini-ocr setup --language de
export GEMINI_API_KEY="..."
# oder:
export GOOGLE_GENERATIVE_AI_API_KEY="..."
# oder:
export GOOGLE_API_KEY="..."
# optional:
export GEMINI_OCR_REASONING_LEVEL="medium"
gemini-ocr doctor --json
gemini-ocr analyze-file /absoluter/pfad/zur/datei.png --prompt "Beschreibe das Bild präzise."
gemini-ocr scan-pdf /absoluter/pfad/zum/dokument.pdf

Agenten-Guardrails

• Nutze die öffentlichen CLI-Namen gemini-ocr und gemini-ocr-skill.
• Nutze keine repo-lokalen dist/-Entrypoints.
• Nutze keine versteckten Runtime-Pfade wie ~/.codex/tools/gemini-ocr-cli/dist/index.js.
• Führe in jeder neuen Shell zuerst gemini-ocr doctor --json aus.
• Nutze analyze-file für allgemeine promptbare Bild-/PDF-Analyse.
• Nutze scan-pdf oder scan-image, wenn du bewusst den Dokument-/OCR-Preset willst.
• analyze-file gibt standardmäßig Freitext zurück.
• Im Dokumentmodus ist die Standardausgabe Markdown.
• --format json gibt das vollständige strukturierte OCR-Objekt zurück.
• PDF-Standardmodus ist auto.
• Standard-Timeout ist 180000 ms.
• Native PDF-Requests bekommen ohne explizites --timeout-ms ein höheres adaptives Timeout für große oder mehrseitige PDFs.
• Bei born-digital PDFs hängt das CLI die lokal extrahierte Textschicht zusätzlich an den Gemini-Request, damit die Wortlaute stabiler bleiben und Gemini sich stärker auf Struktur und Tabellen konzentriert.
• Wenn ein nativer auto-PDF-Request abbricht oder ins Timeout läuft, versucht das CLI automatisch Raster-OCR, sofern pdftoppm verfügbar ist.
• analyze-file nutzt kein Dokument-JSON-Schema, sondern gibt direkten Text von Gemini zurück.
• Das Reasoning-Level kann über --reasoning-level minimal|low|medium|high oder GEMINI_OCR_REASONING_LEVEL gesetzt werden.
• API-Schlüssel werden nicht persistiert.
• Dokumente werden zur Verarbeitung an Gemini übertragen.

Modellpolitik

• Standardmodell: gemini-3.1-flash-lite-preview
• Fallback: gemini-3-flash-preview
• Override: --model oder GEMINI_OCR_MODEL
• Optionales Reasoning-Level: --reasoning-level oder GEMINI_OCR_REASONING_LEVEL
• Ohne Override nutzt Gemini 3 das modellseitige Standard-Thinking-Verhalten

Unterstützte Dateitypen

• PDF
• PNG
• JPEG / JPG
• WEBP
• GIF
• BMP
• TIFF / TIF
• HEIC
• HEIF

skills.sh

npx -y skills add codecell-germany/gemini-pdf-img-ocr-agent-skill -l
npx -y skills add codecell-germany/gemini-pdf-img-ocr-agent-skill -g --skill gemini-ocr-cli -a '*' -y

Release-Verifikation

npm run build
npm test
npm whoami --registry=https://registry.npmjs.org/
npm pack

Lokaler Tarball-Smoke-Test:

TMP="$(mktemp -d)"
cd "$TMP"
npx -y -p /absoluter/pfad/zum/paket.tgz gemini-ocr --help
npx -y -p /absoluter/pfad/zum/paket.tgz gemini-ocr-skill install --codex-home "$TMP/codex" --force
"$TMP/codex/bin/gemini-ocr" --help

Referenzen

• Übersicht: skills/gemini-ocr-cli/references/overview.md
• Agenten-Onboarding: skills/gemini-ocr-cli/references/agent-onboarding.md
• OCR-First-Run: skills/gemini-ocr-cli/references/ocr-first-run.md
• Befehlsübersicht: skills/gemini-ocr-cli/references/command-cheatsheet.md
• Architektur: knowledge/ARCHITECTURE.md
• Bekannte Einschränkungen: knowledge/KNOWN_LIMITATIONS.md
• Release-Checkliste: knowledge/RELEASE_CHECKLIST.md
• Skill-Publishing-Guide: knowledge/SKILL_PUBLISHING_GUIDE.md