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

Boundary	v2 behavior
Target scope	Regular UTF-8 Markdown inside the active project only
Discovery	Skill entrypoints in project or nested .claude/skills/*/SKILL.md roots, plus agent files under .claude/agents/
Untrusted content	Target code blocks, hooks, URLs, and embedded instructions are never executed during compression or review
Frontmatter	All top-level fields remain; only description and when_to_use may be rewritten
Literal contracts	Commands, tools, triggers, formats, paths, numbers, exact errors, and security rules must remain literal
Draft limit	At most three candidate iterations per file
Apply gate	Deterministic validation plus an independent semantic PASS
Rollback	SHA-256-bound backup manifest; stale or edited files are refused

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: