# Caveman-Compress Skill Features: Safe Documentation Compression for Developers

> Discover Caveman-Compress skill features for safe documentation compression. This tool converts prose to caveman-speak, preserving code blocks and URLs for developers.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: getting-started
- Published: 2026-07-03

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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**:

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

```

**Direct Python Module Invocation**:

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

```

**Programmatic Python API**:

```python
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`](https://github.com/JuliusBrussee/caveman/blob/main/compress.py) uses the Anthropic API via `build_compress_prompt` and preserves all code blocks verbatim
- The validation system in [`validate.py`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.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`](https://github.com/JuliusBrussee/caveman/blob/main/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.