Caveman-Compress Skill Features: Safe Documentation Compression for Developers

The caveman-compress skill is a documentation compression tool that converts natural-language prose into concise "caveman-speak" while guaranteeing that code blocks, URLs, and technical artifacts remain untouched through a safe backup and validation pipeline.

The caveman-compress skill is part of the JuliusBrussee/caveman repository, providing a specialized pipeline for reducing the verbosity of markdown and text files. It orchestrates file detection, AI-powered compression via the Anthropic API, and multi-stage validation to ensure no technical content is lost during the reduction process.

How the Caveman-Compress Skill Processes Files

File Detection and Eligibility Screening

The detection logic in skills/caveman-compress/scripts/detect.py identifies eligible natural-language files by examining file extensions and content heuristics. Supported formats include .md, .txt, .typ, and .tex files. The skill explicitly refuses to process potential secret files such as .env, credentials.*, or SSH keys, and aborts on any file exceeding 500 KB.

Backup Creation Before Modification

Before any compression occurs, the skill creates a human-readable backup at <filename>.original.md stored in ~/.local/share/caveman-compress/backups on Unix or %LOCALAPPDATA%\caveman-compress\backups on Windows. This location prevents skill auto-loaders from re-ingesting the backup as a live file during subsequent operations.

Compression and Claude Integration

The core routine in skills/caveman-compress/scripts/compress.py extracts YAML front-matter, sends only the body text to Claude via the Anthropic SDK using the build_compress_prompt function, and receives a compressed markdown payload. The skill strictly preserves all content inside triple backticks, copying it verbatim without modification, re-ordering, or shortening.

Validation and Retry Logic

After writing the compressed output, skills/caveman-compress/scripts/validate.py checks for rule violations such as missing URLs or altered code blocks. If validation fails, the skill retries up to two additional times using the build_fix_prompt function to patch only reported errors while preserving the rest of the document. If all retries fail, the original file is restored from backup and the backup is deleted, ensuring zero data loss.

Compression Rules and Content Boundaries

The compression rules defined in skills/caveman-compress/SKILL.md govern exactly what the caveman-compress skill removes and preserves:

• Remove: Articles, filler words, pleasantries, hedging language, redundant phrasing, and connective fluff
• Preserve Exactly: Code blocks (fenced and indented), inline code, URLs, file paths, shell commands, technical terms, proper nouns, dates, version numbers, and environment variables
• Preserve Structure: Markdown headings, bullet hierarchies, numbered lists, tables, and front-matter
• Compress: Use short synonyms, eliminate "you should" constructions, merge redundant bullets, and retain only a single representative example when multiple exist

Command-Line and Programmatic Usage

You can invoke the caveman-compress skill through multiple interfaces depending on your workflow.

CLI Usage via the Caveman Toolset:

caveman-compress ./docs/project-notes.md

Direct Python Module Invocation:

python -m scripts.compress /absolute/path/to/README.md

Programmatic Python API:

from pathlib import Path
from scripts.compress import compress_file

if compress_file(Path("/home/user/notes/todo-list.md")):
    print("✅ Compression succeeded")
else:
    print("❌ Compression skipped or failed")

Summary

• The caveman-compress skill targets natural-language files (.md, .txt, .typ, .tex) while rejecting secrets and files over 500 KB
• Automatic backups are created in platform-specific directories before any modifications occur
• The compression pipeline in compress.py uses the Anthropic API via build_compress_prompt and preserves all code blocks verbatim
• The validation system in validate.py enforces content integrity with up to two retry attempts using build_fix_prompt
• Failed compressions trigger automatic restoration from backup, ensuring no data loss

Frequently Asked Questions

What file types does the caveman-compress skill support?

The skill processes natural-language documentation files including .md, .txt, .typ, and .tex extensions. The detection logic in skills/caveman-compress/scripts/detect.py evaluates both file extensions and content heuristics to determine eligibility. It explicitly excludes secret files like .env or credentials.* and any file larger than 500 KB.

How does caveman-compress handle errors during the compression process?

The skill implements a retry mechanism that attempts compression up to three times total. If validation fails after the initial attempt, the build_fix_prompt function generates targeted corrections for only the reported errors. Should all retries fail, the skill automatically restores the original file from its backup location and deletes the backup, leaving the filesystem in its original state.

What safety measures prevent data loss when using the caveman-compress skill?

Before any modification, the skill writes a human-readable backup to ~/.local/share/caveman-compress/backups on Unix or %LOCALAPPDATA%\caveman-compress\backups on Windows. This backup naming convention uses the .original.md suffix to prevent auto-loader ingestion. The restoration mechanism guarantees atomic rollback if validation fails or exceptions occur during processing.

Does caveman-compress modify code blocks or technical syntax?

No. According to the critical rule in skills/caveman-compress/SKILL.md, anything inside triple backticks must be copied verbatim without modifications, re-ordering, or shortening. The skill also preserves inline code, URLs, file paths, commands, technical terms, proper nouns, dates, and version numbers exactly as they appear in the source document.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}