caveman-compress

An agent skill by JuliusBrussee, from JuliusBrussee/caveman. Tags: compression, documents, local-workflow, optimization.

What it does

Compress a memory file such as CLAUDE.md or a todo list into caveman format to save input tokens, keeping a readable backup. Trigger: /caveman-compress.

Install

With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add JuliusBrussee/caveman --skill caveman-compress

Or copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):

git clone --depth 1 https://github.com/JuliusBrussee/caveman
cp -r caveman/plugins/caveman/skills/caveman-compress ~/.claude/skills/caveman-compress

Safety box score

Grade C, moderate risk: 39 of 100 risk points, rated 2026-10-16. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.

This skill compresses a user-chosen text file by sending its contents to a configured LLM provider, then overwrites the original after validation and keeps a backup in the user’s data directory. The main risks are outbound data exposure, automatic in-place file mutation, and reliance on filename heuristics plus external CLI/API calls.

Category levels, from 0 (none) to 3 (high)
Category	Level	Why
Code & shell execution	2 (moderate)	It shells out to provider binaries via `subprocess.run(command, **run_kwargs)` and resolves them with `shutil.which(binary_name) or binary_name`, so running the skill can execute external CLIs on the local machine.
Network access	3 (high)	The skill explicitly sends the file text to a model provider (`messages=[{"role": "user", "content": prompt}]` or an HTTP POST to `/chat/completions`), so file contents leave the machine to a remote endpoint or CLI-backed service.
Filesystem reach	2 (moderate)	It overwrites the target file in place (`os.replace(tmp_path, path)`) and writes backups/locks under `$XDG_DATA_HOME` or `%LOCALAPPDATA%` via `_state_base_dir("backups")` and `backup_dir_for(filepath)`.
Secrets & credentials	2 (moderate)	It handles API credentials (`ANTHROPIC_API_KEY`, `CAVEMAN_COMPRESS_API_KEY`) and only blocks secret-like files by name/path heuristics, so a secret-bearing note with an innocuous filename would still be uploaded.
Privilege & persistence	0 (none)	There is no sudo, service registration, global install, or shell/OS setting mutation in the shipped files.
Instruction hijack surface	0 (none)	The files do not fetch remote instructions or contain hidden agent-steering text; they only build local prompts from the chosen file content.
Irreversible actions	1 (low)	After validation it automatically replaces the original file and may delete staging/backup files on failure, but it does not push, publish, pay, or act beyond the chosen file.
Transparency	0 (none)	All shipped content is readable source/markdown; there are no binaries, downloaded installers, base64 blobs, or unpinned remote code loads.

Before installing

Run it first on a throwaway `.md` copy with non-sensitive text.
Check `CAVEMAN_COMPRESS_PROVIDER`, `CAVEMAN_COMPRESS_ENDPOINT`, and any API-key env vars before use.
Read `scripts/compress.py` for the backup path logic so you’re okay with writes under your home data directory.
Do not use it on files that may contain secrets unless you’re comfortable sending them to the configured provider.

Rated 2026-10-16 by an automated review of 8 files from the skill's repository.

Source

Repository: JuliusBrussee/caveman (all skills from this repository)
Path: plugins/caveman/skills/caveman-compress/SKILL.md
Branch: main
Collection: caveman
Updated: 2026-10-05

bd-to-br-migration — Migrate docs from bd (beads) to br (beads_rust). Use when updating AGENTS.md, converting bd commands, "bd sync" → "br sync --flush-only", or beads migration.
defuddle — Extract clean Markdown from HTML pages with Defuddle CLI.
filesystem-context — This skill should be used when agent work needs file-backed context: durable scratchpads, tool-output offloading, just-in-time discovery.
fixing-claude-export-conversations — Fixes broken line wrapping in Claude Code exported conversation files (.txt), reconstructing tables, paragraphs, paths.
json-canvas — Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. Use when working with .canvas files, creating visual canvases.
obsidian-bases — Create and edit Obsidian Bases (.base files) with views, filters, formulas, and summaries. Use when working with .base files.