Catalog
JuliusBrussee/caveman-compress

JuliusBrussee

caveman-compress

Compress a memory file such as CLAUDE.md or a todo list into caveman format to save input tokens, keeping a readable backup. Sends the file's text to the configured model provider. Trigger: /caveman-compress.

NewUpdated Nov 13, 2026

Caveman Compress

Purpose

Data leaves the machine. Compression sends the file's full text to the model provider that scripts/compress.py is configured for: the claude CLI, the Anthropic API, or an OpenAI-compatible endpoint. Files whose names look like secrets (.env, credentials, secrets, .netrc, …) are refused before they are read, and a file whose text holds a credential (a private key block, or a cloud, Git host or model API token) is refused before anything is sent. Don't compress a file the provider shouldn't see.

Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as <filename>.original.md, but NOT beside the source file — it lives in an out-of-tree data dir ($XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/, or %LOCALAPPDATA%\caveman-compress\backups\<parent-dir-name>\ on Windows) so skill auto-loaders don't re-ingest it as a live file.

Trigger

/caveman-compress <filepath> or when user asks to compress a memory file.

Requires an explicit filepath. If the user pastes raw text instead of naming a file, do NOT improvise an inline compression — ask them for the filepath to compress, or offer to save the pasted text to a file first. Writing your own reasoning/commentary about the request into the compressed output (e.g. "User passed text directly, not a filepath...") is the exact failure this guards against — never let that leak into a saved file.

Process

  1. The compression scripts live in scripts/ (adjacent to this SKILL.md). If the path is not immediately available, search for scripts/__main__.py next to this SKILL.md.

  2. From the directory containing this SKILL.md, run:

python3 -m scripts <absolute_filepath>

  1. The CLI will:
  • detect file type (no tokens)
  • call Claude to compress
  • validate output (no tokens)
  • if errors: cherry-pick fix with Claude (targeted fixes only, no recompression)
  • retry up to 2 times
  • if still failing after 2 retries: report error to user, leave original file untouched
  1. Return result to user

Compression Rules

Remove

  • Articles: a, an, the
  • Filler: just, really, basically, actually, simply, essentially, generally
  • Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
  • Hedging: "it might be worth", "you could consider", "it would be good to"
  • Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
  • Connective fluff: "however", "furthermore", "additionally", "in addition"

Preserve EXACTLY (never modify)

  • Code blocks (fenced ``` and indented)
  • Inline code (backtick content)
  • URLs and links (full URLs, markdown links)
  • File paths (/src/components/..., ./config.yaml)
  • Commands (npm install, git commit, docker build)
  • Technical terms (library names, API names, protocols, algorithms)
  • Proper nouns (project names, people, companies)
  • Dates, version numbers, numeric values
  • Environment variables ($HOME, NODE_ENV)

Preserve Structure

  • All markdown headings (keep exact heading text, compress body below)
  • Bullet point hierarchy (keep nesting level)
  • Numbered lists (keep numbering)
  • Tables (compress cell text, keep structure)
  • Frontmatter/YAML headers in markdown files

Compress

  • Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
  • Fragments OK: "Run tests before commit" not "You should always run tests before committing"
  • Drop "you should", "make sure to", "remember to" — just state the action
  • Merge redundant bullets that say the same thing differently
  • Keep one example where multiple examples show the same pattern

CRITICAL RULE: Anything inside ... must be copied EXACTLY. Do not:

  • remove comments
  • remove spacing
  • reorder lines
  • shorten commands
  • simplify anything

Inline code (...) must be preserved EXACTLY. Do not modify anything inside backticks.

If file contains code blocks:

  • Treat code blocks as read-only regions
  • Only compress text outside them
  • Do not merge sections around code

Pattern

Original:

You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.

Compressed:

Run tests before push to main. Catch bugs early, prevent broken prod deploys.

Original:

The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.

Compressed:

Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.

Boundaries

  • ONLY compress natural language files (.md, .txt, .typ, .typst, .tex, extensionless)
  • NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh
  • If file has mixed content (prose + code), compress ONLY the prose sections
  • If unsure whether something is code or prose, leave it unchanged
  • Original file is backed up as FILE.original.md before overwriting — in the out-of-tree backup data dir (see Purpose), not beside the source file
  • Never compress FILE.original.md (skip it)
Files10
10 files · 112.8 KB

Select a file to preview

Overall Score

80/100

Grade

B

Good

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

78

Quality

85

Clarity

82

Completeness

76

Summary

Caveman Compress is a Claude Code skill that compresses natural-language files (markdown, text) into abbreviated "caveman" format to reduce token count for repeated ingestion. It sends file content to a configured LLM provider (Claude, OpenAI, or local), validates the compressed output against structural invariants (headings, code blocks, URLs, paths), and stores uncompressed backups in an out-of-tree data directory. The skill includes sensitive-path detection and credential-pattern matching to refuse files it should not transmit.

Static Analysis Findings

4 findings

Patterns detected by deterministic static analysis before AI scoring. Hover over any finding code for detailed information and remediation guidance.

Credential Exposure
SEC-020Direct .env File Access9x in 3 files

Direct .env file access

SKILL.md.env2x
scripts/detect.py.env5x
scripts/compress.py.env2x
SEC-022SSH/Credentials File Access2x in 2 filesMax: B

SSH key or credentials file access

SKILL.md.netrc
scripts/compress.py.netrc
Command Injection
SEC-011Dynamic Shell Eval2x in 2 files

Shell eval/exec of dynamic content

README.mdexec`
scripts/compress.pyexec"
Environment Access
SEC-050Sensitive Environment Variable

Environment variable read for sensitive values

scripts/compress.py$OPENAI_API_KEY

Detected Capabilities

file readfile writefile deletesubprocess executionenvironment variable readnetwork request (HTTP/POST to LLM provider)file lockingcredential pattern matchingmarkdown parsing and validation

Trigger Keywords

Phrases that agents use to match this skill to user intent.

compress memory filereduce token countcompress claude.mdshorten project notescompress todo list

Risk Signals

WARNING

SEC-020: Direct .env file access (read content check)

SKILL.md | Purpose section, detect.py line ~200
WARNING

SEC-020: Multiple .env references in scripts/compress.py and scripts/detect.py

scripts/compress.py, scripts/detect.py
WARNING

SEC-022: SSH key file (.netrc) detection

SKILL.md, scripts/compress.py SENSITIVE_BASENAME_REGEX
INFO

SEC-011: Shell eval/exec pattern in README (docstring example)

README.md | codex exec in auth-behavior section
INFO

SEC-011: exec string in scripts/compress.py

scripts/compress.py | run_cli subprocess patterns
WARNING

SEC-050: OPENAI_API_KEY environment variable read

scripts/compress.py line ~900
WARNING

File write to user's target path (in-place overwrite)

scripts/compress.py _compress_file_locked()
INFO

Temporary file write to system temp directory

scripts/compress.py | opencode provider creates prompt attachments
INFO

Subprocess execution without shell=True (safe pattern)

scripts/compress.py run_cli() and run_provider_claude/opencode
INFO

Cross-session file locking with OS primitives (fcntl/msvcrt)

scripts/compress.py file_lock context manager

Referenced Domains

External domains referenced in skill content, detected by static analysis.

em-content.zobj.netgithub.comlearn.chatgpt.comlocalhostwww.apache.org

Use Cases

  • Compress project memory files (CLAUDE.md) to reduce per-session input tokens
  • Shrink todo lists and preference files while preserving structure and code blocks
  • Validate that compression preserves URLs, file paths, and heading structure
  • Detect and refuse files with credentials or sensitive naming patterns before transmission
  • Create restartable backups in platform-appropriate data directories (XDG_DATA_HOME or LOCALAPPDATA)

Quality Notes

  • Skill includes comprehensive SECURITY.md document explaining subprocess usage, file I/O scoping, and credential-handling patterns — demonstrates security-conscious design
  • Credential detection uses multiple pattern-matching strategies (sensitive filenames, path components, token shapes) with high precision to avoid false positives on placeholders
  • Validation subsystem (validate.py) is thorough: checks heading preservation, code-block integrity, URL/path preservation, bullet count, and inline-code pairing with detailed error messages
  • File locking mechanism (cross-session, OS-native fcntl/msvcrt) is well-designed for collision avoidance and handles filesystem edge cases (symlinks, unsupported filesystems)
  • Atomic write pattern (tempfile → fsync → os.replace) prevents data loss on write failure and preserves original file permissions
  • Backup path keying includes SHA256 hash of full parent path to prevent collisions when multiple projects share same filename
  • Detection module (detect.py) uses content sniffing for extensionless files with good heuristics (YAML, JSON, code pattern matching)
  • YAML frontmatter preservation (split/unsplit) is well-considered for memory files and skill definitions
  • Environment variable handling uses explicit ENV_* constants rather than magic strings; provider selection is clearly documented and scoped
  • Line-ending preservation (CRLF vs LF) shows attention to cross-platform correctness
  • Error messages are user-friendly with actionable guidance (e.g., 'Rename the file if this is a false positive')
  • Markdown fence parsing handles indentation (0-3 spaces per CommonMark) and nested fences correctly
  • Limitations are well-documented: 500KB file size cap, >30 fixture validation tests, max 2 retries with targeted fixes only
  • README includes before/after examples and benchmark results showing 33.2% token savings across 5 test files
Model: claude-haiku-4-5-20251001Analyzed: Nov 13, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Version History

  1. v3.4

    Content updated

    ✦ AIDocumentation and security guidance expanded; dynamic shell evaluation patterns added to compress script.

    2026-11-13

    LATEST
  2. v3.3

    Content updated

    ✦ AIAdds credential-content detection to refuse files holding private keys or API tokens, supplementing filename-based checks.

    2026-11-07

    View This Version
  3. v3.2

    Content updated

    ✦ AIExecutable scripts updated: compress.py and detect.py with size changes.

    2026-11-06

    View This Version
  4. v3.1

    Content updated

    ✦ AIUpdates executable scripts (cli.py, compress.py, validate.py) and documentation without changing skill instructions.

    2026-10-26

    View This Version
  5. v3.0

    Contract changed: description

    ✦ AIAdds explicit warning that file text is sent to model provider; refuses files with secret-like names; requires explicit filepath input to avoid inline compression and output contamination.

    triggering2026-10-17

    View This Version
  6. v2.4

    Content updated

    ✦ AIExpands scripts/compress.py (+9.9 KB) and enlarges documentation (README.md, SECURITY.md).

    2026-10-08

    View This Version
  7. v2.3

    Content updated

    ✦ AIScripts compress.py and validate.py updated (2.2 KB total growth); LICENSE expanded 9.7 KB.

    2026-10-03

    View This Version
  8. v2.2

    Content updated

    ✦ AIREADME.md documentation updated; no behavioral changes to skill logic or instructions.

    2026-09-21

    View This Version
  9. v2.1

    Content updated

    ✦ AIUpdates executable script scripts/cli.py

    2026-09-15

    View This Version
  10. v2.0

    Contract changed: description

    ✦ AIDescription narrowed to less specific usage guidance; compression scripts significantly expanded (compress.py doubled, validate.py increased 67%).

    triggering2026-09-09

    View This Version
  11. v1.0

    2026-08-17

    View This VersionInitial version

Use JuliusBrussee/caveman-compress in your dev environment

Command Palette

Search for a command to run...