google-image-search

Q: How do I install google-image-search?

Run npx skills add https://github.com/glebis/claude-skills --skill google-image-search in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/google-image-search/ (personal) or .claude/skills/google-image-search/ (project).

by glebisMedia & Creative

Search and download images via Google Custom Search API with LLM-powered selection. This skill should be used when finding images for articles, presentations, research documents, or enriching Obsidian notes with relevant visuals. Supports simple queries, batch processing from JSON config, automatic config generation from terms, and full note enrichment with automatic image insertion below headings.

Installs: 643
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/glebis/claude-skills --skill google-image-search

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads google-image-search automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Google Image Search Skill

Search for images using Google Custom Search API with intelligent scoring and LLM-based selection.

When to Use

Finding images to illustrate technical articles or research
Adding visuals to presentations
Enriching Obsidian notes with relevant images
Batch image search for multiple topics
Generating image search configs from plain text lists

Requirements

Google Custom Search API key and Search Engine ID
OpenRouter API key (for LLM selection)
llm CLI installed at /opt/homebrew/bin/llm

Store credentials in .env:

Google-Custom-Search-JSON-API-KEY=your_key
Google-Custom-Search-CX=your_cx
OPENROUTER-API-KEY=your_openrouter_key

(The OPENROUTER_API_KEY=... spelling works too — see the plugin note below.)

OpenRouter / llm-openrouter caveat

The llm-openrouter plugin only registers its models when it can read a key named OPENROUTER_KEY (env var or llm keys set openrouter). With only OPENROUTER_API_KEY set, llm models list shows zero OpenRouter models and every openrouter/... name fails with Unknown model — the script then silently falls back to keyword scoring. llm_select.py sets both names for the subprocess, so this is handled; if selection ever regresses, check OPENROUTER_KEY first:

llm models list | grep -c openrouter   # 458+ means the plugin registered its models

Modes of Operation

1. Simple Query

Search for a single term:

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --query "neural interface wearable device" \
  --output-dir ./images \
  --num-results 5

2. Batch Processing

Process multiple queries from JSON config:

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --config image_queries.json \
  --output-dir ./images \
  --llm-select

3. Generate Config from Terms

Create JSON config from a list of terms using LLM:

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --generate-config \
  --terms "AlterEgo wearable" "sEMG electrodes" "BCI headset" \
  --output my_queries.json

4. Enrich Obsidian Note

Extract visual terms from note, find images, and insert below headings:

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --enrich-note ~/Brains/brain/Research/neural-interfaces.md

This mode:

Detects Obsidian vault and attachments folder
Uses LLM to extract visual-worthy terms from note
Searches for images for each term
Downloads best images to attachments folder
Inserts image embeds below relevant headings
Creates backup before modifying note

Key Options

Option	Description
`--query TEXT`	Simple single query
`--config FILE`	JSON config for batch
`--generate-config`	Generate config from `--terms`
`--enrich-note FILE`	Enrich Obsidian note
`--output-dir DIR`	Where to save images
`--urls-only`	Return URLs only, no download
`--llm-select`	Use LLM to pick best image (default: on)
`--no-llm-select`	Disable LLM selection
`--num-results N`	Results per query (default: 5)
`--dry-run`	Show what would be done

JSON Config Format

Each entry supports:

{
  "id": "unique-id",
  "heading": "Display Heading",
  "description": "Context for what image to find",
  "query": "Google search query",
  "numResults": 5,
  "selectionCriteria": "What makes a good image",
  "requiredTerms": ["must", "have"],
  "optionalTerms": ["bonus", "terms"],
  "excludeTerms": ["stock", "clipart"],
  "preferredHosts": ["official-site.com"],
  "selectionCount": 2
}

See references/api_config_reference.md for full documentation.

Scoring System

Images are scored based on:

Required terms: -80 if missing, +30 if all present
Optional terms: +5 per match
Exclude terms: -50 per match
Preferred hosts: +25 if trusted, -5 if unknown
MIME type: +5 for PNG/JPEG, -10 for GIF
Resolution: +10 for high res, -10 for low res
File size: -5 if very small

LLM Selection

After scoring, LLM picks the best image from top candidates based on:

Title and URL metadata
Scoring reasons
Selection criteria

The LLM evaluates authenticity, clarity, and relevance for technical audiences.

Obsidian Integration

When in an Obsidian vault:

Auto-detects vault root via .obsidian folder
Uses configured attachments folder (default: Attachments)
Generates Obsidian-style embeds: ![[image.png|alt text]]
Creates backup before modifying notes

Script Files

File	Purpose
`google_image_search.py`	Main entry point
`api.py`	Google Custom Search API
`config.py`	Credentials and config handling
`download.py`	Image download with magic bytes
`evaluate.py`	Keyword-based scoring
`llm_select.py`	LLM selection and term extraction
`obsidian.py`	Vault detection and enrichment
`output.py`	Markdown output generation

FAQ

What does the google-image-search skill do?

How do I install google-image-search?

Run npx skills add https://github.com/glebis/claude-skills --skill google-image-search in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/google-image-search/ (personal) or .claude/skills/google-image-search/ (project).

Which AI agents can use google-image-search?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is google-image-search safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains google-image-search?

It is published by glebis in glebis/claude-skills. It has 643 recorded installs.

More from glebis/claude-skills

View all →

pdf-generation

glebis/claude-skills

Professional PDF generation from markdown using Pandoc with Eisvogel template and EB Garamond fonts. Use when converting markdown to PDF, creating white papers, research documents, marketing materials, or technical documentation. Supports both English and Russian documents with professional typography and color-coded themes. Mobile-optimized layout (6x9) by default for Telegram bot context, desktop/print layout (A4) for other contexts.

Docs & Writing482 installs