Semantic Compressor

Semantic Compressor

Compress agents and skills while keeping their meaning intact. The core idea: don't trust a smaller file blindly — prove that a fresh read of the compressed version yields the same understanding as the original. A 5-phase loop does exactly that.

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• What to compress — a single named file, or which directory to scan. The auto-scan defaults to .claude/skills/ and .claude/agents/; if those don't exist here, detect where the skills/agents actually live (e.g. skills/, repo root, a SKILL.md you were handed) and confirm the path before scanning.
• Output mode — replace the originals in place (relying on the required backup) or write compressed copies alongside and leave the originals untouched. Default to the safer copy-alongside unless the user asks for in-place replacement.
• How aggressive — the target ratio and info-loss floor (defaults: 2:1 body, 2.5:1 description, 0% loss of triggers/commands/tools). Some files shouldn't be squeezed that hard; confirm if the user wants a different aggressiveness.
• Where working files go — where the intermediate *.original-understanding.yaml / *.compressed.md / *.compressed-understanding.yaml artifacts land (default: alongside the source file).

Subagents & parallelism (opt-in)

By default this skill runs inline in a single context — no subagents, no Workflow fan-out, no claude -p sub-processes — to keep it cheap to run. You read each file yourself, write the understanding extracts yourself, and compare them yourself, all in this one context.

Parallel subagents (or fresh claude -p contexts) can help on large jobs: compressing a whole directory of skills/agents at once, or when you want an independent verification read from a context that has never seen the original (a stricter test of preserved meaning). Before spawning any subagent, Workflow, or claude -p process, stop and ask the user, for example:

> This batch is large ([N skill/agent files]). I can compress and verify them inline here one at a time (cheaper, slower), or fan out [M] parallel subagents — one per file, each verified in its own fresh context (faster, stricter, more tokens). Which do you want?

Spawn subagents/workflows only after an explicit yes. If the user declines or doesn't answer, do the whole job inline.

Workflow: 5-Phase Quality Loop

Run every phase, in order, for each file being compressed.

Phase 1: Capture original understanding

Goal: Pin down what the original file actually conveys, before touching it.

Read the original and answer these four questions:

1. What is the main purpose? (one sentence)
2. What are the key features? (bullet list)
3. What commands/tools are available?
4. What triggers should activate this?

By default, answer them yourself inline and write the result to .original-understanding.yaml as structured YAML.

Opt-in (only after the ask above): hand the file to a fresh context for an independent read —

claude -p "Read this and answer:
1. What is the main purpose? (1 sentence)
2. What are the key features? (bullet list)
3. What commands/tools are available?
4. What triggers should activate this?

Output as structured YAML."

Phase 2: Compress

Goal: Produce the compressed version.

MUST-PRESERVE inventory — the most common failure mode. Roughly two-thirds of files needed a second pass purely because one of these slipped out. List them out of the original before you start cutting:

□ EVERY trigger keyword
□ EVERY command
□ EVERY tool
□ EVERY supported format/type (file formats, output formats, protocols)
□ EVERY feature category (no capability silently dropped)
□ EVERY specific name (databases, languages — never collapse to "etc.")

Compression rules

Frontmatter descriptions:
  - Cut: "This skill/agent provides...", "comprehensive", "advanced"
  - Cut: "Use this when...", "is designed to", "enables users to"
  - Keep: every trigger keyword, file extension, action verb
  - Shape: [Purpose .compressed.md`.

### Phase 3: Capture compressed understanding

**Goal**: Read the compressed file the same way Phase 1 read the original, and see what comes through.

Answer the identical four questions against `.compressed.md` and write the result to `.compressed-understanding.yaml`.

Inline by default. The fresh-context `claude -p` form (opt-in) is more honest here, since a context that never saw the original can't fill gaps from memory — but it costs more tokens, so only use it after the user opts in:

```bash
claude -p "Read this and answer:
1. What is the main purpose? (1 sentence)
2. What are the key features? (bullet list)
3. What commands/tools are available?
4. What triggers should activate this?

Output as structured YAML."

Phase 4: Compare and decide

Goal: Diff the two understanding extracts and rule on whether compression cost any meaning.

Compare .original-understanding.yaml against .compressed-understanding.yaml and answer:

1. Is the purpose identical? (yes/no)
2. Are all key features preserved? (list any missing)
3. Are all commands/tools preserved? (list any missing)
4. Are all triggers preserved? (list any missing)
5. Verdict: PASS or NEEDS_IMPROVEMENT

If NEEDS_IMPROVEMENT, name exactly what to add back. Do this inline; the opt-in claude -p equivalent:

claude -p "Compare these two understanding extracts.

ORIGINAL:

COMPRESSED:

Questions:
1. Is the purpose identical? (yes/no)
2. Are all key features preserved? (list any missing)
3. Are all commands/tools preserved? (list any missing)
4. Are all triggers preserved? (list any missing)
5. Overall: PASS or NEEDS_IMPROVEMENT?

If NEEDS_IMPROVEMENT, specify what to add back."

Decision:

• PASS → Phase 5
• NEEDS_IMPROVEMENT → back to Phase 2 with the specific feedback

Phase 5: Report

Goal: Emit the final comparison.

## 

| Metric | Original | Compressed | Ratio |
|--------|----------|------------|-------|
| Lines | X | Y | X:Y |
| Tokens (est.) | X | Y | X:Y |

### Understanding Comparison
- Purpose: ✓ Preserved
- Features: ✓ All preserved / × Missing: [list]
- Commands: ✓ All preserved / × Missing: [list]
- Triggers: ✓ All preserved / × Missing: [list]

### Quality: PASS ✓ / FAIL ×

---

Quick Commands

| Command | Action | |---------|--------| | /semantic-compressor | Scan the project's .claude/skills/ and .claude/agents/, compress everything | | /semantic-compressor | Run the 5-phase loop on one file | | /semantic-compressor benchmark | Run the 5-phase loop across all bundled samples | | /semantic-compressor verify | Phases 1 + 3 only — measure understanding, no compression |

---

Project Directory Auto-Scan Mode

Triggered by /semantic-compressor with no arguments.

Step 1: Discover

find .claude/skills -name "*.md" -o -name "SKILL.md"
find .claude/agents -name "*.md"

If neither .claude/skills nor .claude/agents exists, don't assume this repo follows that layout — detect where skills/agents actually live (skills/, agents/, repo root, or a single file you were handed) and confirm the target path with the user before scanning.

Step 2: Back up (required)

BACKUP_DIR=".claude/backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r .claude/skills "$BACKUP_DIR/"
cp -r .claude/agents "$BACKUP_DIR/"
echo "✓ Backup created: $BACKUP_DIR"

Step 3: Process each file

By default, walk the discovered files one at a time in this context. If the user opted into subagents (see Subagents & parallelism), you may instead process them in parallel — one subagent per file — and consolidate the results.

For each file:

1. Skip anything already compressed (look for a # Already compressed marker).
2. Run the 5-phase loop.
3. Apply the output mode the user confirmed up front: either replace the original in place (the original is safe in the backup) or write the compressed copy alongside and leave the original untouched. Don't replace in place silently if it wasn't confirmed.
4. Stamp a # Compressed by semantic-compressor on header.

Step 4: Report

## Compression Report

| File | Original | Compressed | Ratio | Iterations | Status |
|------|----------|------------|-------|------------|--------|
| skill-a.md | 500 | 120 | 4.2:1 | 1 | ✓ PASS |
| agent-b.md | 300 | 80 | 3.8:1 | 2 | ✓ PASS |

Total: X files compressed, Y tokens saved
Backup: .claude/backups/YYYYMMDD_HHMMSS/

---

Sample Files

Bundled under samples/ for benchmarking:

samples/
├── skills/
│   ├── verbose/        # Original verbose versions
│   └── compressed/     # Compressed versions
└── agents/
    ├── verbose/        # Original verbose versions
    └── compressed/     # Compressed versions

Never Compress

• Error messages (exact text matters)
• Security instructions
• Code syntax
• Numerical thresholds
• File paths

Quality Thresholds

| Type | Min Ratio | Max Info Loss | |------|-----------|---------------| | Skill description | 2.5:1 | 0% triggers | | Skill body | 2:1 | 0% commands | | Agent | 2:1 | 0% tools |

Below the ratio floor, or any information loss above 0%, marks the file NEEDS_IMPROVEMENT. These are the default floors; if the user confirmed a different aggressiveness up front, use theirs instead.

Deeper References

• references/strategies.md — per-target compression algorithms (descriptions, DICE context, hierarchical output, code, documents) plus retention metrics.
• references/examples.md — worked before/after pairs with measured ratios.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: napnap11
• Source: napnap11/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.