Semantic Compressor

A fail-closed Claude Code skill for reducing skill and agent Markdown without silently changing behavior.

English | 繁體中文

[!IMPORTANT]
v2.0.0 is a major workflow and safety upgrade. Existing users should review CHANGELOG.md before updating.

What v2 changes

Semantic Compressor now separates drafting from mutation:

• scan, compress, verify, benchmark, and restore preview are read-only for source files.
• Only explicit apply and restore ... --apply can replace a source file.
• A dependency-free Python control script validates paths, frontmatter, preservation inventories, ratios, hashes, backups, manifests, and rollback state.
• A fresh read-only reviewer judges conceptual equivalence after deterministic checks pass.
• Semantic review is reported as model judgment with evidence, never as an absolute guarantee.

The skill is user-invocable only. Its frontmatter sets disable-model-invocation: true, so Claude does not trigger it automatically.
Use scan, compress, verify, benchmark, and restore preview as source-unmodified dry runs.

Safety model

Requirements

• Claude Code 2.1.196 or newer
• Python 3.10 or newer
• Git for installation from this repository
• An authenticated Claude Code session using any supported subscription, API, or cloud provider configuration

A direct Anthropic API key is not required if Claude Code is already authenticated through another supported provider.
If the first session reports Not logged in, run /login inside Claude Code or complete your provider-specific authentication before invoking the skill.

Check your local versions in a shell:

claude --version
python3 --version

The shell examples below use macOS, Linux, or WSL syntax.

Installation

The commands below install v2.0.0 from the public default branch.

Personal installation

Use a personal installation to make the skill available in every local project:

git clone https://github.com/claude-world/skills-optimizer.git skills-optimizer
test -f skills-optimizer/.claude/skills/semantic-compressor/scripts/semantic_compressor.py
mkdir -p ~/.claude/skills
cp -R skills-optimizer/.claude/skills/semantic-compressor ~/.claude/skills/

Installed path:

~/.claude/skills/semantic-compressor/SKILL.md

Project installation

Use a project installation when the repository should pin and share the skill with collaborators:

test -f /path/to/skills-optimizer/.claude/skills/semantic-compressor/scripts/semantic_compressor.py
mkdir -p .claude/skills
cp -R /path/to/skills-optimizer/.claude/skills/semantic-compressor .claude/skills/

Review project skills before accepting Claude Code workspace trust, then commit the installed directory if the team should share it.

Verify the installation and launch Claude Code

For a personal installation, verify the bundled control script in a shell:

python3 ~/.claude/skills/semantic-compressor/scripts/semantic_compressor.py --version

For a project installation, use:

python3 .claude/skills/semantic-compressor/scripts/semantic_compressor.py --version

The expected v2 script version is 2.0.0. Start a fresh Claude Code session after installation or update:

claude

Then invoke the skill inside Claude Code, not in your shell:

/semantic-compressor scan

Update

Update the checkout first:

git -C skills-optimizer pull --ff-only

Keep the previous personal installation recoverable, then copy the new one:

mkdir -p "$HOME/.claude/disabled-skills"
SEMANTIC_COMPRESSOR_PREVIOUS="$(mktemp -d "$HOME/.claude/disabled-skills/semantic-compressor-XXXXXXXX")"
mv "$HOME/.claude/skills/semantic-compressor" "$SEMANTIC_COMPRESSOR_PREVIOUS/"
cp -R skills-optimizer/.claude/skills/semantic-compressor "$HOME/.claude/skills/"

For a project installation:

mkdir -p .claude/disabled-skills
SEMANTIC_COMPRESSOR_PREVIOUS="$(mktemp -d ".claude/disabled-skills/semantic-compressor-XXXXXXXX")"
mv .claude/skills/semantic-compressor "$SEMANTIC_COMPRESSOR_PREVIOUS/"
cp -R /path/to/skills-optimizer/.claude/skills/semantic-compressor .claude/skills/

Re-run the version check and start a fresh Claude Code session.

Uninstall

Move the skill outside the discovery directory so the uninstall remains recoverable:

mkdir -p "$HOME/.claude/disabled-skills"
SEMANTIC_COMPRESSOR_DISABLED="$(mktemp -d "$HOME/.claude/disabled-skills/semantic-compressor-XXXXXXXX")"
mv "$HOME/.claude/skills/semantic-compressor" "$SEMANTIC_COMPRESSOR_DISABLED/"

For a project installation:

mkdir -p .claude/disabled-skills
SEMANTIC_COMPRESSOR_DISABLED="$(mktemp -d ".claude/disabled-skills/semantic-compressor-XXXXXXXX")"
mv .claude/skills/semantic-compressor "$SEMANTIC_COMPRESSOR_DISABLED/"

Start a fresh Claude Code session after uninstalling. Delete the moved directory later only if you no longer need it.

Usage

Run all commands in an interactive Claude Code session:

Paths may be absolute or project-relative, but they must resolve inside the active project. Put -- before a path beginning with a dash.

Scan

/semantic-compressor scan

Scan reports candidates and skipped. It excludes the compressor itself, supporting references, samples, backups, workspaces, symlinks, and files already carrying the v2 marker.

Compress without changing the source

/semantic-compressor compress .claude/skills/my-skill/SKILL.md

The source remains byte-for-byte unchanged. The skill creates a source-bound inventory and candidate below:

.claude/semantic-compressor-work/<workspace-id>/

It then runs deterministic validation and a fresh read-only semantic review. Inspect the reported candidate, hashes, evidence, ratio, and final state before applying.

Apply an accepted candidate

/semantic-compressor apply .claude/skills/my-skill/SKILL.md

apply snapshots the source, candidate, completed inventory, and independent review; validates their bound hashes and per-concept evidence; creates and verifies a backup; writes a manifest; inserts the v2 idempotence marker without changing candidate body indentation; checks for concurrent source edits; and atomically replaces the source. If any gate fails, this run does not replace the source.

Verify an original/candidate pair

/semantic-compressor verify .claude/skills/my-skill/SKILL.md .claude/semantic-compressor-work/<workspace-id>/candidate.md --inventory .claude/semantic-compressor-work/<workspace-id>/inventory.json

Verify is read-only. It reports deterministic preservation separately from semantic judgment and ratio status. A semantically acceptable candidate below the configured ratio is not mislabeled as a successful compression.

Benchmark bundled samples

/semantic-compressor benchmark

Benchmark locates samples relative to the installed skill, not the current project. It reports reproducible line, word, character, byte, hash, and pairing data. The ratio gate uses whitespace-delimited words; these metrics are not Claude tokenizer counts and do not prove semantic equivalence.

Preview and apply a restore

Preview first:

/semantic-compressor restore .claude/backups/<run-id>/manifest.json

Apply only after reviewing the operations:

/semantic-compressor restore .claude/backups/<run-id>/manifest.json --apply

Restore accepts only .claude/backups/<run-id>/manifest.json from the same project root, with the current one-file schema and applied state. It refuses a target changed after compression, a changed file mode, or a backup whose SHA-256 no longer matches the manifest.

Backups and manifests

Successful apply creates:

.claude/backups/<run-id>/
├── manifest.json
└── files/
    └── <project-relative-source-path>

The manifest records the source path, backup path, file mode, project root, compressor version, completed-inventory path/hash, semantic-review path/hash/reviewer, and SHA-256 values before compression, for the validated candidate, and after marker insertion. Backup bytes and the source/candidate/inventory-bound review artifact are verified before source replacement. Reported manifest paths are the authoritative rollback handles; do not move a manifest between project roots or guess a timestamped directory.

Result states

Only PASS, APPLIED, and RESTORED are success states for their respective operations.

Limitations, cost, and privacy

• Semantic Compressor handles Claude Code skill and agent Markdown, not arbitrary documents or source code.
• Symlinks, directories, non-UTF-8 files, and paths outside the active project are rejected.
• The default minimum compression ratio is 2.0:1 by whitespace-delimited words. Already-concise files may correctly return NOT_COMPRESSIBLE.
• Candidate drafting and independent review use model calls. Cost and latency grow with file size and retries, with at most three candidate drafts per file.
• Source, candidate, and inventory content enters the configured Claude Code model context and is processed by your configured provider. Do not use the skill on data that provider is not authorized to receive.
• The local Python control script performs deterministic checks, but conceptual equivalence remains a model judgment. Review evidence before apply.
• The script can verify reviewer attestation and artifact bindings, not the reviewer's actual identity. Claude Code orchestration must assign a genuinely fresh read-only reviewer; a user-fabricated review JSON is outside this trust boundary.
• If a fresh independent reviewer is unavailable, the skill returns REVIEW_REQUIRED and must not apply.
• Workspaces and backups intentionally remain on disk for inspection and rollback. Check git status and your repository ignore policy before committing.

Deterministic control script

The bundled script is useful for diagnostics and CI-style checks:

python3 .claude/skills/semantic-compressor/scripts/semantic_compressor.py --help
python3 .claude/skills/semantic-compressor/scripts/semantic_compressor.py benchmark \
  --samples .claude/skills/semantic-compressor/samples \
  --format markdown

Direct script execution provides deterministic controls only. It does not replace the skill's independent semantic review requirement.

Tests

From the repository root:

python3 -m unittest discover -s tests -v

The suite covers discovery scope, unique project-local workspaces, idempotence markers, symlink-component and backup-path safety, conservative frontmatter validation, completed source-bound inventories, literal failures, source/candidate/inventory-bound reviews, apply races and unknown-byte rollback refusal, strict manifest restore, file modes, and deterministic benchmark edge cases.

Project structure

skills-optimizer/
├── README.md
├── README.zh-TW.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── tests/
│   └── test_semantic_compressor.py
└── .claude/skills/semantic-compressor/
    ├── SKILL.md
    ├── scripts/
    │   └── semantic_compressor.py
    ├── references/
    │   ├── inventory-schema.md
    │   ├── strategies.md
    │   └── examples.md
    └── samples/
        ├── skills/
        ├── agents/
        └── verification/

Contributing

See CONTRIBUTING.md. Behavior changes must include tests; documentation changes affecting commands or safety must update both READMEs.

License

MIT — see LICENSE.