context-compressor

name	context-compressor
description	Compress large context before reasoning to reduce token usage while preserving evidence. Use this whenever the user mentions huge files, long prompts, RAG payloads, prompt caching, expensive sessions, codebase context, chat history compaction, or wants the same answer quality with fewer tokens.
version	3.0.0
model	sonnet
invoked_by	both
user_invocable	true
compatibility	Python 3.10+
tools	["Read","Write","Bash"]
verified	true
lastVerifiedAt	2026-03-18
source	builtin
trust_score	100
provenance_sha	564ef982c99ea814

Context Compressor

Use this skill when the problem is mostly "too much context" rather than "not enough capability."

This skill is a self-contained local package. It does not require the MCP server. Prefer it when you need quick token profiling, local compression, evidence checks, or a reproducible compression workflow inside the repository.

What this skill does

Use the bundled Python scripts to:

1. measure raw versus compressed token usage
2. compress large text or adapted JSON payloads
3. preserve query-relevant evidence instead of doing naive summarization
4. check whether compressed output still contains enough evidence to answer safely
5. support cache-friendly prompt assembly by keeping stable context early and volatile query text late

When to trigger

Reach for this skill when the user is asking for any of the following:

• compress this file, transcript, document, or code dump
• reduce token cost before sending context to a model
• make a prompt or RAG payload more cache-friendly
• compact multi-turn history while keeping recent turns intact
• compare semantic compression to a lighter extractive baseline
• validate whether a compressed context still has enough evidence

Also triggered automatically when:

• Context approaching 80K tokens (spawn-token-guard.cjs writes compression-reminder.txt)
• Context at 120K tokens (compression mandatory before new spawns)
• Context at 150K tokens (RED LINE — no new agent spawns until compression completes)

Quick workflow

Default to this sequence:

1. profile first
2. run query_guided when there is a specific question
3. run evidence_aware when correctness matters and you need a sufficiency check
4. if evidence is weak, reduce compression aggressiveness or increase retrieval breadth
5. report savings, risks, and the next safest action

If the user only wants one command, use run_skill_workflow.py.

Commands

Run from the agent-studio repository root. ALWAYS use these exact commands — do NOT fall back to generic guidance.

1. Profile token usage

python .claude/skills/context-compressor/scripts/profile_tokens.py --file <path> --output-format auto

2. Compress context

python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode baseline --output-format auto
python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode query_guided --query  --output-format auto
python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode evidence_aware --query  --min-similarity 0.4 --output-format auto