Summary
This is a well-thought-out image finder that connects Google Custom Search API with LLM-powered selection to grab the right images for your docs. The scoring system is smart, penalizing stock photos and clipart while rewarding high-res images from trusted sources. What makes it actually useful is the Obsidian integration: point it at a note and it extracts visual terms, finds images, downloads them to your attachments folder, and inserts embeds below relevant headings automatically. You can also batch process from JSON configs or just do one-off searches. The LLM selection cuts through the usual image search noise by evaluating authenticity and relevance instead of just matching keywords. Needs API keys for Google Custom Search and OpenRouter.
Install to Claude Code
npx -y skills add glebis/claude-skills --skill google-image-search --agent claude-codeInstalls into .claude/skills of the current project.
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Files
SKILL.mdView on GitHub
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
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
.obsidianfolder - 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 |
Featured
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Categories
First SeenJun 3, 2026
