context-compression

Implements structured summarization and probe-based evaluation for compressing long agent conversation histories.

Updated Feb 20, 2026
One-click install
npx skills add https://github.com/gtbauke/bj-utils --skill context-compression-gtbauke
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: context-compression
Source: https://github.com/gtbauke/bj-utils/tree/main/.agent/skills/context-compression
Command: npx skills add https://github.com/gtbauke/bj-utils --skill context-compression-gtbauke

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Long-running agent sessions generate millions of tokens of conversation history that exceed context windows, and naive compression loses critical details like file paths, error messages, and decision rationale, forcing costly re-exploration. ## Core Features & Use Cases - Anchored Iterative Summarization: Maintains persistent structured summaries with dedicated sections for session intent, file modifications, decisions, and next steps, merging new content incrementally instead of regenerating from scratch. - Probe-Based Evaluation: Generates recall, artifact, continuation, and decision probes from conversation history and scores responses across six quality dimensions using an LLM judge rubric. - Structured Summarizer Script: The compression_evaluator.py script provides ProbeGenerator, CompressionEvaluator, and StructuredSummarizer classes for end-to-end compression quality checks. - Use Case: A coding agent debugging a 401 error across 178 messages hits the context limit; the skill compresses history into a structured summary preserving the root cause, modified files, and failing tests so work continues without re-reading files. ## Quick Start Ask the agent to compress the current conversation history into a structured summary with sections for session intent, files modified, decisions, and next steps.

Frequently Asked Questions about context-compression

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I compress conversation history without losing file tracking?▼

Use anchored iterative summarization with explicit sections for files modified, files read, and decisions. Summarize only newly truncated spans and merge them into the existing summary rather than regenerating, which prevents cumulative detail loss across compression cycles.

What is the best context compression method for coding agents?▼

Anchored iterative summarization scores highest overall (3.70) with the best accuracy (4.04) for coding agents. Opaque compression achieves the highest ratio (99.3%) but sacrifices interpretability, making it suitable only for short sessions with low re-fetching costs.

How do I evaluate whether compression preserved critical information?▼

Use probe-based evaluation instead of metrics like ROUGE. Generate recall, artifact, continuation, and decision probes from the original history, then score model responses against a six-dimension rubric covering accuracy, artifact trail, and continuity.

When should compression be triggered in an agent session?▼

Trigger at 70-80% context utilization for fixed thresholds, or use a sliding window keeping the last N turns plus a summary. Task-boundary triggers work best when sessions have clear phase transitions like research then implementation.

Why does my agent forget which files it modified after compression?▼

Artifact trail is the weakest dimension across all compression methods, scoring only 2.2-2.5 out of 5. General summarization cannot reliably track files, so implement a separate artifact index or explicit file-state tracking in the agent scaffolding.

What should never be compressed in agent context?▼

Never compress tool definitions, function call schemas, or API specs, since summarizing parameter names destroys the agent's ability to invoke tools. Also protect early turns containing task constraints and preserve code blocks and identifiers verbatim.