Image Read Cache — AI skill for Claude Code

image-read-cache

An [Agent Skill](https://agentskills.io) that caches LLM image descriptions as XMP metadata inside image files, reducing token usage by ~92% on repeated reads.

Installation

npx skills add ParthJadhav/image-read-cache

Works with [30+ compatible agents](https://agentskills.io) including Claude Code, Cursor, OpenCode, Gemini CLI, Goose, Roo Code, GitHub Copilot, and more.

The Problem

Every time an AI agent reads an image, it sends the full base64-encoded image to the LLM. In a multi-turn conversation where the same image is referenced repeatedly, this compounds fast:

• A single image costs 1,000-6,000+ tokens per read
• Over 20 turns referencing the same image, that's 20,000-120,000 tokens wasted on identical content

The Solution

`image-read-cache` intercepts image reads and stores the LLM's description directly inside the image file as XMP metadata. On subsequent reads, the cached text description is returned instead of the full image.

Agent reads image.png
  -> Check XMP metadata for cached description
  -> If found: return text (~200 tokens) instead of image (~4,000 tokens)
  -> If not found: read image normally, cache the result in metadata

The cache is embedded in the image file itself -- no external database, no sidecar files (for JPEG/PNG/WebP), and it follows the image wherever it goes.

For GIF and BMP, the cache is stored in an adjacent `.ai-cache` sidecar because those formats do not support the same embedded XMP flow used for JPEG/PNG/WebP.

How It Works

image-read-cache/
  SKILL.md              # Agent instructions (AgentSkills.io format)
  scripts/
    cache_common.py     # Shared hashing/XMP/atomic-write helpers
    check_cache.py      # Read cached description from XMP metadata
    write_cache.py      # Write description into image XMP metadata

Cache Flow

1. Before reading an image, the agent runs check_cache.py
2. If CACHED: -- use the text descrip