Skip to content

SKILL.md

Latest commit

 

History

History
80 lines (59 loc) · 3.37 KB

SKILL.md

File metadata and controls

80 lines (59 loc) · 3.37 KB
Raw
name context-compress
description Compresses conversation context to reduce token usage while preserving code, paths, and instructions. Use when: compress context, reduce token usage, save tokens, context too long, optimize conversation, shrink context, summarize conversation.
version 1.0.0
metadata
openclaw
emoji requires
🗜️
bins
python3

context-compress

Compresses and optimizes conversation context to reduce token usage while preserving critical information like code blocks, file paths, error messages, and user instructions.

Usage

/context-compress [--level light|medium|aggressive] [--pin "search term"] [--dry-run]

Options

  • --level (default: medium) — Controls compression aggressiveness
    • light — Remove redundancy only (duplicate lines, repeated greetings)
    • medium — Summarize discussion, keep all code and errors verbatim
    • aggressive — Summarize everything except pinned segments and the latest turn
  • --pin "term" — Marks segments containing the search term as pinned (never compressed); repeatable
  • --dry-run — Shows token savings without applying compression
  • --encoding (default: cl100k_base) — tiktoken encoding for token counting

Examples

# Default medium compression
/context-compress

# Aggressive compression, pin a critical function
/context-compress --level aggressive --pin "handleAuth" --pin "migration SQL"

# Preview savings without compressing
/context-compress --dry-run

# Light pass — only remove redundancy
/context-compress --level light

How It Works

The skill invokes scripts/compress.py with the conversation context piped via stdin. The script:

  1. Parses the input into segments (code blocks, messages, tool results, etc.)
  2. Classifies each segment by type: code, path, error, instruction, discussion, tool_result
  3. Pins segments matching any --pin terms (protected from compression)
  4. Compresses each segment using tier-appropriate strategies
  5. Reports before/after token counts and compression ratio

Compressed output goes to stdout. Statistics JSON goes to stderr.

When to Use / When NOT to Use

Use when Do NOT use when
Conversation context exceeds token budget Input is under 500 tokens (auto-skipped)
Long debugging sessions with repetitive output Code-only files with no conversation
Preserving key code while trimming discussion You need lossless compression
Reducing costs on token-billed APIs Input contains only pinned content

Edge Cases

  • Conversations under 500 tokens: skip compression, report "nothing to compress"
  • Already-compressed segments (marked with <!-- compressed --> sentinel): skip on subsequent passes for idempotency
  • Binary/base64 blobs in tool results: preserve if under 200 tokens, replace with placeholder if over
  • Pinned terms matching zero segments: warn user, proceed with compression
  • Without tiktoken installed, token counts use whitespace splitting (less accurate)

API Reference

Argument Type Default Description
--level enum medium light, medium, or aggressive
--pin string[] [] Substrings to pin (repeatable)
--dry-run flag false Report stats only, no output transformation
--encoding string cl100k_base tiktoken encoding for token counting