Guide · Agent skill
How to use the Caveman Compress agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Caveman Compress is an agent skill that rewrites a memory or notes file, such as CLAUDE.md or a todo list, into a terse style that uses fewer input tokens. This guide explains what the skill does, how to install it, how to trigger it with a request, and what to check before running it. By the end you will be able to compress a file safely and know where the original goes.
Caveman CompressJuliusBrussee/caveman · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the caveman-compress ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 3Configure a model provider. Make sure Python 3 is installed and that you have the claude CLI, an Anthropic API key, or an OpenAI-compatible endpoint with its key.
- 4Pick a file that is safe to send. Choose a natural language file such as CLAUDE.md that contains no secrets, credentials or private data.
- 5Ask for compression. Run /caveman-compress with the file path, or ask in plain words and include the path.
- 6Review the result. Read the compressed file and check the backup location reported by the tool. Confirm that code, commands and URLs are unchanged.
What is an agent skill and what does caveman-compress do?
An agent skill is a folder with a SKILL.md file and any supporting scripts. When the skill is installed, the agent can load it and follow its instructions when a matching request comes up.
caveman-compress targets natural language files: CLAUDE.md, todo lists and preference notes. It runs a bundled Python script that asks a model to rewrite the prose with articles, filler and hedging removed. Code blocks, inline code, URLs, file paths, commands, version numbers and environment variables are meant to be kept exactly as written.
The compressed version overwrites the original file. The original is saved as a backup in an out-of-tree data folder, not next to the source file, so skill loaders do not read it as a live file.
Install the caveman-compress skill
Download the ZIP for the skill from this page and unzip it. Then choose one of these options.
For a single user across all projects, unzip it into ~/.claude/skills/. For one project only, unzip it into that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Set up a model provider and Python 3
The skill needs Python 3 and a configured model provider, because the rewriting is done by a model. The source lists three options: the claude CLI, an Anthropic API key, or an OpenAI-compatible endpoint with its key.
The tiktoken package is optional. It gives more accurate token counts when benchmarking. Without it, the scripts fall back to word count.
- Python 3
- One provider: the claude CLI, an Anthropic API key, or an OpenAI-compatible endpoint plus its key
- Optional: tiktoken for accurate token counts
Trigger the skill with a natural request
You can use the slash command or ask in plain language. The skill needs an explicit file path. If you paste raw text instead, the agent should ask for a file path or offer to save the text to a file first.
The skill runs python3 -m scripts followed by the absolute file path. The CLI detects the file type, asks the model to compress, validates the output, and if validation finds errors, asks for targeted fixes. It retries up to 2 times. If it still fails, it reports the error and leaves the original file untouched.
- Slash command: /caveman-compress <filepath>
- Plain request: "Compress my CLAUDE.md at /path/to/CLAUDE.md"
- Paste text instead of a path: the agent asks for a file first
/caveman-compress <filepath>Check what the skill will send and change
Compression sends the full text of the file to your configured model provider over the network. Do not use it on files you would not share with that provider. Files whose names look like secrets, such as .env, credentials, secrets or .netrc, are refused before they are read.
The output is deliberately terse, and the original file is overwritten. Keep your own copy or rely on the backup in the data folder before you run it on important notes.
- Content is sent to the model provider
- Secret-like filenames are refused
- Compressed output replaces the original; the backup is stored out of tree
- Skip .py, .js, .json, .yaml, .env and similar files: the skill only handles natural language files
What people use it for
- Shrinking a long CLAUDE.md so less text loads into each session
- Compressing a todo list or a preferences file that is mostly prose
- Reducing a memory notes file while keeping its commands and file paths intact
Frequently asked questions
Is caveman-compress free to use?
The skill is published under the Apache-2.0 licence. The rewriting itself is done by your configured model provider, so you need access to one of the supported providers, and usage may be billed by that provider.
What do I need to install caveman-compress?
You need Python 3 and a configured model provider: the claude CLI, an Anthropic API key, or an OpenAI-compatible endpoint with its key. Installing the skill means unzipping it into ~/.claude/skills/ or a project's .claude/skills/ folder, or uploading it in Settings → Capabilities → Skills.
Does caveman-compress send my files to the internet?
Yes. The full text of the file is sent to the model provider the scripts are configured for. Do not compress files containing secrets, credentials or private data that the provider should not see.
Where is the original file saved?
The original is saved as FILE.original.md in an out-of-tree data folder: $XDG_DATA_HOME/caveman-compress/backups/ on Linux and macOS, or %LOCALAPPDATA%\caveman-compress\backups\ on Windows. It is not stored beside the source file.
What if the compressed output breaks my file?
The CLI validates the output. If it finds errors, it asks for targeted fixes and retries up to 2 times. If it still fails, it reports the error and leaves the original file untouched.
Are there alternatives to caveman-compress?
The source does not compare this skill with other tools, so this guide cannot rank them. If you need a readable, polished document or do not want content sent to a model provider, this skill is the wrong choice and you should edit the file by hand.
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 caveman-compress if you maintain long CLAUDE.md or memory files and accept that their text goes to your configured model provider. Pick something else if the file holds secrets or private data, or if you need output that reads like a polished document, since the result is deliberately terse and overwrites the original.
Download the skill