--- title: compress vs caveman-compress dedup type: concept tags: [skills, dedup, caveman, repo-hygiene] updated: 2026-05-05 --- # compress vs caveman-compress dedup > Two skills shipped the same payload under different names. Kept `caveman-compress` (richer, on-brand), deleted `compress`. Recorded here so future readers don't reinvent the analysis. ## What we found Side-by-side audit of `skills/compress/` and `skills/caveman-compress/`: | Layer | `compress` | `caveman-compress` | |---|---|---| | `scripts/__init__.py` | identical (SHA256) | same | | `scripts/__main__.py` | identical | same | | `scripts/benchmark.py` | identical | same | | `scripts/cli.py` | identical | same | | `scripts/compress.py` | identical | same | | `scripts/detect.py` | identical | same | | `scripts/validate.py` | identical | same | | `SKILL.md` description | byte-identical text | byte-identical text | | `SKILL.md` Process step 2 | `cd && python3 -m scripts ...` (generic) | `cd caveman-compress && python3 -m scripts ...` (brittle, assumes cwd is parent) | | `SKILL.md` `name:` | `compress` | `caveman-compress` | | `README.md` | absent | present (benchmarks table, branding, "Part of Caveman" toolkit linkage) | | `SECURITY.md` | absent | present (Snyk false-positive writeup: subprocess + file I/O patterns explained) | | Frontmatter `version:` | absent | absent (added `1.0.0` as part of this dedup) | Description text in both skills' frontmatter: ``` Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format to save input tokens. ... Trigger: /caveman:compress or "compress memory file" ``` — literally the same paragraph. The harness loads both skill listings, both register independently, descriptions identical ⇒ activation tie-break is arbitrary, and the listing budget pays twice. ## What we kept and why **Canonical = `caveman-compress`.** Reasons in order of weight: 1. **Richer artefacts** — README.md and SECURITY.md exist only here. The README is not boilerplate: benchmarks table on real files (claude-md-preferences.md, project-notes.md, mixed-with-code.md), 46% average savings claim, before/after example. The SECURITY.md is what static-analysis (Snyk) hooks into, so deleting it would re-open the same false-positive ticket the upstream author already closed. 2. **On-brand naming** — the skill is part of the [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) toolkit. The `caveman-*` prefix lines up with the rest of the cluster: `caveman` (speak compressed), `caveman-commit` (commit-message variant), `caveman-review` (PR-review variant), `caveman-help` (help card), `caveman-compress` (compress files). `compress` was the lone exception that broke the prefix invariant. 3. **History reads cleanly** — the per-task `[skill-readmes]` plan groups the caveman cluster as a single batch for README work. Keeping the prefix means that batch covers all of them; mixing in a stray `compress` would force a "wait, do we README this one separately?" decision later. ## What we ported across before deleting The only thing `compress` did better than `caveman-compress` was Process step 2. Original wording: ``` cd caveman-compress && python3 -m scripts ``` This assumes cwd is the parent of `caveman-compress/`. When the agent invokes the skill from `~/.claude/skills/caveman-compress/`, that assumption is false (cwd is the skills dir, parent is `~/.claude/`). The `compress` SKILL.md had the robust form: ``` cd && python3 -m scripts ``` — ported into `caveman-compress/SKILL.md` as part of this dedup. Net: the canonical skill now has the better instructions plus the README + SECURITY. Also added `version: 1.0.0` to frontmatter — first versioned release. Aligns with the rest of the infra-skill cluster ([skill-versioning](skill-versioning.md)). ## What we rejected **Alias-stub** — keep `skills/compress/SKILL.md` as a tiny pointer file with description "alias for caveman-compress, see that skill". Rejected: the harness has no alias mechanism. Every SKILL.md file fully registers as a skill, with its description text consuming the listing budget. An alias-stub still occupies a listing slot and a description allowance — there's no "see that skill" indirection at the harness level. Pure waste of a listing entry. **Keep both, document them as siblings** — let the user pick which slash-command name they prefer (`/compress` vs `/caveman-compress`). Rejected: descriptions are identical; the harness has no signal to disambiguate; activation tie-break is arbitrary. Forces every future `/caveman:compress` call to gamble on which copy the harness picks. **Delete `caveman-compress`, keep `compress` as the simpler name** — rejected because we'd lose the README, SECURITY.md, and the caveman-toolkit branding link. `compress` was the stripped-down fork; reverting to it would be a net regression in artefact quality. ## Install-path impact `scripts/install.sh` has no prune step. Removing `skills/compress/` does **not** remove `~/.claude/skills/compress/` on the user's machine — the install script copies, never deletes. Manual `rm -rf ~/.claude/skills/compress/` is required during this dedup. Same applies to `dist/compress.skill`: deleted explicitly, since the next `build.sh` run iterates over `skills//` and won't recreate an artefact for a source folder that no longer exists. > **Future work:** the [`install-ps1`](../../.tasks/STATUS.md) ⚪ task should at minimum match `install.sh`'s behavior, but is also the right time to add a `--prune` flag that removes `~/.claude/skills//` for every name not in `skills//`. Would have made this dedup automatic instead of three-step. ## Slash-command impact Before: `/compress`, `/caveman-compress`, and `/caveman:compress` (toolkit-canonical) were all live. After: `/compress` is gone. `/caveman-compress` and `/caveman:compress` still work. User confirmed `/compress` was effectively never used; no migration needed. ## See also - [skill-versioning](skill-versioning.md) — why infra skills carry `version:` in frontmatter and the project-discipline Rule 3 bumps tie back here - [repo-layout](repo-layout.md) — flat `skills/` layout means duplicates show up as flat sibling folders, easy to spot in a directory listing - [skill-vs-plugin](skill-vs-plugin.md) — caveman-compress is a bare SKILL.md (no slash command, no hooks, no MCP), the right granularity for this workload