Context Optimize

Context Optimize Skill

> When to use: > - When you need to analyze a long document or codebase > - When the context window is running low > - When you need to synthesize multiple files > - When cleaning up documents before starting a project implementation > - When accumulated search/tool results are polluting the context (v2.0 self-editing)

Quick Start

# Extract key information (Heavy-Hitter)
/compress optimize 

# Compress a document
/compress 

# LLM-based summarization (requires Claude CLI)
/compress  --llm

---

Usage Scenarios

1. Pre-project document cleanup

Situation: Planning docs and specs are too long to read in one pass
Solution:  /compress optimize docs/spec.md --heavy-count=20
Result:    Extract only the top 20 key items for quick understanding

2. Context overload

Situation: "Context window exceeded" or degraded response quality
Solution:  /compress  --summary-ratio=0.3
Result:    70% compression to free up context headroom

3. Synthesizing multiple files

Situation: Need to reference 10+ files at once
Solution:  /compress build "summarize" docs/*.md
Result:    RAG hybrid extracts only relevant content

---

Commands

| Command | Description | Example | |---------|-------------|---------| | optimize | Heavy-Hitter extraction | /compress optimize spec.md | | compress | Compress (preserve start/end) | /compress README.md | | build | RAG hybrid | /compress build "API list" src/*.ts |

Options

| Option | Description | Default | |--------|-------------|---------| | --heavy-count=N | Number of key items to extract | 10 | | --summary-ratio=N | Compression ratio (0.1–0.9) | 0.3 | | --llm | Use LLM-based summarization | false | | --json | Output in JSON format | false |

---

Technical Principles

H2O (Heavy-Hitter Oracle)

Places critical information at the top to mitigate the "Lost in the Middle" phenomenon:

| Type | Priority | Example | |------|----------|---------| | h1 header | 1 | # Title | | Class definition | 1 | class Foo | | h2 header | 2 | ## Section | | Function definition | 2 | function bar() | | Table header | 2 | \| col1 \| col2 \| | | Code block | 3 | `javascript | | List | 4 | - item |

Bonus system:

• Top 10% of document: priority multiplier 0.8x (higher priority)
• Bottom 10% of document: priority multiplier 0.9x
• Critical keywords (CRITICAL, IMPORTANT, 🔥): multiplier 0.5x

Compressive Context

Older or less important content is summarized; recent and critical content is preserved as-is:

[First 5 lines — preserved as-is]
... (compressed) ...
[Middle sampling]
... (compressed) ...
[Last 5 lines — preserved as-is]

LLM Mode (--llm)

Semantic summarization using Claude CLI:

• No additional API cost — subscription only
• Automatically falls back to heuristic when running inside Claude Code

---

How to Run

This skill internally calls contextOptimizer.js:

node project-team/services/contextOptimizer.js   [options]

Examples

# Heavy-Hitter extraction
node project-team/services/contextOptimizer.js optimize docs/spec.md --heavy-count=15 --json

# Compress
node project-team/services/contextOptimizer.js compress large-file.md --summary-ratio=0.2

# LLM-based (run in a separate terminal)
node project-team/services/contextOptimizer.js compress large-file.md --llm

# RAG hybrid
node project-team/services/contextOptimizer.js build "API endpoints" src/*.ts

---

---

Self-Editing Context (v2.0)

> Inspired by Chroma Context-1: > "Model selectively removes irrelevant documents during retrieval to free context capacity." > Context-1 achieves 94.1% prune accuracy with this pattern.

The Problem

During long sessions, tool results accumulate in the conversation:

• Early search results become irrelevant as the task evolves
• Stale file reads pollute context when those files have since been modified
• Debugging output from resolved issues wastes context on solved problems

This is context pollution — the same problem Context-1 solves for retrieval.

/prune — Self-Editing Command

When context feels polluted, run /prune (or /compress prune). The process:

1. SCAN: Review all tool results and file reads in the current conversation
2. CLASSIFY each result:
   - KEEP: Still relevant to the current task
   - STALE: Was relevant but task has moved on
   - NOISE: Was never relevant (wrong search, failed attempt)
3. SUMMARIZE stale/noise items into one-line summaries
4. OUTPUT: A compact context summary replacing the bloated results

Prune Decision Criteria

| Signal | Classification | Action | |--------|---------------|--------| | File read → file was later modified | STALE | Summarize: "read X, since modified" | | Search result → query was refined | STALE | Summarize: "searched X, refined to Y" | | Error output → error was fixed | NOISE | Summarize: "fixed error in X" | | Debugging trace → bug resolved | NOISE | Drop entirely | | Tool result still referenced in current task | KEEP | Preserve as-is | | Recent result (last 3 turns) | KEEP | Preserve as-is |

When to Self-Edit

Proactively suggest /prune when:

• Session has exceeded 20 tool calls
• The same file has been read 3+ times (likely stale earlier reads)
• A search was followed by a more specific search (earlier one is noise)
• Debugging output exists for a resolved issue

Integration with /compact

/prune is lighter than /compact:

• /prune — removes noise from tool results within the active session
• /compact — compresses the entire conversation for a fresh start

Use /prune first. If still overloaded, then /compact.

---

Related Resources

• Service README: project-team/services/README.md
• MCP server: project-team/services/mcp-context-server.js

Source & license

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

• Author: insightflo
• Source: insightflo/claude-impl-tools
• License: MIT

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