Guide · Agent skill
How to use the Content-Hash File Cache agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Content-Hash File Cache skill gives your AI agent a tested design pattern for caching the results of slow file processing, such as PDF parsing, text extraction or image analysis. It is aimed at Python developers whose programs process the same files many times. After following this guide you will know how to install the skill, ask the agent for caching in plain language, and check what the code it writes does.
Content-Hash File Cacheaffaan-m/ECC · MIT Download the skill Quick start
- 1Download the ZIP. Get the skill ZIP from this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project.
- 3Or upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Describe your caching task. Ask the agent in plain language to add caching to a file processing step or a CLI tool.
- 5Review the generated code. Check that the key is a content hash, the processing function has no cache logic, and corrupt entries are handled.
- 6Test with a rerun. Run the tool twice on the same files and confirm the second run logs cache hits.
What is an agent skill?
An agent skill is a folder containing a SKILL.md file with instructions and examples that an AI agent can load when a task matches it. This skill is documented in a single file, SKILL.md, and contains no scripts. The agent reads the pattern and writes code that follows it in your project.
What the skill makes the agent do
When you ask for caching, the agent writes Python code that identifies each file by a SHA-256 hash of its contents rather than its path. A renamed or moved file still produces the same hash and so hits the cache. An edited file produces a new hash and is processed again automatically.
Each result is stored as a JSON file named after its hash, so no index file is needed. The processing function stays unchanged and a separate service layer handles the cache check, extraction and cache write. The pattern also treats a corrupted cache entry as a miss rather than a crash.
Install the skill
Option 1: download the ZIP from this page and unzip it into ~/.claude/skills/ for your user account, or into .claude/skills/ inside a project folder if you want it limited to that project.
Option 2: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Files included: SKILL.md only
- Requirements: Python. The examples use hashlib, dataclasses, pathlib and json, which are all in the Python standard library.
- No API keys or accounts are needed.
How to trigger the skill with natural requests
You do not need a special command. Describe the task in plain words that match the skill's use cases. The skill is meant for requests such as adding caching to a file pipeline, or adding a --cache/--no-cache option to a command-line tool.
Mention the file types and the slow step so the agent knows what to wrap.
- "Add caching to my PDF text extraction script so files I have already processed are not parsed again."
- "Add a --cache/--no-cache flag to this CLI tool without changing the extraction functions."
- "My batch job processes the same images every run. Cache the image analysis results by file content."
What to check in the code the agent writes
Review the generated code against the pattern. The cache key should come from compute_file_hash, not from the file path. The extraction function should contain no cache logic. Cache misses and hits should be logged with truncated hashes.
Also confirm that the cache directory is a location you are happy to write to. The example defaults to a .cache folder in the current directory.
- Cache key is a SHA-256 hash of file bytes, read in 64KB chunks
- Each entry is saved as {hash}.json
- Corrupt entries return None and are reprocessed
When not to use it
Do not use this pattern for data that must always be fresh, such as real-time feeds, because cached results can be stale by design. It is also a poor fit when results depend on settings beyond the file itself. Different extraction configurations would share the same cache key, so the skill's own guidance says not to use it in that case.
The skill also advises against it when cache entries would be extremely large, and suggests streaming instead.
What people use it for
- Caching PDF parsing in a document ingestion pipeline that reruns over the same folder
- Adding --cache/--no-cache to an existing text extraction command-line tool
- Storing image analysis results so batch jobs skip unchanged images
- Reusing extracted text when files are renamed or moved between folders
Frequently asked questions
How do I install the content-hash-cache-pattern skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/, or into .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
What do I need to use this skill?
You need Python. The examples use only hashlib, dataclasses, pathlib and json. The skill needs no API keys or accounts, runs no scripts and uses no network access.
Is the content-hash-cache-pattern skill free?
The skill is published under the MIT licence. Check the licence on the source repository for the full terms.
Why hash file contents instead of using file names?
A hash of the contents stays the same when a file is renamed or moved, so the cache still hits. If the content changes, the hash changes and the file is processed again automatically.
What happens if a cache file is corrupted?
The pattern treats a corrupted entry as a cache miss. The code returns None, the file is processed again, and the program does not crash.
When should I not use content-hash caching?
Avoid it for data that must always be fresh, such as real-time feeds, and for results that depend on settings beyond the file, such as different extraction configurations. Those would collide under the same cache key.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a Python developer building file processing pipelines that rerun over the same inputs, or if you want to add a --cache/--no-cache option to an existing command-line tool without rewriting its functions. Pick something else if your data must always be fresh or if your results depend on settings beyond the file contents.
Download the skill