Agent skill · software engineering · affaan-m
content-hash-cache-pattern
Cache expensive file processing results using SHA-256 content hashes — path-independent, auto-invalidating, with service layer separation. Use when repeated file processing is slow and results should be cached and invalidated by content rather than path.
Why this skill is useful
Provides a detailed caching pattern with specific implementation examples that the AI wouldn't reliably generate on its own.
What it needs
About 3k tokens when loaded. Last updated 2026-08-06. 238,342 stars on the source repository.
What this skill does
Content-Hash File Cache Pattern Cache expensive file processing results (PDF parsing, text extraction, image analysis) using SHA-256 content hashes as cache keys. Unlike path-based caching, this approach survives file moves/renames and auto-invalidates when content changes. When to Activate Building file processing pipelines (PDF, images, text extraction) Processing cost is high and same files are processed repeatedly Need a --cache/--no-cache CLI option Want to add caching to existing pure functions without modifying them Core Pattern 1. Content-Hash Based Cache Key Use file content (not path) as the cache key: Why content hash? File rename/move = cache hit. Content change = automatic invalidation. No index file needed. 2. Frozen Dataclass for Cache Entry 3. File-Based Cache Storage Each cache entry is stored as {hash}.json — O(1) lookup by hash, no index file required. 4. Service Layer Wrapper (SRP) Keep the processing function pure. Add caching as a separate service layer. Key Design Decisions Decision Rationale ---------- ----------- SHA-256 content hash Path-independent, auto-invalidates on content change {hash}.json file naming O(1) lookup, no index file needed Service layer wrapper SRP: extraction stays pure, cache is a separate concern Manual JSON serialization Full control over frozen dataclass serialization Corruption returns None Graceful degradation, re-processes on next run cachedir.mkdir(parents=True) Lazy directory creation on first write Best Practices Hash content, not paths — paths change, content identity doesn't Chunk large files when hashing — avoid loading entire files into memory Keep processing functions pure — they should know nothing about caching Log cache hit/miss with truncated hashes for debugging Handle corruption gracefully — treat invalid cache entries as misses, never crash Anti-Patterns to Avoid When to Use File processing pipelines (PDF parsing, OCR, text extraction, image analysis) CLI tools that benefit from --cache/--no-cache o …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills affaan-m/content-hash-cache-pattern--96f90e