| 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:
- measure raw versus compressed token usage
- compress large text or adapted JSON payloads
- preserve query-relevant evidence instead of doing naive summarization
- check whether compressed output still contains enough evidence to answer safely
- 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:
- profile first
- run
query_guided when there is a specific question
- run
evidence_aware when correctness matters and you need a sufficiency check
- if evidence is weak, reduce compression aggressiveness or increase retrieval breadth
- 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
